Certum Fiscal API — Documentação

1. Autenticação

Gere o clientId e o clientSecret no portal (Configurações da API). Troque-os por um token de acesso válido por 1 hora (OAuth 2.0 client_credentials). Também é aceito o header Authorization: Basic base64(clientId:clientSecret).

curl -X POST https://api.certum-fiscal-api.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"cf_live_...","client_secret":"cfs_..."}'

Resposta: { "access_token": "...", "token_type": "Bearer", "expires_in": 3600, "ambiente": "producao" }. Envie o token em todas as chamadas: Authorization: Bearer <access_token>.

Ambientes: credenciais cf_live_ são de produção e cf_test_ de homologação. Cada ambiente tem limites, consumo e webhook próprios.

2. Rotas

Método e rota	O que faz	Resposta
POST /v1/oauth/token	Gera o token de acesso	imediata
GET /v1/cnpj/{cnpj}	Dados cadastrais do CNPJ na Receita	imediata
GET /v1/inscricao-estadual/{uf}/{cnpj}	Situação da inscrição estadual	imediata
POST /v1/certidoes	Pede uma certidão: `tipo` = CND_FEDERAL, CRF_FGTS, CNDT ou CND_ESTADUAL (com `uf`); `referencia` opcional (seu identificador)	202 + id; resultado no webhook
GET /v1/certidoes/{id}	Situação do pedido (PROCESSANDO, CONCLUIDA ou ERRO) e o resultado	imediata
GET /v1/certidoes/{id}/pdf	PDF oficial da certidão	application/pdf
GET /v1/consumo	Consumo do mês e limites do ambiente	imediata (não conta no limite)

curl https://api.certum-fiscal-api.com/v1/cnpj/11222333000181 \
  -H "Authorization: Bearer <access_token>"

curl -X POST https://api.certum-fiscal-api.com/v1/certidoes \
  -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" \
  -d '{"tipo":"CND_FEDERAL","cnpj":"11222333000181","referencia":"pedido-123"}'

Certidões dependem dos portais do governo e costumam levar de 5 segundos a 2 minutos. Por isso o pedido responde na hora com um id e o resultado é enviado ao seu webhook. Se preferir, consulte GET /v1/certidoes/{id} a cada 10–15 segundos.

3. Webhook

Cadastre a URL (HTTPS) no portal. Enviamos um POST JSON quando uma certidão termina, com até 3 tentativas se sua URL não responder 2xx.

{
  "id": "5b6c...",                 // id da entrega
  "evento": "certidao.concluida",  // ou certidao.erro, webhook.teste
  "ambiente": "producao",
  "criadoEm": "2026-10-02T14:03:11.000Z",
  "dados": {
    "id": "8f1e...", "tipo": "CND_FEDERAL", "cnpj": "11222333000181", "uf": null,
    "referencia": "pedido-123", "status": "CONCLUIDA",
    "resultado": { "situacao": "Negativa", "dataEmissao": "2026-10-02", "dataValidade": "2027-03-31", "codigoControle": "..." },
    "pdf": "https://api.certum-fiscal-api.com/v1/certidoes/8f1e.../pdf",
    "erro": null
  }
}

Headers: X-Certum-Event, X-Certum-Delivery e X-Certum-Signature: sha256=<HMAC do corpo com o segredo do webhook>.

// Node.js — confira a assinatura antes de confiar no conteúdo
const crypto = require('crypto')
const esperado = 'sha256=' + crypto.createHmac('sha256', WEBHOOK_SECRET).update(corpoBruto).digest('hex')
const ok = crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(req.headers['x-certum-signature']))

4. Limites e erros

Cada ambiente tem limite por minuto e limites mensais (total e por tipo de consulta), conforme contrato. Acima do limite a resposta é 429 com o limite e o uso atual. Chamadas com dados inválidos (400) não contam no consumo.

HTTP	codigo	Significado
400	cnpj_invalido, tipo_invalido, uf_obrigatoria…	Pedido com dados inválidos (não conta)
401	token_invalido, credenciais_invalidas, credencial_revogada	Autenticação
402 / 403	conta_suspensa, conta_sem_api	Conta sem acesso
404	nao_encontrada, pdf_indisponivel	Recurso inexistente neste ambiente
422	consulta_falhou	O órgão não respondeu ou recusou a consulta (conta no consumo)
429	limite_atingido	Limite por minuto ou mensal atingido

Formato dos erros: { "erro": { "codigo": "...", "mensagem": "..." } }.

Certum Fiscal · suporte: responda o e-mail do seu contrato.