Produto

API de nota fiscal: 12 perguntas para fazer antes de contratar

Idempotência, webhook assinado, lote, sandbox, multi-CNPJ, certificado A1 e limites: o checklist técnico para escolher uma API de nota fiscal para alto volume.

Lucas Rannye7 min de leitura
Neste artigo

Uma API de nota fiscal se prova no dia em que a rede cai no meio de 5.000 emissões. As 12 perguntas abaixo separam a API que aguenta esse dia da que gera nota duplicada e webhook perdido; no fim, como a emite.ai responde a cada uma.

Por que a API pesa mais que o preço

Porque o sistema do governo faz só o passo simples. No padrão nacional da nota de serviço, ele recebe a declaração (DPS) e devolve a nota ou o motivo da recusa na mesma chamada. Para saber se uma DPS já virou nota, há uma consulta pelo identificador da DPS (município, inscrição, série e número). As duas estão no manual das APIs do Emissor Nacional.

Manual dos Contribuintes do Sistema Nacional NFS-e: geração síncrona da nota e consulta pela DPS

Numeração, reenvio sem duplicar, consulta de situação e cidades com regras próprias ficam com o fornecedor.

As 12 perguntas

1. Se eu reenviar a mesma nota, sai uma segunda?

Timeout não quer dizer que a nota falhou, e retry sem idempotência emite duas notas para a mesma venda. Peça cabeçalho de idempotência e referência do pedido, e que a repetição devolva a nota original. O Idempotency-Key está em padronização na IETF.

POST /api/v1/invoices HTTP/1.1
Host: emitenota.ai
Content-Type: application/json
Idempotency-Key: pedido-8823

2. O webhook é assinado e reentregue?

Sem assinatura, qualquer um posta no seu endpoint; sem reentrega, o evento some quando o seu servidor cai. Peça HMAC com carimbo de tempo, id de entrega fixo e a tabela de novas tentativas.

X-Emite-Delivery: whd_3f9a1c2b7d4e5f60a1b2c3d4
X-Emite-Signature-V2: t=1762963258,v1=96f42f43012e9c0d16252826e9a04e2f579064234155659e89a4b91e44bb1e17

3. Dá para emitir em lote, e se um item falhar?

Lote em que um item ruim derruba os outros 499 obriga a reprocessar tudo. Peça itens independentes, resultado por item e um status HTTP que avise a falha parcial.

{ "summary": { "total": 500, "created": 498, "replayed": 1, "retidas": 0, "failed": 1 } }

4. Existe ambiente de testes com a mesma requisição?

Integrar contra notas reais é caro e arriscado; o próprio portal nacional separa documentação de produção e de testes. Peça uma chave de teste que aceite o mesmo corpo, sem gerar documento e sem consumir cota.

5. Emito para vários CNPJs com uma integração só?

Plataforma, grupo e franquia emitem por dezenas de empresas. Pergunte se a empresa vai em cada nota, quantos CNPJs o plano aceita e se o cadastro sai por API.

6. O certificado A1 pode ser enviado por API?

Com 50 empresas, subir certificado tela por tela não fecha a conta. Peça envio do arquivo e da senha por API, conferência do CNPJ e armazenamento criptografado. Mais em certificado digital A1.

7. Cobre o Emissor Nacional e as prefeituras fora do padrão?

Cidades grandes mantêm sistema próprio. Peça a cobertura por município e o que acontece com cidade não coberta: a nota deve ser barrada antes, com motivo, nunca enviada às cegas.

8. Emite NF-e e já trata os campos da reforma?

Pergunte quais modelos a API emite hoje e como preenche IBS e CBS. O cronograma está em IBS e CBS na nota fiscal e o layout novo em novo layout da nota fiscal de serviço.

9. Qual é o limite de requisições e como ele aparece?

