> ## Documentation Index
> Fetch the complete documentation index at: https://devs.tapipay.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar contactos

> Devuelve tus contactos con filtros y paginación.



## OpenAPI

````yaml /api-reference/openapi.yaml get /contacts
openapi: 3.0.0
info:
  title: TapiPay Facade API
  version: 1.0.0
  description: >
    Facade API pública de la plataforma de cobranzas TapiPay.  Ofrece un
    contrato limpio y desacoplado del modelo interno del OFU,  permitiendo a los
    clientes crear y gestionar cobros (deudas puntuales,  suscripciones
    recurrentes, links de pago, productos y contactos)  sin conocer detalles
    internos de Company, Modalities o GenerationData.
  contact:
    name: TapiPay Team
    url: https://www.tapipay.com
  license:
    name: Proprietary
servers:
  - url: https://tapipay-facade.dev.tapila.cloud
    description: Desarrollo
security:
  - apiKeyAuth: []
    tapiAuth: []
paths:
  /contacts:
    get:
      tags:
        - Contacts
      summary: Listar contactos
      description: Devuelve tus contactos con filtros y paginación.
      operationId: listContacts
      parameters:
        - name: name
          in: query
          schema:
            type: string
          description: Búsqueda parcial por nombre
        - name: email
          in: query
          schema:
            type: string
          description: Filtrar por email exacto
        - name: phone
          in: query
          schema:
            type: string
          description: Filtrar por número de teléfono
        - name: identifier
          in: query
          schema:
            type: string
          description: Filtrar por identifier del deudor
        - name: externalClientId
          in: query
          schema:
            type: string
          description: Filtrar por llave externa exacta
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 500
      responses:
        '200':
          description: Lista de contactos
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
                  requestId:
                    type: string
        '401':
          description: No autenticado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Contact:
      type: object
      required:
        - contactId
        - externalClientId
        - name
        - email
        - phones
        - active
        - createdAt
        - updatedAt
      properties:
        contactId:
          type: string
          pattern: ^con_[a-zA-Z0-9]+$
          description: ID interno del contacto (prefijo con_)
        externalClientId:
          type: string
          description: Llave natural del contacto
        name:
          type: string
          description: Nombre del deudor
        email:
          type: string
          format: email
          description: Email del deudor
        phones:
          type: array
          description: Lista de teléfonos del deudor
          items:
            $ref: '#/components/schemas/Phone'
        active:
          type: boolean
          description: Estado activo del contacto
        createdAt:
          type: string
          format: date-time
          description: Timestamp de creación (ISO 8601)
        updatedAt:
          type: string
          format: date-time
          description: Timestamp de última actualización (ISO 8601)
    PaginationMeta:
      type: object
      required:
        - page
        - limit
        - total
        - hasMore
      properties:
        page:
          type: integer
          minimum: 1
        limit:
          type: integer
          minimum: 1
          maximum: 500
        total:
          type: integer
          minimum: 0
        hasMore:
          type: boolean
        capped:
          type: boolean
          description: >
            Indica si el total está truncado por cap interno. Cuando es true, la
            cantidad exacta de resultados no se puede determinar (el cursor fue
            alcanzado antes de iterar  toda la colección). El cliente debe
            asumir que hasMore puede seguir siendo true incluso si llega a este
            límite. Se usa para prevenir queries scans costosos.
          default: false
    Error:
      type: object
      required:
        - error
        - requestId
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - INVALID_REQUEST
                - AUTHENTICATION_FAILED
                - RESOURCE_NOT_FOUND
                - RESOURCE_CONFLICT
                - RESOLUTION_ERROR
                - BUSINESS_RULE_VIOLATION
                - RATE_LIMITED
                - INTERNAL_ERROR
              description: Código de error estándar
            message:
              type: string
              description: Mensaje legible del error
            details:
              type: array
              description: Array de detalles adicionales (validaciones por campo, etc.)
              items:
                type: object
                properties:
                  field:
                    type: string
                  issue:
                    type: string
        requestId:
          type: string
          pattern: ^req_[a-zA-Z0-9]+$
          description: ID único del request para trazabilidad
    Phone:
      type: object
      required:
        - number
        - type
      properties:
        number:
          type: string
          description: Número de teléfono. Ej +5215512345678
        type:
          $ref: '#/components/schemas/PhoneType'
        primary:
          type: boolean
          default: false
          description: >
            Indica si es el número telefónico principal. Opcional (default:
            false). El facade mapea a OFU.
        description:
          type: string
          description: >
            Descripción o etiqueta del teléfono. Opcional (default: type cuando
            no se especifica). El facade mapea a OFU.
    PhoneType:
      type: string
      enum:
        - MAIN
        - MOBILE
        - WORK
        - RELATIVE
        - OTHER
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >
        API key del API Gateway de Tapi. Requerida en todas las operaciones.
        Distinta por ambiente (desarrollo, homologación, producción).
    tapiAuth:
      type: apiKey
      in: header
      name: x-authorization-token
      description: >
        Token TAPI JWT. Requerido en todas las operaciones. Se envía sin prefijo
        "Bearer". Ej: x-authorization-token: eyJhbGci...

````