Skip to content
ESEN

Collections

Designed to feed early warning engines, AI agents, and automated reminders.

Overview

The Collections API is an analytical, mass-read endpoint specifically designed for recovery workflows. Instead of forcing you to download thousands of quotes and calculate dates manually, Cord performs the complete aging and balance calculations on the backend.

This endpoint is perfect for being consumed by a Cron job (node-cron or Github Actions) to trigger SMS reminders, or to feed a PowerBI dashboard.

Retrieving Portfolio Status

The GET /api/v1/cobranza endpoint returns a master summary of the organization’s financial health.

Requires the Professional plan or higher. Collections is a paid capability. Without the required plan, the endpoint responds 402 Payment Required with code: "subscription_required" instead of data — see Error Handling.

Request:

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

Response (Analytical Snapshot):

The response is structured for immediate use, stripping each account’s secret public token for security — publishing it in a list would turn any read-only key into a payment-link dispenser. Each total is the quote total in its own sale currency, unconverted; the response doesn’t include each account’s currency. resumen, aging, and clientes add those totals as they are, so if your business quotes in more than one currency those sums mix currencies. The portfolio includes approved or invoiced quotes (approved, invoiced) that aren’t recurring retainers; Cord Invoicing invoices are read with the Invoices API.

{
  "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": "Not yet due", "monto": 300000, "n": 12, "color": "#3b82f6" },
      { "key": "d30", "label": "1–30 days", "monto": 50000, "n": 6, "color": "#f59e0b" },
      { "key": "d60", "label": "31–60 days", "monto": 20000, "n": 3, "color": "#f97316" },
      { "key": "d60p", "label": "60+ days", "monto": 80000, "n": 3, "color": "#ef4444" }
    ],
    "items": [
      {
        "id": "2a9d8e4f-6b1c-4d7a-9e3f-5c8b1a2d4e6f",
        "folio": "COT-00104",
        "empresa": "Stark Industries",
        "clienteId": "8f7b2c1e-4d3a-4b9f-a6e2-1c5d7e9f0a3b",
        "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 is an array of 4 fixed buckets, not an object keyed by day range: vigente (not yet due), d30 (1 to 30 days overdue), d60 (31 to 60), and d60p (more than 60). status in items is the real quote state (approved or invoiced); when it’s overdue, overdue comes back true and diasVencido counts the days.