Deudas

Una deuda (Debt) es un cargo puntual a un deudor conocido: un importe fijo que se cobra a una persona o entidad identificada, con una fecha de vencimiento y medios de pago configurables. Es el caso de uso más común de la API. Tú indicas quién paga, cuánto y cuándo vence. TapiPay resuelve internamente toda la complejidad (tu organización, las modalidades y los datos internos del sistema de cobranzas) y te devuelve un contrato limpio con la URL de pago lista para compartir.

Cuándo usar una deuda

Deuda

Un cobro único a alguien que conoces: una factura, una cuota, un servicio puntual.

Suscripción

Si el cobro se repite en el tiempo (mensualidades, cuotas).

Liga de pago

Si no conoces al deudor de antemano (donaciones, ventas sueltas).

Crear una deuda

Para crear una deuda necesitas, como mínimo, identificar al deudor, el monto y la fecha de vencimiento. El header opcional Idempotency-Key se usa como externalRequestId de la deuda, y el debtId resultante es debt_<key> (en el ejemplo, debt_INV-2026-001). Si no lo envías, el backend genera el externalRequestId. Ver Idempotencia.

curl --request POST \
  --url 'https://tapipay-facade.homo.tapila.cloud/v2/debts' \
  --header 'x-api-key: TU_API_KEY' \
  --header 'x-authorization-token: TU_TOKEN_TAPI' \
  --header 'Idempotency-Key: INV-2026-001' \
  --header 'Content-Type: application/json' \
  --data '{
    "contactData": {
      "externalClientId": "CLI-00042",
      "name": "Cliente Ejemplo",
      "email": "cliente@example.com"
    },
    "amount": 1500.00,
    "currency": "MXN",
    "dueDate": "2026-07-01",
    "description": "Factura junio 2026"
  }'

Identificar al deudor

Debes enviar uno de estos dos campos (no ambos, no ninguno):

Campo	Cuándo usarlo
`externalClientId`	El deudor ya existe en tu padrón. Si no corresponde a un contacto, la API responde `422 BUSINESS_RULE_VIOLATION` y no se crea nada. Para crear el contacto en el mismo request, usa `contactData`.
`contactData`	Datos del deudor en línea. Si el `externalClientId` no existe, se crea el contacto; si ya existe, se actualiza.

Ver Contactos para el detalle del deudor reutilizable.

Un contacto puede tener más de un identificador. Si lo referencias por uno secundario, la deuda se crea con su identificador principal y contact.externalClientId en la respuesta devuelve ese valor, no el que enviaste.

Campos principales

number

requerido

Monto en pesos, con hasta 2 decimales (mínimo 0.01). Por ejemplo, 1500.50 equivale a $1,500.50 MXN.

string

requerido

Fecha de vencimiento en formato YYYY-MM-DD. Debe ser una fecha de calendario válida (2026-02-30 devuelve 400). No se valida que sea futura.

string

predeterminado:"MXN"

Código de moneda. Valores permitidos: MXN, ARS, PEN, COP, CLP, USD. Default MXN.

string

Descripción visible para el deudor. Debe ser un string (otro tipo devuelve 400).

string

ID de un producto existente en Tapi, con formato prd_<número> (por ejemplo, prd_12985). Otro formato devuelve 400 INVALID_REQUEST. Excluyente con externalProductId (enviar los dos devuelve 400); no crea productos. Ver Productos.

string

Tu identificador de un producto existente. Excluyente con productId; no crea productos. No admite los caracteres ', ", \, ; (400).

boolean

predeterminado:"true"

Habilita pagos parciales. Con true, la deuda pasa a PARTIALLY_PAID hasta saldarse. Solo acepta true o false literal: "true", 1, etc. devuelven 400 con details[].

boolean

predeterminado:"true"

Si es false, la deuda no puede pagarse después del dueDate. Solo acepta true o false literal, igual que allowPartialPayments.

object

Datos propios de tu sistema que quieras guardar en la deuda. Debe ser un objeto plano (un escalar, como un string o un número, devuelve 400) y no puede usar las claves reservadas que TapiPay escribe internamente: description, paymentMethods, productName, externalProductId, debtExpirationDate, overduePayment, allowPartialPayments, recurringDebt, debtReference. Si aparece alguna, la API responde 400 INVALID_REQUEST con details[].field = additionalData.

POST /v2/debts solo acepta estos campos en el body: externalClientId, contactData, amount, currency, dueDate, description, allowOverduePayment, allowPartialPayments, additionalData, productId, externalProductId. Cualquier otro, incluidos autopay, paymentMethods, productName y paymentMethod, devuelve 400 INVALID_REQUEST con el campo en details[].field. Un array JSON en la raíz (sin el sobre { "debts": [...] }) también devuelve 400.

La deuda no declara medio de pago: el cobro automático lo gobierna el medio de pago default que cada usuario registra una sola vez. Referenciar un producto (productId/externalProductId) es lo que activa esa posibilidad. Los campos paymentMethods y autopay aplican solo a suscripciones. Ver Débito automático para el detalle completo.

