Crear un cliente que debe
Abre la cuenta de un cliente, con lo que ya debe (initialDebt) y lo que ya abonó (initialPaid). Cada uno se vuelve un movimiento del historial («Deuda inicial», «Abono inicial») y la etapa se calcula sola: con abono queda en PARTIAL, sin abono en OPEN.
No deduplica por nombre: antes de crear, busca con GET /v1/receivables?q= que no exista ya — dos «Gloria» en el cuaderno parten el saldo en dos.
Queda con source: "API" y createdBy: null. Responde con la misma forma que GET /v1/receivables/{id}.
Permiso: receivables.write.
Autorización
apiKey receivables.writeLa llave del negocio, creada en el panel: Integraciones → API pública. vk_live_… es una llave real; vk_test_…, una llave de modo prueba (verificaciones simuladas, nada toca el libro real). Ver la guía «Modo de prueba».
Va en: header
Permiso: receivables.write
Parámetros de consulta
Sobre qué negocio actúa la petición. Obligatorio solo si la llave entra a varios negocios; con uno solo, se deduce.
Parámetros de cabecera
Llave única de la operación. Un reintento con la misma llave y el mismo cuerpo devuelve la respuesta original (con Idempotent-Replay: true) en vez de registrar el movimiento otra vez. Ver la guía de idempotencia.
Cuerpo de la petición
application/json
Tipos de TypeScript
Usa el tipo request body en TypeScript.
Cuerpo de la respuesta
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/receivables" \ -H "Content-Type: application/json" \ -d '{ "name": "Gloria Restrepo", "phone": "310 456 7890", "notes": "Mercado de la semana. Paga los viernes.", "dueDate": "2026-10-15", "initialDebt": 300000, "initialPaid": 50000, "branchId": "cmt7xbfrj0002q3w1iq4ysatr" }'{ "object": "receivableAccount", "id": "cmu4a2k9x000b7qw1h3r5tz8e", "name": "Gloria Restrepo", "phone": "+573104567890", "email": null, "notes": "Mercado de la semana. Paga los viernes.", "stage": "PARTIAL", "dueDate": "2026-10-15T05:00:00.000Z", "isOverdue": false, "balance": 250000, "currency": "COP", "totalCharged": 300000, "totalPaid": 50000, "totalWrittenOff": 0, "chargesCount": 1, "paymentsCount": 1, "lastChargeAt": "2026-09-22T14:12:08.431Z", "lastPaymentAt": "2026-09-22T14:12:08.431Z", "lastActivityAt": "2026-09-22T14:12:08.431Z", "branchId": "cmt7xbfrj0002q3w1iq4ysatr", "source": "API", "createdBy": null, "createdAt": "2026-09-22T14:12:08.431Z", "updatedAt": "2026-09-22T14:12:08.431Z", "archivedAt": null, "entries": { "object": "list", "data": [ { "object": "receivableEntry", "id": "cmu4a2kb4000d7qw1c5x8fj3n", "accountId": "cmu4a2k9x000b7qw1h3r5tz8e", "type": "PAYMENT", "amount": 50000, "currency": "COP", "balanceAfter": 250000, "note": "Abono inicial", "occurredAt": "2026-09-22T14:12:08.431Z", "createdAt": "2026-09-22T14:12:08.432Z", "source": "API", "createdBy": null, "voided": false, "voidedAt": null, "voidedBy": null }, { "object": "receivableEntry", "id": "cmu4a2kb1000c7qw1p9d2mw6s", "accountId": "cmu4a2k9x000b7qw1h3r5tz8e", "type": "CHARGE", "amount": 300000, "currency": "COP", "balanceAfter": 300000, "note": "Deuda inicial", "occurredAt": "2026-09-22T14:12:08.431Z", "createdAt": "2026-09-22T14:12:08.431Z", "source": "API", "createdBy": null, "voided": false, "voidedAt": null, "voidedBy": null } ], "hasMore": false, "nextCursor": null }}Archivar un cliente POST
Lo saca del tablero, de la lista y de los totales (ya no se le cobra, se mudó…). **No perdona la deuda** —para eso está condonar— ni borra el historial: se lee igual y se restaura cuando quieras. Mientras esté archivado no admite movimientos ni ediciones. Archivar uno que ya estaba archivado responde `404`. Permiso: `receivables.write`.
Registrar un fiado, un abono o una condonación POST
Un movimiento nuevo. El saldo **no se suma ni se resta**: se recalcula releyendo todo el historial, con la fila del cliente bloqueada. Por eso dos abonos simultáneos (la caja y el panel) nunca pasan los dos la validación contra el mismo saldo. - `CHARGE` (fiado) sube el saldo; si la cuenta estaba saldada, la reabre en `OPEN`. - `PAYMENT` (abono) lo baja; el primero sobre `OPEN` la pasa a `PARTIAL`. - `WRITE_OFF` (condonación) lo baja sin contar como pago. - Si el saldo llega a cero, la cuenta pasa a `PAID` sola. Un abono o una condonación por más de lo que debe responde `422 RECEIVABLE_OVERPAYMENT` con el saldo en `details.balance`. Si el cliente pagó todo, `POST …/settle` es más seguro: salda lo que de verdad queda. Permiso: `receivables.write` para `CHARGE` y `PAYMENT`; `receivables.write_off` para `WRITE_OFF`. El permiso se mira **después** de validar el cuerpo, porque depende de `type`.