Copiar para IA

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. La cartera une las cotizaciones aprobadas sin factura abierta y las facturas abiertas (origen: cotizacion o factura), cada una por su saldo; las igualas recurrentes no entran. Los importes de resumen, aging y clientes, y el total de cada item, van en moneda, la divisa de tu negocio: un documento en otra divisa se convierte con la tasa congelada al cotizar o, si no la hay, con la de hoy. Cada item trae además su saldo en la divisa del documento (saldoDocumento y monedaDocumento). Un documento sin tipo de cambio disponible no se suma, y su divisa aparece en divisas.sinTasa. El detalle de una factura se consulta con la API de Facturas.

{
  "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": "2a9d8e4f-6b1c-4d7a-9e3f-5c8b1a2d4e6f",
        "folio": "COT-00104",
        "origen": "cotizacion",
        "empresa": "Stark Industries",
        "clienteId": "8f7b2c1e-4d3a-4b9f-a6e2-1c5d7e9f0a3b",
        "status": "invoiced",
        "total": 5000,
        "monedaDocumento": "MXN",
        "saldoDocumento": 5000,
        "overdue": true,
        "diasVencido": 14,
        "interes": 42
      }
    ],
    "clientes": [
      {
        "empresa": "Stark Industries",
        "saldo": 55000,
        "limite": 500000,
        "n": 3,
        "excede": false,
        "uso": 11
      }
    ],
    "moneda": "MXN",
    "divisas": { "convertidas": ["USD"], "sinTasa": [] }
  }
}

aging es un arreglo de 4 cubetas fijas, no un objeto por rango de días: vigente (todavía no vence), d30 (1 a 30 días vencida), d60 (31 a 60) y d60p (más de 60). status en items es el estado real de la cotización (approved o invoiced); si está vencida, overdue viene en true y diasVencido cuenta los días.