Nunca envías ni recibes datos internos del sistema (organización, modalidades, generationData). Trabajas solo con conceptos de negocio.

La respuesta

La respuesta de creación y de consulta incluye paymentUrl (la URL lista para compartir con tu deudor; viene en null solo si falla la integración con el portal) y amountPaid (el acumulado pagado). La creación también incluye autopay (si el cobro automático quedó activo) y, cuando es false, el motivo en autopayReason. Si la deuda no referencia un producto, el motivo es NO_PRODUCT. Ver Débito automático.

debtId es siempre debt_ + externalRequestId.
description se devuelve en la creación y en las lecturas (GET /debts/{id}, GET /debts) cuando la deuda tiene una; si no, el campo no viene.
contact.contactId trae el prefijo con_, también cuando el contacto se crea en línea.
Las fechas date-time vienen en UTC con milisegundos y Z. Ver Convenciones de la API.

{
  "data": {
    "debtId": "debt_INV-2026-001",
    "externalRequestId": "INV-2026-001",
    "status": "PENDING",
    "amount": 1500.00,
    "amountPaid": 0,
    "currency": "MXN",
    "dueDate": "2026-07-01",
    "paymentUrl": "https://app.tapipay.la/s/acme-corp/portal/aB3dE5fG7h/debts/payment-methods?externalRequestId=INV-2026-001",
    "createdAt": "2026-06-03T18:10:00.000Z",
    "allowOverduePayment": true,
    "allowPartialPayments": true,
    "description": "Factura junio 2026",
    "contact": {
      "contactId": "con_9aL3kP2m",
      "externalClientId": "CLI-00042",
      "createdInline": true
    },
    "autopay": false,
    "autopayReason": "NO_PRODUCT"
  },
  "requestId": "req_a1b2c3d4e5f6"
}

Deep link de pago

El paymentUrl es un deep link que apunta directo a esa deuda puntual. Es una URL opaca: compártela tal cual con tu deudor, no la parsees ni la construyas a mano (su formato puede cambiar). Las deudas generadas por una suscripción también traen su propio deep link (lo ves en GET /subscriptions/{id}/debts).

Ciclo de vida

Estado	Significado
`PENDING`	Creada, sin pagos.
`PARTIALLY_PAID`	Recibió al menos un pago, pero `amountPaid < amount`.
`PAID`	Saldada por completo. Estado final.
`OVERDUE`	Superó el `dueDate`. Si `allowOverduePayment` es `false`, ya no puede pagarse.
`CANCELLED`	Cancelada manualmente. Estado final.

Consultar y listar

GET /debts/{id} acepta el debtId (debt_...) o el externalRequestId sin prefijo. También devuelve deudas canceladas (status: CANCELLED). GET /debts devuelve tus deudas de la más reciente a la más antigua, paginadas con page y limit (ver Convenciones de la API). No incluye deudas canceladas: para leer una cancelada, usa GET /debts/{id}.

Filtro	Descripción
`status`	`PENDING`, `PARTIALLY_PAID`, `PAID` u `OVERDUE`. Un valor fuera del enum devuelve `400`. Como el listado no incluye canceladas, `CANCELLED` siempre devuelve una lista vacía.
`externalClientId`	Deudas de un deudor.
`externalRequestId`	Una deuda puntual por su llave externa.
`batchId`	Deudas de un lote o de una suscripción.
`minAmount`, `maxAmount`	Rango de monto en pesos: mayores o iguales a `0` y con hasta 2 decimales. `maxAmount` menor a `minAmount` devuelve `400`.
`createdAtFrom`, `createdAtTo`	Rango de fecha de creación. Ver la regla abajo.

Regla de fechas de createdAtFrom y createdAtTo

Aceptan una fecha (YYYY-MM-DD) o un date-time RFC 3339. Otro formato devuelve 400.
Una fecha sola cubre el día UTC completo, incluido en los dos extremos: createdAtFrom=2026-09-24 empieza a las 00:00:00.000Z y createdAtTo=2026-09-24 termina a las 23:59:59.999Z. Con la misma fecha en los dos, obtienes las deudas de ese día.
Un date-time se convierte a UTC y la precisión del filtro es diaria: se incluye el día UTC completo que lo contiene. Un createdAtTo exactamente a las 00:00:00Z no incluye ese día.
Sin createdAtTo, el rango llega hasta hoy. Un createdAtFrom futuro sin createdAtTo devuelve una lista vacía.
createdAtFrom posterior a createdAtTo devuelve 400.

Actualizar y cancelar

Actualizar (PATCH /debts/{id})

Solo se puede actualizar una deuda en estado PENDING. Intentarlo en otro estado, incluida una deuda cancelada, devuelve 422 BUSINESS_RULE_VIOLATION.Campos editables: amount y dueDate. Envía al menos uno: un body vacío o cualquier otro campo devuelve 400 INVALID_REQUEST. dueDate va en formato YYYY-MM-DD y debe ser una fecha de calendario válida. companyCode en el body se toma como contexto, no como campo a modificar.El PATCH no modifica allowPartialPayments. La respuesta trae dueDate como YYYY-MM-DD y amountPaid con el monto pagado actual.

