O que a API de NF-e faz
Cada operação corresponde a um serviço do Fisco. A API cuida do leiaute, da assinatura e da conexão com o autorizador; sua aplicação trata o resultado.
| Operação | O que acontece | Retorno |
|---|---|---|
| Emitir | Valida os dados, gera o XML 4.00, assina e transmite ao autorizador. | HTTP 202, operação; após autorização, XML e DANFE |
| Consultar | Consulta a situação da NF-e pela chave de acesso. | Situação atual e protocolos |
| Cancelar | Registra o evento de cancelamento dentro do prazo legal. | Protocolo do evento |
| Corrigir | Registra a carta de correção eletrônica (CC-e). | Protocolo do evento |
| Inutilizar | Informa ao Fisco a faixa de numeração que não será usada. | Protocolo da inutilização |
| Baixar arquivos | Entrega o XML autorizado (nfeProc) e o DANFE. | XML e PDF |
Como funciona a emissão de NF-e por API
-
Validação
Os campos obrigatórios, o CFOP, o NCM e a soma dos totais são conferidos antes de qualquer envio ao Fisco.
-
Chave de acesso
A chave de 44 dígitos junta UF, ano e mês, CNPJ do emitente, modelo, série, número, tipo de emissão, código numérico e dígito verificador.
chNFe -
Assinatura
O XML é assinado com o certificado A1 cujo CNPJ base é o do emitente.
Signature -
Transmissão
O documento segue ao serviço de autorização da SEFAZ que atende a UF do emitente.
NFeAutorizacao4 -
Retorno
Autorizada, a NF-e volta com
cStat100 e o protocolo. Rejeitada, o registro permanece para correção e reenvio controlado; isso não representa autorização fiscal. Desde a NT 2024.001, irregularidade cadastral do emitente ou do destinatário também gera rejeição, e não mais denegação.protNFe -
Guarda e entrega
O XML autorizado é o documento fiscal; o DANFE é só a representação impressa. O destinatário deve receber o XML, e o emitente deve guardá-lo pelo prazo legal.
Sobre a guarda, veja por que o XML precisa ficar guardado por 5 anos.
Exemplo de emissão de NF-e
A chamada leva uma referência da sua aplicação, como o número do pedido. Ela permite consultar o resultado sem reenviar a nota quando a resposta não chega.
POST https://erp.fideflow.com.br/api/flow-fiscal/v1/homologacao/emitentes/{emitente}/documentos/nfe
Authorization: Bearer {credencial_de_homologacao}
Content-Type: application/json
Idempotency-Key: exemplo-nfe-001
{
"referencia_externa": "exemplo-nfe-001",
"dados": {
"cabecalho": {
"natureza_id": 1,
"cliente_id": 1,
"total": "10.00",
"tipo_pagamento": "01"
},
"itens": [
{
"produto_id": 1,
"quantidade": "1.00",
"valor_unitario": "10.00",
"sub_total": "10.00",
"cfop": "5102"
}
],
"pagamentos": [
{
"tipo_pagamento": "01",
"valor": "10.00",
"data_vencimento": "2026-10-21"
}
]
}
}HTTP/1.1 202 Accepted
Location: https://erp.fideflow.com.br/api/flow-fiscal/v1/homologacao/emitentes/{emitente}/operacoes/{operacao_id}
Retry-After: 5
Content-Type: application/json
{"dados":{"id":"{operacao_id}","estado":"enfileirada","url":"https://erp.fideflow.com.br/api/flow-fiscal/v1/homologacao/emitentes/{emitente}/operacoes/{operacao_id}"}}Requisição extraída do OpenAPI v1; resposta ilustrativa do aceite. IDs e valores são fictícios e precisam corresponder aos cadastros e à operação do emitente. HTTP 202 ainda não é autorização fiscal.
Pontos de atenção na NF-e
- Numeração: cada série tem sequência própria. Ao trocar de emissor, continue do último número usado na série ou adote uma série nova.
- Destinatário: a inscrição estadual e o indicador de contribuinte (
indIEDest) precisam bater com o cadastro da SEFAZ. - Tributação: CFOP, CST ou CSOSN, NCM e alíquotas vêm da sua aplicação. A API transmite e devolve a rejeição quando algo não fecha; ela não substitui a orientação contábil.
- Reforma Tributária: em 2026 a NF-e carrega os grupos de IBS e CBS, com CST e cClassTrib próprios. Veja o guia de IBS e CBS na NF-e e na NFC-e.
- Tempo esgotado: consulte pela referência ou pela chave antes de reenviar. Reenviar às cegas é a origem mais comum da rejeição por duplicidade.
Rejeições frequentes na emissão de NF-e, com causa e correção:
Perguntas frequentes sobre a API de NF-e
Preciso de certificado digital para emitir NF-e pela API?
Sim. A NF-e é assinada com o certificado ICP-Brasil do emitente. Para emissão em servidor, use o A1, um arquivo .pfx com senha. O certificado da matriz serve para as filiais quando a raiz do CNPJ é a mesma.
Quem define CFOP, CST e alíquotas?
O emitente. A API monta e transmite o que a sua aplicação informa e devolve a rejeição da SEFAZ quando o conjunto não fecha. A classificação tributária continua sendo decisão do emitente e da contabilidade.
Qual é o prazo para cancelar uma NF-e?
A regra geral é de 24 horas após a autorização, desde que a mercadoria não tenha circulado. Algumas UFs aceitam cancelamento fora desse prazo, com condições próprias. Se o prazo passou, avalie com a SEFAZ da UF e a contabilidade o cancelamento extemporâneo ou o procedimento aplicável; nota de devolução ou de estorno exige fundamento próprio.
O que a carta de correção pode corrigir?
A CC-e não pode alterar valores ligados ao imposto, como base de cálculo, alíquota, quantidade e preço, nem dados que mudem o remetente ou o destinatário, nem a data de emissão ou de saída. Cada NF-e admite até 20 cartas de correção, e a mais recente substitui as anteriores: consolide nela todas as correções que devem continuar valendo.
Como testar a emissão sem valor fiscal?
Use o ambiente de homologação da SEFAZ. Lá, o nome do destinatário precisa ser o texto padrão de homologação, e as notas não têm valor fiscal. O guia de homologação e produção traz o roteiro de testes.
Fontes oficiais
No teste grátis do Flow Fiscal, a API de emissão vem completa, sem contratar; depois do teste, requer plano Flow Fiscal ativo e o opcional de emissão contratado. Exige certificado A1 válido e vínculo autorizado de cada CNPJ. CT-e, CT-e OS e MDF-e atendem o modal rodoviário; NFS-e segue o padrão nacional e os requisitos do município. Consulte as capacidades do emitente antes de transmitir.