VerifikaDocs
ReferenciaCuentas por cobrar

Editar un cliente

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.

PATCH
/receivables/{id}

Autorización

apiKey receivables.write
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.

Al menos un campo. Manda null para borrar un dato opcional.

Cuerpo de la respuesta

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/receivables/string" \  -H "Content-Type: application/json" \  -d '{    "stage": "FOLLOW_UP",    "dueDate": "2026-10-03"  }'
{  "object": "receivableAccount",  "id": "cmu4a2k9x000b7qw1h3r5tz8e",  "name": "Gloria Restrepo",  "phone": "+573104567890",  "email": null,  "notes": "Mercado de la semana. Paga los viernes.",  "stage": "FOLLOW_UP",  "dueDate": "2026-10-03T05: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-27T13:02:40.611Z",  "branchId": "cmt7xbfrj0002q3w1iq4ysatr",  "source": "API",  "createdBy": null,  "createdAt": "2026-09-22T14:12:08.431Z",  "updatedAt": "2026-09-27T13:02:40.611Z",  "archivedAt": null}

Saldar la cuenta POST

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

Anular un movimiento POST

Para un fiado, abono o condonación mal registrado. **No se borra nada**: el movimiento se queda en el historial con `voided: true` y el saldo se recalcula sin él (por eso es `POST …/void` y no `DELETE`). Anular dos veces devuelve lo mismo y no emite un segundo evento. Anular un fiado que ya se había abonado dejaría al cliente con saldo a favor: responde `422 RECEIVABLE_NEGATIVE_BALANCE` — primero se anula el abono. Permiso: `receivables.void`.