Cancelar (POST /debts/{id}/cancel)

Se puede cancelar una deuda en estado PENDING, PARTIALLY_PAID u OVERDUE. No se puede cancelar una deuda ya PAID o CANCELLED: cancelarla por segunda vez devuelve 422 BUSINESS_RULE_VIOLATION.El endpoint no lleva body (si envías uno, se ignora). La deuda cancelada se sigue leyendo con GET /debts/{id}, pero ya no aparece en GET /debts.

Errores

Además del catálogo general, estas son las causas más comunes de error en los endpoints de deudas y el error.code que devuelve cada una. El error.message es informativo y puede cambiar: decide tu lógica con el status, error.code y error.details[].field, no con el texto.

Endpoint	Causa	Status y `error.code`
`POST /v2/debts`	Campo fuera del contrato, `productId` y `externalProductId` juntos, `productId` sin formato `prd_<número>`, booleano no literal, `description` no string, `additionalData` inválido o array JSON en la raíz	`400 INVALID_REQUEST`
`POST /v2/debts`	`externalClientId` que no corresponde a un contacto	`422 BUSINESS_RULE_VIOLATION`
`POST /v2/debts`	`productId` o `externalProductId` inexistente	`404 RESOURCE_NOT_FOUND`
`GET /debts`	`status` fuera del enum, fechas con formato inválido, `createdAtFrom` posterior a `createdAtTo`, montos negativos o con más de 2 decimales, `maxAmount` menor a `minAmount`	`400 INVALID_REQUEST`
`GET /debts/{id}`, `PATCH /debts/{id}`, `POST /debts/{id}/cancel`	La deuda no existe	`404 RESOURCE_NOT_FOUND`
`PATCH /debts/{id}`	Body vacío, campo no editable, `amount` fuera de rango o `dueDate` que no es una fecha de calendario válida	`400 INVALID_REQUEST`
`PATCH /debts/{id}`	La deuda no está en `PENDING` (incluye canceladas)	`422 BUSINESS_RULE_VIOLATION`
`POST /debts/{id}/cancel`	La deuda no se puede cancelar en su estado actual, incluido cancelarla por segunda vez	`422 BUSINESS_RULE_VIOLATION`
Cualquiera	`companyCode` que no pertenece a tu cliente	`422 RESOLUTION_ERROR`

Algunos mensajes reales, solo como referencia:

Caso	`error.message`
`dueDate` inválida en `PATCH /debts/{id}`	`dueDate is not a valid calendar date.`
Fecha de listado con formato inválido	`createdAtFrom must be a date (YYYY-MM-DD) or an RFC 3339 date-time.`
`createdAtFrom` posterior a `createdAtTo`	`createdAtFrom must be earlier than or equal to createdAtTo.`
`PATCH` sobre una deuda cancelada	`Debt can only be updated in PENDING state. Current state: CANCELLED.`
Segundo cancel	`Debt cannot be cancelled in CANCELLED state.`

Cuando la falla no es de validación, la API conserva el status real en lugar de convertirlo siempre en 500, así que también puedes recibir un 409 RESOURCE_CONFLICT o un 422 BUSINESS_RULE_VIOLATION fuera de los casos de la tabla. Estos errores no traen error.details, porque no señalan un campo puntual de tu payload.

Endpoints

Método	Ruta	Descripción
`POST`	`/v2/debts`	Crear una deuda, o hasta 50 en un request con `{ "debts": [...] }`.
`GET`	`/debts/{id}`	Consultar una deuda por su `debtId` o `externalRequestId`, incluidas las canceladas.
`GET`	`/debts`	Listar deudas con filtros y paginación (sin canceladas).
`PATCH`	`/debts/{id}`	Actualizar una deuda en estado `PENDING`.
`POST`	`/debts/{id}/cancel`	Cancelar una deuda.

Pruébalo en el API Reference

Explora cada endpoint con su playground interactivo.

Empieza aquí

Novedades

Conceptos

Recursos

Portal de pagos

Webhooks

Cuándo usar una deuda

Deuda

Suscripción

Liga de pago

Crear una deuda

Identificar al deudor

Campos principales

La respuesta

Deep link de pago

Ciclo de vida

Consultar y listar

Actualizar y cancelar

Errores

Endpoints

Pruébalo en el API Reference

​Cuándo usar una deuda

Deuda

Suscripción

Liga de pago

​Crear una deuda

​Identificar al deudor

​Campos principales

​La respuesta

​Deep link de pago

​Ciclo de vida

​Consultar y listar

​Actualizar y cancelar

​Errores

​Endpoints

Pruébalo en el API Reference

Cuándo usar una deuda

Crear una deuda

Identificar al deudor

Campos principales

La respuesta

Deep link de pago

Ciclo de vida

Consultar y listar

Actualizar y cancelar

Errores

Endpoints