Skip to main content
Estas reglas aplican a todos los recursos de la API. Las páginas de cada recurso solo mencionan las excepciones.

​
IDs en el path

Los endpoints que reciben un {id} en el path aceptan el ID público con prefijo o el valor sin prefijo: Un ID que no corresponde a ningún recurso devuelve 404 RESOURCE_NOT_FOUND. En productos, un prefijo distinto de prd_ o un valor no numérico también devuelve 404.
Guarda y usa siempre el ID con prefijo que te devuelve la API: es el que aparece en todas las respuestas.

​
companyCode

Si tu cliente tiene una sola company, no necesitas enviar companyCode: se resuelve desde tu token. Si tiene varias companies, indica en cuál operas con companyCode, como query param (?companyCode=MX-S-04937) o en el cuerpo de un POST o PATCH:
  • Si no lo envías, la API responde 400 BAD_REQUEST pidiéndolo.
  • Si envías un código que no es una company de tu cliente, la API responde 422 RESOLUTION_ERROR.
  • En los PATCH (contactos, productos, ligas de pago, suscripciones y deudas), companyCode en el cuerpo se toma como contexto: no se considera un campo a modificar ni se rechaza como campo no editable.

​
JSON malformado

Un cuerpo que no es JSON válido devuelve 400 INVALID_REQUEST:
400 JSON malformado

​
Paginación

Los listados reciben page y limit como query params y devuelven los resultados en data junto con un objeto meta: Los valores inválidos de page o limit no devuelven error: toman el default. meta.limit refleja el valor que se aplicó.
Solo GET /payment-links agrega meta.capped: vale true cuando meta.total es aproximado porque se alcanzó el máximo de ítems que el servicio recorre. Los demás listados no traen ese campo.

​
Fechas

  • Los campos date-time de las respuestas (createdAt, updatedAt, expiresAt, etc.) vienen siempre en UTC con milisegundos y Z: 2026-09-24T17:38:21.107Z.
  • Los campos de fecha (dueDate, startDate, endDate) usan YYYY-MM-DD y deben ser fechas de calendario válidas (2026-02-30 devuelve 400).
  • Los date-time que envías (por ejemplo expiresAt de una liga) deben ser RFC 3339, con Z u offset (2026-12-31T23:59:59-06:00). Se convierten y guardan en UTC, y se devuelven en UTC aunque los hayas enviado con offset.
  • Los filtros createdAtFrom y createdAtTo de los listados aceptan fecha (YYYY-MM-DD) o date-time RFC 3339. Una fecha sola cubre el día UTC completo, incluido en los dos extremos. El detalle de cada listado está en Deudas y Ligas de pago.

​
Tipos estrictos

La API no convierte tipos: cada campo debe llegar con el tipo que declara el contrato.
  • Booleanos: solo aceptan true o false literal. "true", 1, "yes", etc. devuelven 400 INVALID_REQUEST con una entrada en details[] por cada campo. Aplica a allowOverduePayment y allowPartialPayments en POST /v2/debts, a autopay, allowOverduePayment, allowPartialPayments y enforcePaymentOrder en POST /subscriptions, y a los booleanos editables de PATCH /subscriptions/{id}. El query param active de GET /products también acepta solo true o false.
  • description: debe ser un string. Otro tipo devuelve 400.
  • Montos: números en pesos con hasta 2 decimales.
400 Booleano no literal

​
additionalData

additionalData guarda datos propios de tu sistema junto al cobro. Se acepta en POST /v2/debts, POST /payment-links y POST/PATCH /subscriptions, y se persiste en la deuda (en una liga, en la deuda asociada a la liga; en una suscripción, en las deudas que genera).
  • Debe ser un objeto plano. Un escalar (string, número o booleano) devuelve 400 INVALID_REQUEST.
  • No puede usar claves reservadas, que TapiPay escribe internamente: description, paymentMethods, productName, externalProductId, debtExpirationDate, overduePayment, allowPartialPayments, recurringDebt y debtReference. Si aparece alguna, la API responde 400 INVALID_REQUEST con details[].field = "additionalData".
Válido

​
Campos no declarados

  • En POST /v2/debts y en todos los PATCH, un campo que no está en el contrato devuelve 400 INVALID_REQUEST. En POST /v2/debts el campo viene en details[].field.
  • En POST /contacts, POST /products, POST /payment-links y POST /subscriptions, los campos no declarados se ignoran.

​
Errores de validación

Los errores de validación devuelven 400 INVALID_REQUEST con un details[] que indica cada campo que falló y por qué. Usa details[].field para mostrar a tu usuario qué corregir, y no dependas del texto de message ni de issue: son informativos y pueden cambiar. En el modo lote de POST /v2/debts, cada entrada de details[] trae también index (posición del item en debts) y externalRequestId. Ver Manejo de errores.