> ## 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. # Crear deuda > Cobra un monto puntual a un deudor conocido. Devuelve la deuda con su paymentUrl lista para compartir. ## OpenAPI ````yaml /api-reference/openapi.yaml post /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: post: tags: - Debts summary: Crear deuda description: >- Cobra un monto puntual a un deudor conocido. Devuelve la deuda con su paymentUrl lista para compartir. operationId: createDebt parameters: - name: Idempotency-Key in: header schema: type: string description: > Clave de idempotencia (opcional). Se usa como llave única (`externalRequestId`) de la deuda. El `externalRequestId` es una llave **permanente** sin TTL (constraint UNIQUE en el OFU). Si el cliente envía `Idempotency-Key`, su valor se devuelve como `externalRequestId` en la response. Una request repetida con la misma key devuelve **error 409 RESOURCE_CONFLICT** (no es replay/idempotencia clásica; es rechazo de duplicado por constraint UNIQUE). Si no se envía, el backend genera un `externalRequestId` único. Ver ADR-004 v1.1 para detalles de semántica. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DebtCreateRequest' responses: '201': description: Deuda creada content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Debt' requestId: type: string '400': description: Validación fallida content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: No autenticado content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Recurso referenciado no encontrado content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- externalRequestId ya existe (constraint UNIQUE permanente; duplicado rechazado, ver ADR-004 v1.1) content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: Error de resolución o violación de regla de negocio content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: DebtCreateRequest: type: object required: - amount - dueDate properties: externalClientId: type: string description: > Identificador del deudor (externalClientId o contactData, no ambos). Si contactData no se envía, este campo es obligatorio. contactData: $ref: '#/components/schemas/ContactInput' description: > Datos completos del deudor inline. Si se envía, externalClientId no se permite. Alternativa a externalClientId. amount: type: number minimum: 0.01 multipleOf: 0.01 description: Monto en pesos (hasta 2 decimales, mínimo 0.01) currency: $ref: '#/components/schemas/Currency' description: Código de moneda ISO 4217 (MXN, ARS, PEN, COP, CLP, USD) dueDate: type: string format: date description: Fecha de vencimiento (YYYY-MM-DD) description: type: string description: Descripción visible al deudor (opcional) productName: type: string description: > Nombre del producto a asociar (opcional). Se resuelve por name en el OFU o se crea inline si no existe. Identificado por name único por companyCode. allowOverduePayment: type: boolean default: true description: Si false, no se puede pagar después del dueDate allowPartialPayments: type: boolean default: true description: Habilita pagos parciales autopay: type: boolean default: false description: > Si true, la deuda se cobrará vía débito automático. No puede coexistir con paymentMethods. paymentMethods: type: array items: $ref: '#/components/schemas/PaymentMethod' description: | Medios de pago habilitados. Solo válido cuando autopay=false. additionalData: type: object description: Escape hatch para datos adicionales 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 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 ContactInput: type: object required: - externalClientId - name - email properties: externalClientId: type: string description: Llave natural del contacto. Única por organización. name: type: string description: Nombre del deudor email: type: string format: email description: Email del deudor (requerido) phones: type: array description: Lista de teléfonos del deudor (opcional) items: $ref: '#/components/schemas/Phone' 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 DebtStatus: type: string enum: - PENDING - PARTIALLY_PAID - PAID - OVERDUE - CANCELLED 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 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... ````