VerifikaDocs
ReferenciaCuentas por cobrar

Saldar la cuenta

Un movimiento por todo el saldo, leído con la fila bloqueada: el monto no se manda. Si entre tu consulta y este POST entró otro abono, se salda lo que de verdad queda. La cuenta pasa a PAID y sale el evento receivable.account.paid.

  • mode: "PAYMENT" — pagó todo. Permiso receivables.write.
  • mode: "WRITE_OFF" — se le perdona todo. Permiso receivables.write_off.

El movimiento se fecha ahora. Si la cuenta ya está en cero → 422 RECEIVABLE_ALREADY_PAID.

POST
/receivables/{id}/settle

Autorización

AutorizaciónBearer <token>

La 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 la ruta

id*string

Id del cliente (la cuenta por cobrar).

Parámetros de consulta

companyId?string

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

Idempotency-Key?string

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

application/json

curl -X POST "https://example.com/receivables/string/settle" \  -H "Content-Type: application/json" \  -d '{    "mode": "PAYMENT"  }'
{  "object": "receivableEntry",  "id": "cmu8c3w5m002zbnw1q7t1ha0g",  "accountId": "cmu4a2k9x000b7qw1h3r5tz8e",  "type": "PAYMENT",  "amount": 170000,  "currency": "COP",  "balanceAfter": 0,  "note": "Pagó el saldo",  "occurredAt": "2026-09-29T16:20:11.207Z",  "createdAt": "2026-09-29T16:20:11.207Z",  "source": "API",  "createdBy": null,  "voided": false,  "voidedAt": null,  "voidedBy": null,  "account": {    "object": "receivableAccount",    "id": "cmu4a2k9x000b7qw1h3r5tz8e",    "name": "Gloria Restrepo",    "phone": "+573104567890",    "email": null,    "notes": "Mercado de la semana. Paga los viernes.",    "stage": "PAID",    "dueDate": "2026-10-15T05:00:00.000Z",    "isOverdue": false,    "balance": 0,    "currency": "COP",    "totalCharged": 300000,    "totalPaid": 300000,    "totalWrittenOff": 0,    "chargesCount": 1,    "paymentsCount": 3,    "lastChargeAt": "2026-09-22T14:12:08.431Z",    "lastPaymentAt": "2026-09-29T16:20:11.207Z",    "lastActivityAt": "2026-09-29T16:20:11.207Z",    "branchId": "cmt7xbfrj0002q3w1iq4ysatr",    "source": "API",    "createdBy": null,    "createdAt": "2026-09-22T14:12:08.431Z",    "updatedAt": "2026-09-29T16:20:11.207Z",    "archivedAt": null  }}

Restaurar un cliente archivado POST

Lo devuelve al tablero y a los totales con el saldo y la etapa que tenía. Los archivados se listan con `GET /v1/receivables?archived=true`. Restaurar uno que no estaba archivado devuelve el cliente sin cambiar nada. Permiso: `receivables.write`.

Editar un cliente PATCH

Datos de contacto, notas, fecha acordada de pago y etapa del tablero. No toca el saldo: eso solo lo mueven los movimientos. - Pasar a `PAID` con saldo → `422 RECEIVABLE_STAGE_REQUIRES_PAYMENT`. Para darla por pagada, `POST /v1/receivables/{id}/settle`. - Mover de etapa una cuenta que ya está en cero → `422 RECEIVABLE_ALREADY_PAID`. Para reabrirla se anota un fiado nuevo. - Un cliente archivado no se edita (`404`): primero se restaura. Permiso: `receivables.write`.