VerifikaDocs
ReferenciaCuentas por cobrar

Listar clientes que deben

El cuaderno de fiados, un cliente por fila con su saldo, paginado por cursor. Por defecto, quien más debe primero.

Acepta los mismos filtros que el tablero y el Excel del panel: si lo que lee tu integración y lo que ve la dueña salieran de filtros distintos, dirían cosas distintas del mismo cuaderno. Para totales usa GET /v1/receivables/summary, no sumes páginas.

Permiso: receivables.read.

GET
/receivables

Autorización

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

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.

limit?integer

Filas por página.

Rango1 <= value <= 100
Por defecto50
startingAfter?string

Cursor: el nextCursor de la página anterior.

q?string

Busca por nombre, teléfono o correo, sin importar tildes ni mayúsculas («jose» encuentra a «José»). Cada palabra tiene que estar. Un término de 4 dígitos o más busca en el teléfono.

Longitudlength <= 80
stage?string

Etapas, separadas por coma o repitiendo el parámetro.

overdue?boolean

true = solo vencidas; false = solo las que no lo están. Sin el parámetro, todas.

minBalance?number

Saldo mínimo, en pesos. Admite centavos (hasta 2 decimales): 1100.5 son $1.100,50.

Múltiplo de0.01
maxBalance?number

Saldo máximo, en pesos, con hasta 2 decimales.

Múltiplo de0.01
minPaid?number

Total abonado mínimo, en pesos, con hasta 2 decimales.

Múltiplo de0.01
maxPaid?number

Total abonado máximo, en pesos, con hasta 2 decimales.

Múltiplo de0.01
minPayments?integer

Número mínimo de abonos.

maxPayments?integer

Número máximo de abonos.

createdFrom?string

Creados desde. Una fecha pelada (2026-09-01) es un día de calendario colombiano: «desde» arranca a las 00:00 de Bogotá y «hasta» cierra a las 23:59:59 de Bogotá. Un ISO completo se respeta tal cual.

createdTo?string

Creados hasta, inclusive.

lastPaymentFrom?string

Último abono desde. Una fecha pelada (2026-09-01) es un día de calendario colombiano: «desde» arranca a las 00:00 de Bogotá y «hasta» cierra a las 23:59:59 de Bogotá. Un ISO completo se respeta tal cual.

lastPaymentTo?string

Último abono hasta, inclusive.

lastChargeFrom?string

Último fiado desde. Una fecha pelada (2026-09-01) es un día de calendario colombiano: «desde» arranca a las 00:00 de Bogotá y «hasta» cierra a las 23:59:59 de Bogotá. Un ISO completo se respeta tal cual.

lastChargeTo?string

Último fiado hasta, inclusive.

dueFrom?string

Fecha acordada desde. Una fecha pelada (2026-09-01) es un día de calendario colombiano: «desde» arranca a las 00:00 de Bogotá y «hasta» cierra a las 23:59:59 de Bogotá. Un ISO completo se respeta tal cual.

dueTo?string

Fecha acordada hasta, inclusive.

includePaid?boolean

Incluir las cuentas saldadas. Por defecto sí (son la columna «Saldada» del tablero); false deja solo las que deben.

Por defectotrue
archived?boolean

true devuelve solo las archivadas (para restaurarlas). Por defecto se excluyen.

Por defectofalse
sort?string

Orden. balance_desc = quien más debe primero; oldest = los que llevan más tiempo quietos (el orden de la cobranza); recent = última actividad; due_asc = por fecha acordada (sin fecha al final); last_payment_desc = abonos más recientes primero.

Por defecto"balance_desc"

Uno de

  • "balance_desc"
  • "balance_asc"
  • "recent"
  • "oldest"
  • "due_asc"
  • "name_asc"
  • "last_payment_desc"

Cuerpo de la respuesta

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/receivables"
{  "object": "list",  "data": [    {      "object": "receivableAccount",      "id": "cmu1f8d3p0021kxw1n6v0bq4m",      "name": "Hernán Ospina",      "phone": "+573157654321",      "email": null,      "notes": "Materiales para la obra de la casa. Llamarlo antes del 5.",      "stage": "FOLLOW_UP",      "dueDate": "2026-09-05T05:00:00.000Z",      "isOverdue": true,      "balance": 480000,      "currency": "COP",      "totalCharged": 680000,      "totalPaid": 200000,      "totalWrittenOff": 0,      "chargesCount": 3,      "paymentsCount": 1,      "lastChargeAt": "2026-08-28T18:40:00.000Z",      "lastPaymentAt": "2026-08-15T17:00:00.000Z",      "lastActivityAt": "2026-09-08T15:31:45.902Z",      "branchId": null,      "source": "PANEL",      "createdBy": {        "id": "cmt8u1p9r00035pw1kq0v2xdc",        "name": "José Quintero"      },      "createdAt": "2026-08-02T16:10:27.554Z",      "updatedAt": "2026-09-08T15:31:45.902Z",      "archivedAt": null    },    {      "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    }  ],  "hasMore": true,  "nextCursor": "cmu4a2k9x000b7qw1h3r5tz8e"}

Historial de un cliente GET

Todos los movimientos de un cliente, paginados por cursor, recientes primero. `balanceAfter` es el saldo justo después de cada uno: el estado de cuenta se lee de arriba abajo sin que la columna mienta. Permiso: `receivables.read`.

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