VerifikaDocs
ReferenciaCuentas por cobrar

Registrar un fiado, un abono o una condonación

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.

POST
/receivables/{id}/entries

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/entries" \  -H "Content-Type: application/json" \  -d '{    "type": "PAYMENT",    "amount": 80000,    "note": "Abono en efectivo, caja 2",    "occurredAt": "2026-09-26T21:05:33.000Z"  }'
{  "object": "receivableEntry",  "id": "cmu4h7r2t0014bnw1y2e6kd9v",  "accountId": "cmu4a2k9x000b7qw1h3r5tz8e",  "type": "PAYMENT",  "amount": 80000,  "currency": "COP",  "balanceAfter": 170000,  "note": "Abono en efectivo, caja 2",  "occurredAt": "2026-09-26T21:05:33.000Z",  "createdAt": "2026-09-26T21:05:33.118Z",  "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": "PARTIAL",    "dueDate": "2026-10-15T05:00:00.000Z",    "isOverdue": false,    "balance": 170000,    "currency": "COP",    "totalCharged": 300000,    "totalPaid": 130000,    "totalWrittenOff": 0,    "chargesCount": 1,    "paymentsCount": 2,    "lastChargeAt": "2026-09-22T14:12:08.431Z",    "lastPaymentAt": "2026-09-26T21:05:33.000Z",    "lastActivityAt": "2026-09-26T21:05:33.118Z",    "branchId": "cmt7xbfrj0002q3w1iq4ysatr",    "source": "API",    "createdBy": null,    "createdAt": "2026-09-22T14:12:08.431Z",    "updatedAt": "2026-09-26T21:05:33.118Z",    "archivedAt": null  }}

Crear un cliente que debe POST

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

Ver un cliente GET

La ficha de un cliente con su saldo y sus últimos 50 movimientos, recientes primero; los anulados salen marcados `voided`. Si `entries.hasMore` es `true`, el resto está en `GET /v1/receivables/{id}/entries`. Un cliente archivado también se lee. Permiso: `receivables.read`.