> ## 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.

# Deudas

> Cobra un monto puntual a un deudor conocido con la TapiPay Facade API.

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 que **siempre** incluye la URL de pago.

## Cuándo usar una deuda

<CardGroup cols={3}>
  <Card title="Deuda" icon="file-invoice-dollar">
    Un cobro único a alguien que conoces: una factura, una cuota, un servicio puntual.
  </Card>

  <Card title="Suscripción" icon="arrows-rotate" href="/es/recursos/suscripciones">
    Si el cobro se repite en el tiempo (mensualidades, cuotas).
  </Card>

  <Card title="Liga de pago" icon="link" href="/es/recursos/ligas-de-pago">
    Si no conoces al deudor de antemano (donaciones, ventas sueltas).
  </Card>
</CardGroup>

## Crear una deuda

Para crear una deuda necesitas, como mínimo, identificar al deudor, el monto y la fecha de vencimiento.

```bash theme={null}
curl --request POST \
  --url 'https://tapipay-facade.dev.tapila.cloud/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",
    "paymentMethods": ["CASH", "CARD"]
  }'
```

### 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 existe, la API responde `422 BUSINESS_RULE_VIOLATION`.                  |
| `contactData`      | Datos del deudor en línea. Si el `externalClientId` no existe, se crea el contacto; si ya existe, se actualiza. |

Ver [Contactos](/es/recursos/contactos) para el detalle del deudor reutilizable.

### Campos principales

<ResponseField name="amount" type="number" required>
  Monto en **pesos**, con hasta 2 decimales (mínimo `0.01`). Por ejemplo, `1500.50` equivale a \$1,500.50 MXN.
</ResponseField>

<ResponseField name="dueDate" type="string" required>
  Fecha de vencimiento en formato `YYYY-MM-DD`.
</ResponseField>

<ResponseField name="currency" type="string">
  Código de moneda. Valores permitidos: `MXN`, `ARS`, `PEN`, `COP`, `CLP`, `USD`. Si no lo envías, se usa el default de tu organización (con respaldo en `MXN`).
</ResponseField>

<ResponseField name="productName" type="string">
  Nombre de un producto para categorizar el cobro. Si no existe, se crea en línea; si ya existe, se reutiliza. Ver [Productos](/es/recursos/productos).
</ResponseField>

<ResponseField name="allowPartialPayments" type="boolean" default="true">
  Habilita pagos parciales. Con `true`, la deuda pasa a `PARTIALLY_PAID` hasta saldarse.
</ResponseField>

<ResponseField name="allowOverduePayment" type="boolean" default="true">
  Si es `false`, la deuda no puede pagarse después del `dueDate`.
</ResponseField>

<ResponseField name="autopay" type="boolean" default="false">
  Domiciliación. No puede coexistir con `paymentMethods`. Ver [Medios de pago](/es/conceptos/medios-de-pago).
</ResponseField>

<ResponseField name="paymentMethods" type="array">
  Medios habilitados para esta deuda: `CASH`, `CARD`, `TRANSFER`, `WALLET`, `BANK_TRANSFER`. Solo válido cuando `autopay` es `false`.
</ResponseField>

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

## La respuesta

La respuesta de creación y de consulta **siempre** incluye `paymentUrl` (la URL lista para compartir con tu deudor) y `amountPaid` (el acumulado pagado).

```json theme={null}
{
  "data": {
    "debtId": "debt_1xY7zR4p",
    "externalRequestId": "INV-2026-001",
    "status": "PENDING",
    "amount": 1500.00,
    "amountPaid": 0,
    "currency": "MXN",
    "dueDate": "2026-07-01",
    "description": "Factura junio 2026",
    "allowOverduePayment": true,
    "allowPartialPayments": true,
    "autopay": false,
    "paymentMethods": ["CASH", "CARD"],
    "paymentUrl": "https://app.tapipay.la/s/acme-corp/portal/CLI-00042/?externalRequestId=INV-2026-001",
    "contact": {
      "contactId": "con_9aL3kP2m",
      "externalClientId": "CLI-00042",
      "createdInline": true
    },
    "createdAt": "2026-06-03T18:10:00Z"
  },
  "requestId": "req_a1b2c3d4"
}
```

### Deep link de pago

El `paymentUrl` es un **deep link**: incluye el `externalRequestId` de la deuda como query param (`?externalRequestId=...`), así apunta directo a **esa** deuda puntual. Compártelo tal cual con tu deudor; no necesitas construir la URL a mano. Las deudas generadas por una [suscripción](/es/recursos/suscripciones) también traen su propio deep link (lo ves en `GET /subscriptions/{id}/debts`).

## Ciclo de vida

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING
    PENDING --> PARTIALLY_PAID: pago parcial
    PENDING --> PAID: pago total
    PENDING --> OVERDUE: vence el dueDate
    PENDING --> CANCELLED: cancelación
    PARTIALLY_PAID --> PAID: se completa el total
    PARTIALLY_PAID --> CANCELLED: cancelación
    OVERDUE --> PAID: pago tardío (si allowOverduePayment)
    OVERDUE --> CANCELLED: cancelación
    PAID --> [*]
    CANCELLED --> [*]
```

| 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.                                           |

## Actualizar y cancelar

<AccordionGroup>
  <Accordion title="Actualizar (PATCH /debts/{id})">
    Solo se puede actualizar una deuda en estado `PENDING`. Intentarlo en otro estado devuelve `422 BUSINESS_RULE_VIOLATION`.

    Campos editables: `amount`, `dueDate`. Enviar cualquier otro campo devuelve `400 INVALID_REQUEST`.
  </Accordion>

  <Accordion title="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` (devuelve `422 BUSINESS_RULE_VIOLATION`).
  </Accordion>
</AccordionGroup>

## Endpoints

| Método  | Ruta                 | Descripción                               |
| ------- | -------------------- | ----------------------------------------- |
| `POST`  | `/debts`             | Crear una deuda.                          |
| `GET`   | `/debts/{id}`        | Consultar una deuda por su `debtId`.      |
| `GET`   | `/debts`             | Listar deudas con filtros y paginación.   |
| `PATCH` | `/debts/{id}`        | Actualizar una deuda en estado `PENDING`. |
| `POST`  | `/debts/{id}/cancel` | Cancelar una deuda.                       |

<Card title="Pruébalo en el API Reference" icon="play" href="/api-reference">
  Explora cada endpoint con su playground interactivo.
</Card>