# API de NF-e: Nota Fiscal Eletrônica

> A API de NF-e da FideFlow recebe os dados da operação em JSON, monta o XML no leiaute 4.00 da Nota Fiscal Eletrônica (modelo 55), assina com o certificado A1 do emitente e transmite à SEFAZ autorizadora. O aceite HTTP 202 inicia o processamento. Após a autorização, consulta e webhook informam situação, chave, protocolo, XML e DANFE em PDF.

- Produto: Flow Fiscal — API de emissão (disponível no flow fiscal)
- Página: https://fideflow.com.br/api-nota-fiscal/nfe
- Atualizado em: 2026-10-21
- Publicado por: FideFlow
- Oferta: adicional de R$ 29,90/mês além do plano Flow Fiscal, com 300 autorizações em produção por contratante/ciclo mensal compartilhadas entre CNPJs; excedente automático R$ 0,50. Cancelamento posterior não estorna consumo.

## Ficha técnica
| Campo | Valor |
| --- | --- |
| Modelo | 55 |
| Leiaute | 4.00, com os grupos da Reforma Tributária |
| Autorizador | SEFAZ da UF do emitente ou Sefaz Virtual que atende a UF |
| Chave de acesso | 44 dígitos |
| Documento auxiliar | DANFE |
| Eventos | Cancelamento e carta de correção (CC-e) |
| Numeração | Inutilização de faixa não usada |
| Testes | Homologação, sem valor fiscal |
| Contingência da API | Não habilitada nesta versão |
| Certificado | ICP-Brasil A1 do emitente |

## 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
1. **Validação.** Os campos obrigatórios, o CFOP, o NCM e a soma dos totais são conferidos antes de qualquer envio ao Fisco.
2. **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.
3. **Assinatura.** O XML é assinado com o certificado A1 cujo CNPJ base é o do emitente.
4. **Transmissão.** O documento segue ao serviço de autorização da SEFAZ que atende a UF do emitente.
5. **Retorno.** Autorizada, a NF-e volta com `cStat` 100 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.
6. **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](https://fideflow.com.br/blog/fiscal/guarda-xml-5-anos-obrigatoria).

## 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.

**Requisição**

```http
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"
            }
        ]
    }
}
```

**Resposta**

```json
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](https://fideflow.com.br/blog/fiscal/novos-campos-ibs-cbs-nfe-nfce-2026).
- **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:

- [Rejeição 204: Duplicidade de NF-e](https://fideflow.com.br/sefaz/rejeicao/204)
- [Rejeição 539: Duplicidade de NF-e com diferença na chave de acesso](https://fideflow.com.br/sefaz/rejeicao/539)
- [Rejeição 225: Falha no schema XML do lote de NF-e](https://fideflow.com.br/sefaz/rejeicao/225)
- [Rejeição 233: IE do destinatário não cadastrada](https://fideflow.com.br/sefaz/rejeicao/233)
- [Rejeição 302: Irregularidade fiscal do destinatário](https://fideflow.com.br/sefaz/rejeicao/302)

## Perguntas frequentes
### 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](https://fideflow.com.br/api-nota-fiscal/guias/homologacao-e-producao) traz o roteiro de testes.

## Fontes oficiais
- [Portal Nacional da NF-e](https://www.nfe.fazenda.gov.br/portal/principal.aspx)
- [Portal DF-e da SVRS: NF-e](https://dfe-portal.svrs.rs.gov.br/Nfe)

## Veja também
- [Como emitir nota fiscal por API](https://fideflow.com.br/api-nota-fiscal/guias/como-emitir-nota-fiscal-por-api.md)
- [Homologação e produção na emissão de notas](https://fideflow.com.br/api-nota-fiscal/guias/homologacao-e-producao.md)
- [Contingência na emissão de notas fiscais](https://fideflow.com.br/api-nota-fiscal/guias/contingencia.md)
- [Certificado digital A1 para emitir nota por API](https://fideflow.com.br/api-nota-fiscal/guias/certificado-digital-a1.md)
- [Validar XML de NF-e online](https://fideflow.com.br/ferramentas/validar-xml-nfe-online)
- [Converter XML em DANFE (PDF)](https://fideflow.com.br/ferramentas/xml-para-danfe-pdf)
- [Consultar NCM](https://fideflow.com.br/ferramentas/consultar-ncm)
- [Carta de correção eletrônica: o que pode alterar](https://fideflow.com.br/blog/fiscal/carta-correcao-eletronica-cce)
- [API de nota fiscal: visão geral](https://fideflow.com.br/api-nota-fiscal.md)

---
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.