Cuentas por cobrar

Un negocio de barrio fía: «Gloria se lleva $300.000 de mercado y me va abonando». Casi siempre eso vive en un cuaderno. Cuentas por cobrar es ese cuaderno dentro de Verifika: una cuenta por cliente, con su saldo, y un historial de movimientos — fiados, abonos y condonaciones. El saldo se calcula solo, y la dueña lo ve en el panel como un tablero por etapas.

La API es para que ese cuaderno se llene solo desde donde ya ocurren las cosas:

Todo cuelga de /v1/receivables. La referencia completa está en Cuentas por cobrar.

Permisos: son cuatro, no dos

El módulo es una función del plan (receivables_module). Sin ella, cualquier llamada responde 403 PLAN_FEATURE_REQUIRED. Con ella, la llave necesita además el permiso de cada cosa:

¿Por qué no un simple leer/escribir? Porque la integración típica es una caja, y la llave de una caja no debería poder perdonar deudas ni hacer desaparecer historia. Si se filtra una llave con receivables.write, lo peor que deja es un movimiento de más, que una persona anula desde el panel. Con write_off o void se puede borrar lo que un cliente debe. Dale esos dos solo a quien los necesite.

No hay un permiso de exportar: leer por API ya es llevarse los datos. El Excel y el PDF son para personas, en el panel.

Tampoco hay alcance por sucursal: el cuaderno es del negocio, y una llave acotada a una sucursal lo ve entero. branchId al crear un cliente es informativo.

Las etapas se mueven solas

Cada cliente está en una columna del tablero (stage):

Después de cada movimiento o anulación se aplican estas reglas, en orden:

1. Saldo en cero → PAID.
2. Saldo mayor que cero y estaba PAID → vuelve a OPEN.
3. Un abono sobre OPEN → PARTIAL.
4. FOLLOW_UP se respeta hasta que el saldo llegue a cero.
5. Anular el único abono de una cuenta PARTIAL la devuelve a OPEN.

Dos cosas que no puedes hacer moviendo la tarjeta:

• Pasarla a PAID con saldo. Eso no es mover una tarjeta, es decir que pagó: responde 422 RECEIVABLE_STAGE_REQUIRES_PAYMENT. Para darla por pagada, salda la cuenta.
• Mover de columna una cuenta en cero. No hay nada que cobrar: 422 RECEIVABLE_ALREADY_PAID. Para reabrirla se anota un fiado nuevo.

«Vencida» no es una etapa

Es un dato aparte, isOverdue: saldo mayor que cero y la fecha acordada de pago (dueDate) quedó antes de hoy, contando el día en Bogotá. Una cuenta en PARTIAL o en FOLLOW_UP puede estar vencida. Para la lista de vencidos: GET /v1/receivables?overdue=true.

Montos y fechas

• Pesos con hasta 2 decimales. 300000 son $300.000 y 25000.2 son $25.000,20. Saldos y totales vuelven igual: con centavos solo si los tienen. Un monto con más de 2 decimales es 400 («El valor admite máximo 2 decimales.»), no se redondea.
• amount siempre positivo. El signo lo da el tipo: CHARGE (fiado) sube el saldo; PAYMENT (abono) y WRITE_OFF (condonación) lo bajan.
• Un día pelado es un día de Bogotá. En los filtros, createdFrom=2026-09-01 arranca a las 00:00 de Colombia y createdTo=2026-09-30 cierra a las 23:59:59 de Colombia — no a medianoche UTC, que serían las 7 de la noche del día anterior.
• dueDate: "2026-10-15" se guarda a las 00:00 de ese día en Bogotá (2026-10-15T05:00:00.000Z), así que la cuenta se vence el 16.
• occurredAt de un movimiento es opcional (sin él, ahora). Un día pelado ("2026-09-26") queda al mediodía de Bogotá, para que un abono «del 26» no caiga el 25 por ningún redondeo. Un ISO completo se respeta tal cual; si está en el futuro (con 5 minutos de tolerancia), es 400.

El flujo completo

De cliente nuevo a cuenta saldada, en cuatro llamadas.

curl -X POST https://api.verifika.tech/v1/receivables \
  -H "Authorization: Bearer $VERIFIKA_API_KEY" \
  -H "Idempotency-Key: alta-gloria-restrepo-2026-09-22" \
  -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
  }'

{
  "object": "receivableAccount",
  "id": "cmu4a2k9x000b7qw1h3r5tz8e",
  "name": "Gloria Restrepo",
  "phone": "+573104567890",
  "stage": "PARTIAL",
  "dueDate": "2026-10-15T05:00:00.000Z",
  "isOverdue": false,
  "balance": 250000,
  "currency": "COP",
  "totalCharged": 300000,
  "totalPaid": 50000,
  "source": "API",
  "createdBy": null,
  "entries": {
    "object": "list",
    "data": [
      { "object": "receivableEntry", "type": "PAYMENT", "amount": 50000, "balanceAfter": 250000, "note": "Abono inicial" },
      { "object": "receivableEntry", "type": "CHARGE", "amount": 300000, "balanceAfter": 300000, "note": "Deuda inicial" }
    ],
    "hasMore": false,
    "nextCursor": null
  }
}

