> ## 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 deudas > Devuelve tus deudas con filtros y paginación. ## OpenAPI ````yaml /api-reference/openapi.yaml get /debts 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: /debts: get: tags: - Debts summary: Listar deudas description: Devuelve tus deudas con filtros y paginación. operationId: listDebts parameters: - name: status in: query schema: $ref: '#/components/schemas/DebtStatus' description: Filtrar por estado - name: externalClientId in: query schema: type: string description: Filtrar por deudor - name: externalRequestId in: query schema: type: string description: Filtrar por llave externa (deuda única) - name: createdAtFrom in: query schema: type: string format: date-time description: Inicio del rango de creación - name: createdAtTo in: query schema: type: string format: date-time description: Fin del rango de creación - name: minAmount in: query schema: type: number description: Monto mínimo en pesos - name: maxAmount in: query schema: type: number description: Monto máximo en pesos - 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 deudas content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Debt' meta: $ref: '#/components/schemas/PaginationMeta' requestId: type: string '401': description: No autenticado content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: DebtStatus: type: string enum: - PENDING - PARTIALLY_PAID - PAID - OVERDUE - CANCELLED Debt: type: object required: - debtId - externalRequestId - status - amount - amountPaid - currency - dueDate - allowOverduePayment - allowPartialPayments - autopay - createdAt properties: debtId: type: string pattern: ^debt_[a-zA-Z0-9]+$ description: ID interno de la deuda (prefijo debt_) externalRequestId: type: string description: > Llave única permanente de la deuda (sin TTL). Igual al header `Idempotency-Key` si se envió, o generada por el backend. Constraint UNIQUE en el OFU: intentar crear con el mismo `externalRequestId` activo devuelve 409 RESOURCE_CONFLICT (no es idempotencia clásica con replay, sino rechazo de duplicado). status: $ref: '#/components/schemas/DebtStatus' amount: type: number description: Monto total en pesos (hasta 2 decimales) amountPaid: type: number description: Monto pagado acumulado en pesos (hasta 2 decimales) currency: $ref: '#/components/schemas/Currency' dueDate: type: string format: date description: type: string description: Descripción, si fue enviada allowOverduePayment: type: boolean allowPartialPayments: type: boolean autopay: type: boolean paymentMethods: type: array items: $ref: '#/components/schemas/PaymentMethod' description: Medios de pago habilitados para esta deuda paymentUrl: type: string format: uri nullable: true description: >- URL pública del portal de pago. Comportamiento según configuración privateLinks del biller. Con privateLinks habilitado: URL opaca `https://app.tapipay.la/s/{slug}/portal/{shortCode}/` (shortCode anti-enumeración, NO expone identidad del deudor). Puede llevar ?externalRequestId= para deep-linking a esta deuda específica. Puede ser null si falla la integración. Con privateLinks deshabilitado: URL legacy `https://app.tapipay.la/s/{slug}/portal/{identifierValue}/` (identifierValue = externalClientId con PII). Puede llevar ?externalRequestId= para deep-linking. Deep-linking solo aplica a deudas INDIVIDUALES. Ver ADR-007 para detalles. contact: $ref: '#/components/schemas/ContactWithInline' description: Datos del contacto resuelto o creado inline product: $ref: '#/components/schemas/ProductWithInline' description: Datos del producto si se asoció createdAt: type: string format: date-time 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 Currency: type: string enum: - MXN - ARS - PEN - COP - CLP - USD default: MXN description: > Código de moneda ISO 4217. Whitelist de monedas aceptadas por la Facade. Si no se envía, se usa el default de la organización (fallback: MXN). Si se envía un valor fuera de este whitelist, la Facade devuelve 400 INVALID_REQUEST. PaymentMethod: type: string enum: - CASH - CARD - TRANSFER - WALLET - BANK_TRANSFER ContactWithInline: type: object required: - contactId - externalClientId - createdInline 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 createdInline: type: boolean description: > Indica si el contacto fue creado inline en esta operación. NOTA: Este es un embedded thin contact (no incluye name/email/phones/active/updatedAt del contacto completo). Para obtener datos completos del contacto, consultá GET /contacts/{id}. ProductWithInline: type: object required: - productId - name - active - createdInline properties: productId: type: string description: ID del producto en el OFU (sin prefijo prod_) name: type: string description: Nombre del producto active: type: boolean description: Estado del producto createdInline: type: boolean description: Indica si el producto fue creado inline en esta operación 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... ````