Platica
Crear API key

Obligaciones

Una obligación es dinero que debes o que te deben, con su calendario de cuotas: un préstamo, una compra a crédito o una venta fiada.

Tipos y estados

Dirección y tipo

PAYABLEdirection
Lo debes tú. Tipos: BORROWED_MONEY (préstamo recibido) o CREDIT_PURCHASE (compra a crédito).
RECEIVABLEdirection
Te lo deben. Tipos: LENT_MONEY (préstamo entregado) o CREDIT_SALE (venta a crédito).

Estado de la obligación (status)

PENDINGstatus
Sin pagos todavía.
PARTIALLY_SETTLEDstatus
Con pagos, sin cuotas vencidas.
OVERDUEstatus
Alguna cuota venció sin pagarse completa.
SETTLEDstatus
Todas las cuotas pagadas.
CANCELEDstatus
Cancelada. Ya no admite pagos.

Cada cuota tiene su propio estado: PENDING, UPCOMING (la próxima), PARTIAL, PAID u OVERDUE. Los estados se calculan con la fecha de Caracas.

El objeto obligación

Campos principales

iduuid
Identificador.
direction, kindstring
Dirección y tipo, ver arriba.
counterpartystring
Con quién: persona o comercio.
totalAmountMinorinteger
Total en céntimos.
totalSettledMinorinteger
Pagado o cobrado hasta ahora.
outstandingMinorinteger
Lo que falta.
currencystring
Moneda. Coincide con la de la cuenta predeterminada.
defaultAccountIduuid
Cuenta donde caen los pagos si no indicas otra.
originDatedate
Fecha de origen, AAAA-MM-DD.
statusstring
Estado calculado.
installmentsobject[]
Cuotas: dueDate, amountMinor, appliedMinor, remainingMinor, status.
settlementsobject[]
Pagos o cobros, con cómo se repartieron entre cuotas (allocations).
eventsobject[]
Historial de cambios, del más reciente al más antiguo.
nextInstallmentobject | null
La próxima cuota por pagar.
archivedAt, canceledAtdatetime | null
Si está archivada o cancelada.

Listar obligaciones

GET/obligations

Plan: ProPermiso de la key: Solo lectura o superior

Lista paginada, de la más reciente a la más antigua.

Parámetros de consulta

pageinteger
Página, desde 1.
limitinteger
Por página. Por defecto 20, máximo 100.
directionstring
PAYABLE o RECEIVABLE.
statusesstring
Estados separados por coma, por ejemplo OVERDUE,PENDING.
kindsstring
Tipos separados por coma.
searchstring
Busca en contraparte, descripción y notas.
dueFrom, dueTodate
Con alguna cuota en ese rango, AAAA-MM-DD.
archivedboolean
Por defecto false: solo las no archivadas.
updatedSincedatetime
Solo las modificadas desde esa fecha, archivadas o no.
curl "https://api.tuplatica.app/api/platica/obligations?direction=PAYABLE&statuses=OVERDUE,PENDING" \
  -H "Authorization: Bearer $PLATICA_API_KEY"

Respuesta 200

{
  "data": [
    "… obligaciones como la de abajo …"
  ],
  "total": 4,
  "page": 1,
  "limit": 20,
  "hasMore": false
}

Resumen por moneda

GET/obligations/summary

Plan: ProPermiso de la key: Solo lectura o superior

Por cada moneda: cuánto debes, cuánto te deben, cuántas están vencidas y la próxima de cada lado.

curl "https://api.tuplatica.app/api/platica/obligations/summary" \
  -H "Authorization: Bearer $PLATICA_API_KEY"

Respuesta 200

[
  {
    "currency": "USD",
    "payableOutstandingMinor": 40000,
    "receivableOutstandingMinor": 15000,
    "overdueCount": 0,
    "nextPayable": "… obligación …",
    "nextReceivable": null
  }
]

Consultar una obligación

GET/obligations/:id

Plan: ProPermiso de la key: Solo lectura o superior

Devuelve la obligación completa con cuotas, pagos e historial. Todas las acciones de esta página responden con este mismo objeto.

curl "https://api.tuplatica.app/api/platica/obligations/2f4a6c8e-0b2d-4f6a-8c0e-2b4d6f8a0c2e" \
  -H "Authorization: Bearer $PLATICA_API_KEY"

