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 Scale plan or higher. Collections is a paid capability (Rule 17). 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. Amounts are expressed in the organization’s accounting currency.

{
  "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": "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 is an array of 4 fixed buckets (vigente, d30, d60, d60p), not an object keyed by day range. status in items is the real quote/invoice state (approved, invoiced…); when it’s overdue, overdue comes back true and diasVencido counts the days.