Documentos, UFs e municípios
O primeiro filtro é o que você emite hoje e o que vai emitir em um ano. Uma API que cobre bem a NF-e pode não ter a NFC-e da sua UF nem a NFS-e do seu município.
- Documentos: NF-e, NFC-e, CT-e, CT-e OS, MDF-e e NFS-e. Confirme os modelos que você usa, os eventos disponíveis, como cancelamento e carta de correção, e os serviços de numeração, como a inutilização, quando se aplicam.
- UFs: a NFC-e tem regras de QR Code e de contingência por estado. Peça a lista de UFs em produção, não só em homologação.
- NFS-e: confirme se a emissão é pelo padrão nacional, por sistemas municipais ou pelos dois, e se o seu município e a sua operação estão cobertos.
- Reforma Tributária: confirme os leiautes e cronogramas de IBS e CBS de cada documento e do regime do emitente. Nos modelos que usam CST e cClassTrib, pergunte como a API recebe esses campos e acompanha as notas técnicas. Veja o guia de IBS e CBS na NF-e e na NFC-e.
Retorno, falhas e contingência
A emissão falha de formas previsíveis: rejeição, tempo esgotado e autorizador fora do ar. É nessas horas que as APIs se diferenciam.
| Situação | O que perguntar |
|---|---|
| Tempo esgotado | A API impede duas emissões para a mesma operação, por uma referência ou chave de idempotência? Depois de um tempo esgotado, como consultar o processamento e repetir o pedido com segurança? |
| Rejeição | O retorno preserva o código e o motivo do autorizador, seja a SEFAZ ou o sistema da NFS-e, para você corrigir o dado certo? |
| Autorizador fora do ar | A API entra em contingência? Em qual modalidade, e quem transmite os documentos depois? |
| Resultado assíncrono | Há aviso por webhook ou só consulta? O aviso é assinado e reenviado quando o seu sistema não responde? |
Para entender o que muda em cada caso, veja como emitir nota fiscal por API e o guia de contingência.
Certificado digital e dados dos clientes
- Certificado: confirme os tipos aceitos pela API e o que é preciso para automatizar a emissão. Se o arquivo A1 e a senha ficarem com o fornecedor, pergunte como são protegidos, quem tem acesso e como é a troca na renovação. Veja o guia do certificado A1.
- Dados pessoais: o XML traz CPF, nome e endereço de consumidores e tomadores. A LGPD vale para esses dados; pergunte onde ficam, por quanto tempo e como são excluídos.
- Acesso: chaves de API separadas por ambiente e por aplicação, que possam ser revogadas uma a uma sem parar as outras.
Guarda de XML e arquivos
- Guarda: o emitente precisa manter os XMLs pelo prazo exigido pela legislação. Confirme por quanto tempo a API guarda os arquivos e como exportá-los em lote. Veja prazos e cuidados na guarda de XML.
- Documentos auxiliares: DANFE, DANFE NFC-e, DACTE e DANFSe em PDF, com o seu logotipo quando o leiaute permite.
- Saída: se trocar de fornecedor, exporte os XMLs e os eventos e preserve o histórico de numeração por emitente, modelo e série. Na NFS-e nacional, confira a sequência das DPS; o número da NFS-e é atribuído pelo sistema nacional.
Integração e ambiente de testes
- Homologação: emitir no ambiente de testes antes da produção, com as mesmas chamadas e respostas. Veja homologação e produção.
- Documentação: contrato publicado, por exemplo em OpenAPI, exemplos por documento e mensagens de erro descritas.
- Limites: requisições por minuto, tamanho de lote e o que acontece quando o limite é atingido.
- Suporte: canal e horário de atendimento para incidentes de emissão.
Modelo de cobrança
APIs de nota fiscal cobram por nota emitida, por CNPJ, por faixa de volume ou por uma combinação desses. Para comparar, monte a conta com o seu volume real e com o volume do mês de pico.
- Quanto custa cada nota acima da franquia.
- Se eventos, como cancelamento e carta de correção, e consultas também são cobrados.
- Se há custo por CNPJ, por filial ou pelo ambiente de homologação.
- Se a guarda dos XMLs tem limite de tempo ou de espaço.
Checklist para a conversa com o fornecedor
| Pergunta | Por que importa |
|---|---|
| Quais documentos, UFs e municípios estão em produção hoje? | Cobertura em homologação não garante emissão real. |
| Como consulto uma nota quando a resposta não chega? | Reenviar sem verificar o processamento e a idempotência pode gerar duplicidade. |
| O que acontece quando a SEFAZ fica fora do ar? | Sem contingência, o caixa e a expedição param. |
| Onde ficam o certificado e os XMLs? | Segurança do certificado e obrigações da LGPD. |
| Como exporto tudo se eu sair? | Evita ficar preso ao fornecedor. |
| Como a API vai tratar IBS e CBS? | A Reforma Tributária muda os documentos a partir de 2026. |
Perguntas frequentes
Qual é a melhor API de nota fiscal?
A que cobre os documentos, as UFs e os municípios da sua operação e trata bem as falhas. Compare pelo checklist com o seu volume real: a melhor opção para um e-commerce que só emite NF-e pode não servir a uma transportadora que precisa de CT-e e MDF-e.
Existe API de nota fiscal gratuita?
Os serviços de autorização da SEFAZ e da NFS-e nacional não cobram pela autorização, mas exigem que o seu sistema monte, assine e transmita o XML, trate as rejeições e guarde os arquivos. As APIs de terceiros cobram para fazer esse trabalho.
Vale mais a pena usar uma API ou integrar direto com a SEFAZ?
Integrar direto exige manter leiautes, certificados, conexões com cada autorizador e as mudanças das notas técnicas. Uma API concentra esse trabalho; em troca, você depende do fornecedor e paga pelo serviço.
Posso trocar de API depois?
Pode. Leve os XMLs e os eventos emitidos, preserve a numeração por emitente, modelo e série (na NFS-e nacional, a sequência das DPS) e refaça a homologação no fornecedor novo antes de virar a produção.
Preciso de uma API ou de um ERP?
Se você já tem um sistema de vendas, faturamento ou transporte, a API acrescenta a emissão a ele. Se não tem, um sistema de gestão com emissão integrada costuma resolver mais rápido.