Respuesta 200

{
  "id": "2f4a6c8e-0b2d-4f6a-8c0e-2b4d6f8a0c2e",
  "direction": "PAYABLE",
  "kind": "CREDIT_PURCHASE",
  "counterparty": "Tienda de electrodomésticos",
  "description": "Nevera",
  "notes": null,
  "totalAmountMinor": 60000,
  "totalSettledMinor": 20000,
  "outstandingMinor": 40000,
  "currency": "USD",
  "defaultAccountId": "0d9a4b7e-3c21-4e6f-8a5b-1f2e3d4c5b6a",
  "categoryId": "expense-shopping",
  "categorySource": "automatic",
  "originDate": "2026-09-15",
  "status": "PARTIALLY_SETTLED",
  "wasRescheduled": false,
  "canceledAt": null,
  "cancellationReason": null,
  "archivedAt": null,
  "originMovementId": null,
  "installments": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "position": 1,
      "dueDate": "2026-10-15",
      "amountMinor": 20000,
      "appliedMinor": 20000,
      "remainingMinor": 0,
      "status": "PAID",
      "wasRescheduled": false,
      "plannedMovementId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
    },
    {
      "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "position": 2,
      "dueDate": "2026-11-15",
      "amountMinor": 20000,
      "appliedMinor": 0,
      "remainingMinor": 20000,
      "status": "UPCOMING",
      "wasRescheduled": false,
      "plannedMovementId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
    },
    {
      "id": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f",
      "position": 3,
      "dueDate": "2026-12-15",
      "amountMinor": 20000,
      "appliedMinor": 0,
      "remainingMinor": 20000,
      "status": "PENDING",
      "wasRescheduled": false,
      "plannedMovementId": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f"
    }
  ],
  "settlements": [
    {
      "id": "d4e5f6a7-b8c9-4d0e-8f2a-3b4c5d6e7f80",
      "kind": "REAL",
      "amountMinor": 20000,
      "occurredAt": "2026-10-15T14:00:00.000Z",
      "note": null,
      "accountId": "0d9a4b7e-3c21-4e6f-8a5b-1f2e3d4c5b6a",
      "movementId": "d4e5f6a7-b8c9-4d0e-8f2a-3b4c5d6e7f80",
      "voided": false,
      "voidedAt": null,
      "voidReason": null,
      "allocations": [
        {
          "id": "e5f6a7b8-c9d0-4e1f-9a3b-4c5d6e7f8091",
          "installmentId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
          "amountMinor": 20000
        }
      ]
    }
  ],
  "events": [
    {
      "id": "f6a7b8c9-d0e1-4f2a-8b4c-5d6e7f809102",
      "type": "SETTLEMENT_CREATED",
      "data": null,
      "createdAt": "2026-10-15T14:00:01.000Z"
    }
  ],
  "history": [
    "… mismo arreglo que events …"
  ],
  "nextInstallment": {
    "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
    "position": 2,
    "dueDate": "2026-11-15",
    "amountMinor": 20000,
    "appliedMinor": 0,
    "remainingMinor": 20000,
    "status": "UPCOMING",
    "wasRescheduled": false,
    "plannedMovementId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
  },
  "createdAt": "2026-09-15T16:20:00.000Z",
  "updatedAt": "2026-10-15T14:00:01.000Z"
}

Crear una obligación

POST/obligations

Plan: ProPermiso de la key: Lectura y escritura

Cuerpo

