Cobranza

Diseñada para alimentar motores de alertas tempranas, agentes de IA y recordatorios automatizados.

Descripción General

La API de Cobranza es un endpoint analítico y de lectura masiva diseñado específicamente para flujos de trabajo de recuperación. En lugar de forzarte a descargar miles de cotizaciones y calcular fechas manualmente, Cord realiza el cálculo completo de antigüedad (Aging) y saldos en el backend.

Este endpoint es perfecto para ser consumido por un trabajo Cron (node-cron o Github Actions) para disparar recordatorios SMS, o para alimentar un dashboard de PowerBI.

Recuperar Estado de Cartera

El endpoint GET /api/v1/cobranza devuelve un resumen maestro de la salud financiera de la organización.

Petición:

curl -X GET "https://cordhq.app/api/v1/cobranza" \
     -H "Authorization: Bearer sk_live_tU..."

Respuesta (Snapshot Analítico):

La respuesta está estructurada para uso inmediato, retirando el token público secreto de cada cuenta por seguridad — publicarlo en un listado convertiría cualquier llave de solo lectura en un repartidor de links de cobro. Los montos se expresan en la divisa contable de la organización.

{
  "data": {
    "resumen": {
      "totalPorCobrar": 450000,
      "totalVencido": 150000,
      "totalVigente": 300000,
      "nPorCobrar": 24,
      "nVencidas": 12,
      "nClientes": 9,
      "nExcedidos": 1,
      "interesTotal": 3200,
      "interesPct": 3,
      "avgDelay": 6,
      "esperado7": 80000,
      "esperado30": 220000
    },
    "aging": [
      { "key": "vigente", "label": "Por vencer", "monto": 300000, "n": 12, "color": "#3b82f6" },
      { "key": "d30", "label": "1–30 días", "monto": 50000, "n": 6, "color": "#f59e0b" },
      { "key": "d60", "label": "31–60 días", "monto": 20000, "n": 3, "color": "#f97316" },
      { "key": "d60p", "label": "+60 días", "monto": 80000, "n": 3, "color": "#ef4444" }
    ],
    "items": [
      {
        "id": "qte_...",
        "folio": "COT-00104",
        "empresa": "Stark Industries",
        "clienteId": "cus_...",
        "status": "invoiced",
        "total": 5000,
        "overdue": true,
        "diasVencido": 14,
        "interes": 42
      }
    ],
    "clientes": [
      {
        "empresa": "Stark Industries",
        "saldo": 55000,
        "limite": 500000,
        "n": 3,
        "excede": false,
        "uso": 11
      }
    ]
  }
}

aging es un arreglo de 4 cubetas fijas (vigente, d30, d60, d60p), no un objeto por rango de días. status en items es el estado real de la cotización/factura (approved, invoiced…); si está vencida, overdue viene en true y diasVencido cuenta los días.