Cobrar y conciliar pagos

GET /obligations responde lo que alguien debe y GET /payments lo que llegó. Una imputación dice qué pago cubre qué obligación, y de ahí salen el saldo, el estado y lo que una persona debe hoy. Ningún saldo se edita a mano.

curl "https://api.vitrinadev.com/api/v1/obligations?contact_id=$CONTACT" \
  -H "Authorization: Bearer $VITRINA_KEY"

Las lecturas piden payments:read y las escrituras payments:write. Revertir un pago tiene su propio permiso, payments:reverse, porque deshacer dinero recibido no equivale a recibirlo.

La obligación

{
  "data": {
    "id": "b44936d0-0000-4000-8000-000000000004",
    "contact_id": "1a73af9e-0000-4000-8000-000000000001",
    "kind": "service",
    "label": "Ortodoncia — primera cuota",
    "expected_clp": 112000,
    "allocated_clp": 0,
    "outstanding_clp": 112000,
    "state": "pending",
    "due_on": "2026-10-10"
  }
}

kind dice de qué nace, y ahí aparece la vertical:

Varias obligaciones que para la persona son una sola cosa, como las cuotas de un plan, comparten un group_id. GET /obligations/groups/{groupId} las lee juntas con su saldo.

Una obligación termina de tres maneras. Pagada: las imputaciones la cubren. Condonada (/waive, con motivo): la organización decide no cobrarla. Anulada (/cancel, con motivo y con qué pasó con lo ya pagado: aplicado, devuelto o perdido). Editar el monto esperado exige un reason en el cuerpo.

El pago

curl -X POST https://api.vitrinadev.com/api/v1/payments \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pago-transferencia-884213" \
  -d '{
    "contact_id": "1a73af9e-0000-4000-8000-000000000001",
    "instrument": "transferencia",
    "amount_clp": 50000,
    "paid_on": "2026-09-24",
    "bank": "Banco de Chile",
    "document_number": "884213",
    "allocations": [
      { "obligation_id": "b44936d0-0000-4000-8000-000000000004", "amount_clp": 50000 }
    ]
  }'

instrument es cómo llegó: efectivo, transferencia, tarjeta, cheque, vale vista. paid_on es el día en que la persona pagó, que no siempre es hoy. allocations lo imputa de una vez. Si todavía no sabes a qué, el pago queda sin imputar y aparece en GET /payments?unapplied=true, que es un estado legítimo.

Un pago que llegó sin saber de quién es se registra igual, sin contact_id, y después POST /payments/{id}/assign-payer le pone dueño. POST /payments/{id}/allocations imputa más adelante y DELETE /payments/{id}/allocations/{allocationId} libera una imputación equivocada, siempre con motivo.

Un pago nunca se borra. POST /payments/{id}/reverse lo revierte con su razón y deja la reversa como una fila más.

El estado de cuenta de una persona

curl https://api.vitrinadev.com/api/v1/contacts/$CONTACT/ledger \
  -H "Authorization: Bearer $VITRINA_KEY"

Responde de una vez qué debe, qué pagó y qué quedó sin imputar. Es la lectura que conviene mostrar en pantalla, en vez de sumar obligaciones y pagos por tu cuenta y llegar a otro número.

Un cobro nombra a una persona, y qué ve de ella una aplicación conectada está en Datos personales.