API de NFS-e pelo padrão Nacional: emissão, consulta e webhooks

Seu sistema emite a nota no instante da venda: um POST /notas devolve a NFS-e autorizada no padrão Nacional, com XML, PDF e chave de acesso. Autenticação Bearer por CNPJ, idempotência por referência externa, sandbox e sete webhooks assinados — a integração fica de pé em uma tarde.

O que a API cobre

• Emitir, consultar, cancelar e substituir notas;
• Notas recebidas contra o CNPJ (DistDFe) e sincronização;
• Clientes/tomadores e certificado digital;
• Fechamento de competência (pacote ZIP + CSV e envio ao contador);
• Uso e cota do plano; rotação de chave; simulação de retenções.

Emitir uma nota

curl -X POST "https://robofiscal.com.br/app/api/v1/notas" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"cliente_id": 12, "valor_servico": 1500.00,
       "discriminacao": "Consultoria de marketing — agosto/2026",
       "referencia_externa": "pedido-889"}'

A chave é por CNPJ e identifica a empresa emitente — não se envia CNPJ nas requisições. Com a empresa em ambiente producao, esta chamada emite documento fiscal real e irreversível; teste antes no sandbox.

Idempotência: retry não duplica nota

Emitir nota é irreversível, então a API é idempotente por desenho: envie referencia_externa com o identificador do seu pedido e, se a chamada repetir por timeout, a API devolve a nota que já existe com "idempotente": true em vez de emitir outra. As demais rotas de escrita aceitam o header Idempotency-Key com a mesma garantia.

Webhooks: sete eventos, assinados

Cada entrega leva X-Robofiscal-Signature — HMAC SHA-256 de timestamp.corpo com o segredo mostrado uma única vez no cadastro. Endpoint fora do ar? A entrega é retentada em 5 min, 30 min, 1 h, 3 h e 24 h; depois vai para a fila de falhas definitivas, de onde sai por replay. O payload identifica a empresa pelo CNPJ, nunca por id interno.

Sandbox: teste sem certificado

Empresa em ambiente sandbox monta e grava a DPS sem ir à SEFIN — a chave começa com SANDBOX e nada emitido ali tem valor fiscal. É o lugar de errar à vontade antes de ir a produção.

Limites e cotas

Documentação

Swagger completo no painel, especificação OpenAPI aberta e o /llms.txt — se você está integrando com ajuda de uma IA, aponte o agente para lá: ele traz o que a API faz, o que não faz e as regras que um gerador de código precisa respeitar.

Perguntas frequentes

Publicado em 23/08/2026 · Atualizado em 23/08/2026 · RoboFiscal — Mahalo Ventures Ltda