directionstringobligatorio
PAYABLE o RECEIVABLE.
kindstringobligatorio
Compatible con la dirección.
counterpartystringobligatorio
Hasta 200 caracteres.
totalAmountMinorintegerobligatorio
Total en céntimos.
currencystringobligatorio
Igual a la moneda de la cuenta; si no, 422.
defaultAccountIduuidobligatorio
Cuenta tuya.
originDatedateobligatorio
AAAA-MM-DD.
frequencystringobligatorio
SINGLE, WEEKLY, BIWEEKLY o MONTHLY.
installmentCountintegerobligatorio
Número de cuotas, 1 a 360. SINGLE exige 1.
firstDueDatedateobligatorio
Vencimiento de la primera cuota.
installmentsobject[]
Calendario a mano: { dueDate, amountMinor }. Debe sumar el total menos el pago inicial. Si lo omites, se reparte en partes iguales.
initialSettlementobject
Pago inicial: { amountMinor, occurredAt, accountId?, note? }.
createOriginMovementboolean
Solo préstamos. Por defecto true: registra la entrada o salida del dinero prestado.
description, notesstring
Hasta 500 y 2000 caracteres.
categoryIdstring
Categoría. En préstamos se ignora.
iduuid
Tu propio id. Reenviarlo devuelve la obligación existente.
curl -X POST "https://api.tuplatica.app/api/platica/obligations" \
  -H "Authorization: Bearer $PLATICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "PAYABLE",
    "kind": "CREDIT_PURCHASE",
    "counterparty": "Tienda de electrodomésticos",
    "description": "Nevera",
    "totalAmountMinor": 60000,
    "currency": "USD",
    "defaultAccountId": "0d9a4b7e-3c21-4e6f-8a5b-1f2e3d4c5b6a",
    "originDate": "2026-09-15",
    "frequency": "MONTHLY",
    "installmentCount": 3,
    "firstDueDate": "2026-10-15"
  }'

Responde 201 con la obligación completa. Cada cuota aparece también en la agenda.

Registrar un pago o cobro

POST/obligations/:id/settlements

Plan: ProPermiso de la key: Lectura y escritura

Registra el pago y crea el movimiento en la cuenta. Sin installmentId, el monto cubre primero las cuotas vencidas y luego las más antiguas.

Cuerpo

amountMinorintegerobligatorio
Monto en céntimos. No puede pasar de lo que falta.
occurredAtdatetimeobligatorio
Cuándo se pagó.
accountIduuid
Cuenta del pago. Por defecto, la predeterminada.
installmentIduuid
Aplica todo a una cuota concreta.
notestring
Hasta 500 caracteres.
iduuid
Tu propio id; también es el id del movimiento creado.
curl -X POST "https://api.tuplatica.app/api/platica/obligations/2f4a6c8e-0b2d-4f6a-8c0e-2b4d6f8a0c2e/settlements" \
  -H "Authorization: Bearer $PLATICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountMinor": 20000,
    "occurredAt": "2026-11-15T10:00:00-04:00"
  }'

Anular un pago

POST/obligations/:id/settlements/:settlementId/void

Plan: ProPermiso de la key: Lectura y escritura

Anula el pago, borra su movimiento y devuelve el saldo a las cuotas. Queda en el historial. Pide reason (hasta 500 caracteres).

curl -X POST "https://api.tuplatica.app/api/platica/obligations/2f4a6c8e-0b2d-4f6a-8c0e-2b4d6f8a0c2e/settlements/d4e5f6a7-b8c9-4d0e-8f2a-3b4c5d6e7f80/void" \
  -H "Authorization: Bearer $PLATICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Lo registré dos veces"
  }'

Editar datos

PATCH/obligations/:id

Plan: ProPermiso de la key: Lectura y escritura

Acepta counterparty, description, notes, defaultAccountId y categoryId. Para cambiar montos o fechas usa el calendario.

Cambiar el calendario

PUT/obligations/:id/schedule

Plan: ProPermiso de la key: Lectura y escritura

Reemplaza el total y las cuotas: { totalAmountMinor, installments: [{ id?, dueDate, amountMinor }] }. Las cuotas deben sumar el total y no puedes quitar ni rebajar por debajo de lo ya pagado (409).

PATCH/obligations/:id/installments/:installmentId

Cambia solo la fecha de una cuota: { "dueDate": "2026-12-20" }.

Cancelar, archivar, restaurar

POST/obligations/:id/cancel

Cancela para siempre y omite sus filas pendientes en la agenda. Pide reason.

POST/obligations/:id/archive

Archiva una obligación pagada o cancelada. Sin cuerpo.

POST/obligations/:id/restore

La saca del archivo. Sin cuerpo.

Las obligaciones no se borran

No hay DELETE: el historial de pagos se conserva. Cancela o archiva. Una obligación archivada o cancelada no acepta pagos (409).

¿Dudas o algo no funciona? Escríbenos a [email protected]

Actualizado el 18 de octubre de 2026