curl -X POST https://api.verifika.tech/v1/receivables/cmu4a2k9x000b7qw1h3r5tz8e/entries \
  -H "Authorization: Bearer $VERIFIKA_API_KEY" \
  -H "Idempotency-Key: caja2-recibo-004817" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PAYMENT",
    "amount": 80000,
    "note": "Abono en efectivo, caja 2"
  }'

{
  "object": "receivableEntry",
  "id": "cmu4h7r2t0014bnw1y2e6kd9v",
  "type": "PAYMENT",
  "amount": 80000,
  "balanceAfter": 170000,
  "note": "Abono en efectivo, caja 2",
  "source": "API",
  "voided": false,
  "account": {
    "object": "receivableAccount",
    "id": "cmu4a2k9x000b7qw1h3r5tz8e",
    "stage": "PARTIAL",
    "balance": 170000,
    "totalPaid": 130000,
    "paymentsCount": 2
  }
}

curl https://api.verifika.tech/v1/receivables/cmu4a2k9x000b7qw1h3r5tz8e \
  -H "Authorization: Bearer $VERIFIKA_API_KEY"

curl -X POST https://api.verifika.tech/v1/receivables/cmu4a2k9x000b7qw1h3r5tz8e/settle \
  -H "Authorization: Bearer $VERIFIKA_API_KEY" \
  -H "Idempotency-Key: caja2-recibo-004902" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "PAYMENT" }'

{
  "object": "receivableEntry",
  "type": "PAYMENT",
  "amount": 170000,
  "balanceAfter": 0,
  "note": "Pagó el saldo",
  "account": { "id": "cmu4a2k9x000b7qw1h3r5tz8e", "stage": "PAID", "balance": 0, "totalPaid": 300000 }
}

Reintentar un abono sin duplicarlo

La red se corta después de que registramos el abono pero antes de que te llegue la respuesta. Tu caja reintenta. Sin protección, Gloria queda con dos abonos de $80.000 — y el saldo del cuaderno, $80.000 más bajo de lo que de verdad debe.

Por eso toda escritura acepta Idempotency-Key. La regla es una llave por operación de negocio, no por intento HTTP: el número de recibo de la caja es una llave perfecta, porque ya identifica ese abono y solo ese.

Solo se guardan las respuestas exitosas: si el abono falló con 422, corriges y reintentas con la misma llave. Las llaves se recuerdan 24 horas. Detalles en Idempotencia.

Errores que vas a ver

Todos con el sobre de siempre ({ error: { code, message, details?, requestId, docUrl } }, ver Errores). Ramifica por code, nunca por message.

{
  "error": {
    "code": "RECEIVABLE_OVERPAYMENT",
    "message": "El monto supera lo que debe ($170.000).",
    "details": { "balance": 170000 },
    "requestId": "req_d20f6e…",
    "docUrl": "https://docs.verifika.tech/guias/errores"
  }
}

Condonar con la llave de la caja

La caja intenta perdonar el saldo ("type": "WRITE_OFF" o settle con "mode": "WRITE_OFF") con una llave que solo tiene receivables.write:

{
  "error": {
    "code": "SCOPE_REQUIRED",
    "message": "Esta API key no tiene permiso para esta operación.",
    "details": { "scope": "receivables.write_off" },
    "requestId": "req_b0b926…",
    "docUrl": "https://docs.verifika.tech/guias/errores"
  }
}

Es lo esperado, no un fallo: condonar es una decisión de la dueña, no de la caja. No amplíes la llave de la caja para esquivarlo; que lo haga una persona desde el panel, o una llave aparte con ese permiso. Como el permiso depende del type o del mode, se revisa después de validar el cuerpo: un cuerpo inválido responde 400 antes que 403.

Anular, archivar o condonar

Las tres «quitan» algo, y no son intercambiables:

No hay forma de borrar un cliente ni un movimiento por API. Es a propósito: el cuaderno es la memoria de lo que se fió, y un historial que se puede reescribir deja de servir para cobrar.

Enterarte sin preguntar

Si tu sistema necesita saber cuándo alguien —la cajera en la app, la dueña en el panel, el asistente o tu propia llave— anota un fiado o salda una cuenta, suscríbete a los eventos receivable.* en vez de consultar cada minuto. Están en Eventos de webhook. El que casi todos quieren es receivable.account.paid.

Siguiente paso