API do provedor

Como autenticar

Gere um token na Central → Integração. Um token por integração (SGP, CRM, n8n): assim você revoga um sem derrubar os outros. O token aparece uma única vez — guardamos apenas o hash.

Mande o token no header Authorization. Aceitamos também Bearer <token> e o parâmetro ?api_key=, para CRMs que não deixam configurar header.

curl https://confiaisp.com.br/api/v2/ping \
  -H "Authorization: cfa_seu_token_aqui"

{"ok":true,"provedor":"Seu Provedor","participante":"#14","escopos":["consulta","registros"]}

Consultar a rede

GET /api/v2/consulta/{documento} — só dígitos, CPF ou CNPJ. Consome 1 da franquia do mês e entra na trilha de auditoria.

curl https://confiaisp.com.br/api/v2/consulta/12345678000199 \
  -H "Authorization: cfa_seu_token_aqui"

{
  "documento": "12345678000199",
  "score": 594,
  "faixa": "atencao",
  "restricoes": 1,
  "provedores": 1,
  "valor_cents": 28490,
  "equipamentos_pendentes": 1,
  "componentes": [
    { "item": "Restricoes ativas",            "peso": -80,  "detalhe": "1 registro(s)" },
    { "item": "Valor em aberto",              "peso": -66,  "detalhe": "284.90" },
    { "item": "Equipamento nao devolvido",    "peso": -120, "detalhe": "1 item(ns)" },
    { "item": "Pendencia recente",            "peso": -40,  "detalhe": "123 dias" }
  ],
  "registros": [
    {
      "provedor": "Net Vale Fibra",
      "provedor_numero": 14,
      "valor_cents": 28490,
      "dias": 123,
      "encerrado_em": "2026-05-04",
      "contestado": false,
      "equipamentos": [{ "tipo": "onu", "modelo": "Huawei EG8010", "status": "nao_devolvido" }]
    }
  ],
  "total": 1,
  "consumo": { "consultas_no_mes": 37, "franquia": 100 }
}

Dinheiro vem sempre em centavos (valor_cents): float erra centavo, e centavo errado em cadastro de crédito vira reclamação. Desde 21/09/2026 o campo provedor traz o nome de quem registrou (antes vinha “ISP participante #14”, e o número continua em provedor_numero). O que ninguém vê continua sendo quem mais consultou o mesmo documento.

Registrar um inadimplente

POST /api/v2/registros

curl -X POST https://confiaisp.com.br/api/v2/registros \
  -H "Authorization: cfa_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
        "documento": "12345678000199",
        "nome": "NOME DO DEVEDOR",
        "valor": 284.90,
        "vencimento": "2026-05-04",
        "contrato": "C-9001",
        "observacao": "contrato encerrado com mensalidade em aberto",
        "equipamento": { "tipo": "onu", "modelo": "Huawei EG8010", "serial": "ABC123" }
      }'

{"id":"adcf29ad-…","documento":"12345678000199","valor_cents":28490,"status":"ativo","equipamento":"registrado"}

Listar e dar baixa

GET /api/v2/registros — os seus registros, com ?status=ativo, ?documento=, ?pagina= e ?limite= (máximo 200 por página).

DELETE /api/v2/registros/{id}?motivo=pago — o verbo é DELETE por compatibilidade, mas o efeito é baixa: nada é apagado.

curl -X DELETE "https://confiaisp.com.br/api/v2/registros/adcf29ad-…?motivo=pago%20em%2011/09" \
  -H "Authorization: cfa_seu_token_aqui"

{"ok":true,"acao":"baixado","id":"adcf29ad-…"}

Franquia e consumo

GET /api/v2/uso — útil para o seu sistema avisar antes de a franquia acabar.

{"plano":"Basico","consultas_no_mes":37,"franquia":100,"em_cortesia":false,"cortesia_ate":null}

Webhook — o Confia avisando o seu sistema

Em vez de o seu sistema perguntar se mudou alguma coisa, a gente avisa. Ligue em Central → Integração: você informa a URL (precisa ser https, o aviso leva documento e valor) e recebe um segredo de assinatura, que aparece uma única vez.

POST https://seu-sistema.com.br/confia/webhook

X-Confia-Evento: registro.baixado
X-Confia-Entrega: 9f3c1a7e-...
X-Confia-Assinatura: t=1789102030,v1=4f1b...c9

{
  "evento": "registro.baixado",
  "em": "2026-09-11T18:32:10Z",
  "dados": {
    "id": "adcf29ad-...",
    "documento": "12345678000199",
    "nome": "NOME DO DEVEDOR",
    "valor_cents": 28490,
    "vencimento": "2026-05-04",
    "contrato": "C-9001",
    "status": "baixado",
    "motivo_baixa": "pago",
    "baixado_em": "2026-09-11T18:32:09Z"
  }
}

Como conferir a assinatura

O header X-Confia-Assinatura traz t (o instante do envio) e v1 (HMAC-SHA256 de t + "." + corpo, com o seu segredo). Compare com o que você calcular — e rejeite o que chegar com t muito antigo: é isso que impede alguém reenviar um aviso capturado.

// Node
const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
const esperado = crypto.createHmac("sha256", SEGREDO)
  .update(t + "." + corpoCru)   // o corpo CRU, antes do JSON.parse
  .digest("hex");

const ok = crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(esperado))
  && Math.abs(Date.now() / 1000 - Number(t)) < 300;

• Responda 2xx assim que receber. Redirect não conta como entrega.
• Processe depois de responder — o timeout é de 10 segundos.
• Repetimos 5 vezes com espera crescente: 1 min, 5, 30, 2h e 6h. Depois disso a entrega é marcada como falha e fica no log.
• Use o X-Confia-Entrega para idempotência: o mesmo id pode chegar duas vezes se a sua resposta se perder no caminho.
• Cada tentativa aparece em Central → Integração, com o status HTTP que voltou — quando alguém disser que o aviso não chegou, é lá que se confere.

Erros

Mudou em relação à API antiga

Endpoints de clientes, faturas e projetos da versão antiga não existem mais: eram do painel interno, não do produto. /api/v2/inadimplentes continua valendo como apelido de /api/v2/registros.

Boas práticas

• Um token por integração, com nome que diga qual é. Revogar fica barato.
• Consulte uma vez por candidato, não a cada tela: cada chamada custa franquia.
• Trate o 402 como cota, não como erro — avise o operador em vez de repetir.
• Dê baixa pela API no mesmo gancho em que o seu sistema baixa o título. É o que mantém a rede confiável e evita reclamação do negativado.