Documentação da API

Versão 1 · Base: https://api.suacnd.com/v1

Autenticação

Gere uma chave no painel e envie em todas as chamadas:

Authorization: Bearer scnd_live_...

1. Solicitar uma certidão

curl -X POST https://api.suacnd.com/v1/emissoes \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-123" \
  -d '{"portal":"fgts-caixa","documento":"12.345.678/0001-95","referencia_externa":"cliente-42"}'

Resposta 202: a emissão entra na fila e o valor do portal é debitado do saldo.

{ "id": "8f1c…", "portal": "fgts-caixa", "status": "na_fila", ... }

Idempotency-Key (opcional) evita cobrar duas vezes se você repetir o pedido. webhook_url (opcional) substitui o webhook da conta só para esse pedido.

2. Acompanhar

curl https://api.suacnd.com/v1/emissoes/{id} -H "Authorization: Bearer $CHAVE"

status	significado
`na_fila`	aguardando um robô
`processando`	o robô está no portal
`emitida`	certidão negativa (ou positiva com efeito de negativa) em `certidao.pdf_url`
`pendencia`	o portal não emitiu (débito, irregularidade); motivo e print em `pendencia`
`erro`	falha técnica (portal fora do ar etc.) após as novas tentativas; valor estornado

Os links de PDF valem 15 minutos. Para um link novo, consulte a emissão de novo ou use GET /v1/emissoes/{id}/pdf.

3. Webhook

Quando a emissão termina enviamos um POST com o mesmo corpo de GET /v1/emissoes/{id} e o cabeçalho:

X-SuaCND-Assinatura: t=1760112000,v1=<hmac_sha256_hex>

Para validar: calcule HMAC-SHA256(segredo_do_webhook, t + "." + corpo_bruto) e compare com v1. O segredo está no painel. Responda 2xx; caso contrário tentamos de novo por até 24 horas.

Outras rotas

`GET /v1/portais`	portais disponíveis e preços (sem autenticação)
`GET /v1/emissoes?status=&limite=&antes=`	lista paginada (use `proxima_pagina` em `antes`)
`GET /v1/emissoes/{id}/pdf`	redireciona para o PDF
`GET /v1/conta`	saldo e dados da conta

Portais

portal	certidão	preço
`fgts-caixa`	CRF – Certificado de Regularidade do FGTS	R$ 1,00
`linhares-es`	CND Municipal – Linhares/ES	R$ 1,00

Erros

{ "erro": { "codigo": "saldo_insuficiente", "mensagem": "..." } }

401 chave inválida · 402 saldo insuficiente · 403 e-mail não confirmado ou conta bloqueada · 404 não encontrada · 422 dados inválidos · 429 muitas requisições (limite: 120/min por chave)