> ## 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 links de pago > Devuelve tus links de pago con filtros y paginación. ## OpenAPI ````yaml /api-reference/openapi.yaml get /payment-links 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: /payment-links: get: tags: - Payment Links summary: Listar links de pago description: Devuelve tus links de pago con filtros y paginación. operationId: listPaymentLinks parameters: - name: status in: query schema: $ref: '#/components/schemas/PaymentLinkStatus' description: Filtrar por estado (ACTIVE, PAID, EXPIRED, CANCELLED) - name: externalPaymentLinkId in: query schema: type: string description: Filtrar por llave externa exacta - name: createdAtFrom in: query schema: type: string format: date-time description: Inicio del rango de creación (ISO 8601) - name: createdAtTo in: query schema: type: string format: date-time description: Fin del rango de creación (ISO 8601) - 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 links de pago content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/PaymentLink' meta: $ref: '#/components/schemas/PaginationMeta' requestId: type: string '401': description: No autenticado content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: PaymentLinkStatus: type: string enum: - ACTIVE - PAID - EXPIRED - CANCELLED PaymentLink: type: object required: - paymentLinkId - status - amount - currency - description - singleUse - createdAt - paymentUrl properties: paymentLinkId: type: string pattern: ^plk_[a-zA-Z0-9]+$ description: ID interno del PaymentLink (prefijo plk_) externalPaymentLinkId: type: string description: Llave externa del link (única por organización) status: $ref: '#/components/schemas/PaymentLinkStatus' description: Estado del link (ACTIVE, PAID, EXPIRED, CANCELLED) amount: type: number description: Monto en pesos (hasta 2 decimales, inmutable tras creación) currency: $ref: '#/components/schemas/Currency' description: Moneda del link (inmutable tras creación) description: type: string description: Descripción visible en la página de pago (actualizable) singleUse: type: boolean description: Si true, se desactiva tras el primer pago (inmutable tras creación) expiresAt: type: string format: date-time nullable: true description: > Fecha/hora de expiración (ISO 8601, RFC3339). Null si no expira. Actualizable, pero solo a valores futuros válidos. successUrl: type: string format: uri nullable: true description: URL de redirección post-pago exitoso (inmutable tras creación) metadata: type: object description: Metadatos arbitrarios (actualizable) paymentUrl: type: string format: uri nullable: true description: > URL pública del portal de pago. Comportamiento HÍBRIDO según deudor conocido o no: **SIN DEUDOR CONOCIDO (anónimo/reutilizable):** - Si privateLinks=true (default): URL opaca con shortCode anti-enumeración: `https://app.tapipay.la/s/{slug}/portal/{shortCode}/` donde shortCode no expone identidad. Null si falla integración. - Si privateLinks=false (legacy): URL con identifierValue (PII si es externalClientId): `https://app.tapipay.la/s/{slug}/portal/{identifierValue}/` donde identifierValue = sanitized org name prefix + random (ej. acm-x3kM9pQr). Null si falla. **CON DEUDOR CONOCIDO (externalClientId o contactData):** - Si privateLinks=true: URL opaca con shortCode: `https://app.tapipay.la/s/{slug}/portal/{shortCode}/` (no expone PII del deudor). Null si falla. - Si privateLinks=false: URL legacy con identifierValue = externalClientId (PII): `https://app.tapipay.la/s/{slug}/portal/{externalClientId}/` Null si falla. identifierValue: type: string nullable: true description: > **SOLO PARA LINKS SIN DEUDOR CONOCIDO (anónimo/reutilizable).** Null/omitido para links con deudor conocido (PII-safe). Identificador sintético usado como último segmento de `paymentUrl` (cuando privateLinks=false). Patrón: {primeras 3 letras sanitizadas del nombre org}-{random alfanumérico ≥8} Ejemplo: acm-x3kM9pQr Generación: se normaliza org name (diacríticos→ASCII, no-alfanuméricos→eliminados, lowercase), se toman primeras 3 letras; si quedan <3, se usa fallback "lnk". Ver ADR-006 y BR-007 para edge cases. contact: $ref: '#/components/schemas/ContactWithInline' nullable: true description: > (no implementado en v1, reservado para v2) Contacto resuelto o creado inline (si fue proporcionado externalClientId o contactData). Null en v1. product: $ref: '#/components/schemas/ProductWithInline' nullable: true description: > Producto asociado si fue referenciado en creación (via productName). Se resuelve o crea inline igual que en Debt y Subscription. Null si no se especificó producto. createdAt: type: string format: date-time description: Timestamp de creación (ISO 8601, RFC3339) 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. 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... ````