Copiar para IA

Cobrança

Projetada para alimentar mecanismos de alerta precoce, agentes de IA e lembretes automatizados.

Visão geral

A API de Cobrança é um endpoint analítico e de leitura em massa projetado especificamente para fluxos de recuperação. Em vez de obrigar você a baixar milhares de orçamentos e calcular datas manualmente, o Cord faz no backend o cálculo completo de envelhecimento (aging) e de saldos.

Este endpoint é perfeito para ser consumido por um job Cron (node-cron ou Github Actions) que dispara lembretes por SMS, ou para alimentar um painel do PowerBI.

Recuperar o status da carteira

O endpoint GET /api/v1/cobranza devolve um resumo mestre da saúde financeira da organização.

Requisição:

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

Resposta (snapshot analítico):

A resposta é estruturada para uso imediato e, por segurança, remove o token público secreto de cada conta — publicá-lo em uma listagem transformaria qualquer chave somente leitura em um distribuidor de links de pagamento. Cada total é o total do orçamento na sua própria moeda de venda, sem conversão; a resposta não inclui a moeda de cada conta. resumen, aging e clientes somam esses totais como estão, então, se o seu negócio cria orçamentos em mais de uma moeda, essas somas misturam moedas. A carteira inclui os orçamentos aprovados ou faturados (approved, invoiced) que não são mensalidades recorrentes; as faturas do Cord Invoicing são consultadas com a API de Faturas.

{
  "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 é um array de 4 faixas fixas, não um objeto por intervalo de dias: vigente (ainda não venceu), d30 (de 1 a 30 dias de atraso), d60 (de 31 a 60) e d60p (mais de 60). status em items é o status real do orçamento (approved ou invoiced); se estiver vencido, overdue vem como true e diasVencido conta os dias.