Limite escondido vira erro no pico de vendas. Peça os números por escrito e o formato da resposta: 429 com Retry-After (RFC 6585) e cabeçalhos com o saldo.

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-11-16T14:03:00.000Z

10. O que é cobrado como nota?

Pergunte o que entra na contagem (só a nota emitida, ou também falha, teste e documento recebido) e o que acontece quando a cota do mês acaba: a nota é recusada ou espera?

11. Como acompanho a situação de cada nota?

Peça a lista de estados, um código de falha legível por máquina e um id de requisição para citar no suporte.

12. Reembolso e cancelamento são automáticos?

Venda reembolsada com nota de pé é problema fiscal. Pergunte como se cancela por API, o que acontece com nota que não chegou ao fisco e se o reembolso na plataforma cancela a nota sozinho. Prazos em cancelamento de nota fiscal.

Como a emite.ai responde a cada uma

A API da emite.ai está nos planos Business, Business+ e Enterprise. Tudo abaixo está na documentação aberta em emitenota.ai/developers, conferida em 14/11/2026.

#Resposta da emite.ai
1Idempotency-Key devolve a nota original; corpo diferente com a mesma chave dá 409. externalRef é único na conta: repetido volta com Idempotent-Replay: true, alterado dá 409 EXTERNAL_REF_CONFLICT
2Emitida, falha e cancelamento, com HMAC-SHA256 e carimbo de tempo. 2xx em até 10 s; novas tentativas em 1 min, 5 min, 30 min, 2 h, 6 h, 12 h e 24 h (até 8 envios). Entregas listadas e reenviadas por API
3/v1/invoices/batch com até 500 notas e resposta 207 em falha parcial; /v1/batches assíncrono, 202 na hora e acompanhamento por item
4Chave emite_test_: mesma requisição, resposta com "sandbox": true, sem documento real e sem cota
5companyId ou cnpj em cada nota; cadastro de empresa por API. Até 5 CNPJs no Business, 10 no Business+, sem limite no Enterprise
6POST /v1/companies/:id/certificate: valida o arquivo e a senha, confere o CNPJ e guarda os dois criptografados; a senha não volta em nenhuma resposta
7Padrão nacional e sistemas próprios de prefeituras, como São Paulo e Barueri
8A API emite nota de serviço; NF-e pela API está no roadmap. Com o grupo de IBS e CBS ligado na empresa, a nota do padrão nacional sai com ele e é barrada antes do envio se faltar a classificação
9100 requisições por minuto por chave, 60 escritas por minuto e 300 notas por hora por conta, ajustáveis por contrato; 429 com Retry-After e cabeçalhos X-RateLimit-*
10Conta a nota emitida. Falha, pendência e teste não contam; com a cota do mês esgotada, a nota fica retida e sai quando a cota renova
11Estados de PENDING a EMITTED, FAILED ou CANCELLED, com failureCode e X-Request-Id; GET /v1/account/status mostra cota, empresas prontas e limites
12Cancelamento por API com justificativa e Idempotency-Key obrigatória; nota que não chegou ao fisco é descartada na hora. Nas integrações com plataformas de venda, o reembolso cancela a nota por padrão

Conferido em 14/11/2026

Perguntas frequentes

Idempotência resolve tudo sobre nota duplicada?

Resolve o reenvio da mesma requisição. Se o mesmo pedido chega por dois caminhos, só a referência do pedido barra a segunda nota.

Webhook ou consulta em loop?

Webhook. A consulta em loop gasta limite; deixe-a para reconciliar o dia.

Preciso de um certificado A1 por CNPJ?

Sim. Cada empresa assina as próprias notas, e o certificado vence: acompanhe a validade de todos.

Dá para testar antes de assinar?

Peça a chave de testes e rode o fluxo inteiro, do lote ao webhook. Fornecedor sem ambiente de testes já respondeu a pergunta 4.

Lucas RannyeFundador da emite.ai

A próxima nota é com a gente.

Comece agora