O que a API de NFC-e faz
A NFC-e substituiu o cupom fiscal de equipamento. No caixa, a venda precisa virar documento autorizado em segundos, com o QR Code que o consumidor usa para consultar a nota.
| Operação | O que acontece | Retorno |
|---|---|---|
| Emitir | Gera o XML, monta o QR Code, assina e transmite. | HTTP 202, operação; após autorização, XML e DANFE NFC-e |
| Consultar | Consulta a situação pela chave de acesso. | Situação atual e protocolos |
| Cancelar | Registra o cancelamento dentro do prazo da UF. | Protocolo do evento |
| Inutilizar | Informa ao Fisco a faixa de numeração que não será usada. | Protocolo da inutilização |
| Contingência off-line (somente SP) | Exige escopo, aceite e regularização posterior. | Operação e artefatos de contingência |
| Baixar arquivos | Entrega o XML autorizado e o DANFE NFC-e. | XML e PDF |
Como funciona a emissão de NFC-e por API
-
Venda em JSON
Itens, descontos, formas de pagamento com valores e, quando houver, o troco. A soma dos pagamentos precisa cobrir o total da nota.
detPag -
Consumidor
Informar CPF ou CNPJ é opcional na maior parte das vendas; a legislação exige a identificação em casos como valor elevado e entrega em domicílio.
-
QR Code
Na versão 2, o QR Code leva a chave, o ambiente e um código de verificação calculado com o CSC. A versão 3, da NT 2025.001, usa assinatura digital na contingência. Vale a versão em vigor na UF.
qrCode -
Autorização
A NFC-e é transmitida à SEFAZ da UF, que responde na mesma conexão.
NFeAutorizacao4 -
DANFE NFC-e
Após a autorização, sua aplicação pode imprimir ou entregar o documento ao consumidor conforme a regra da UF. A API não envia e-mail nem mensagem automaticamente.
Exemplo de emissão de NFC-e
POST https://erp.fideflow.com.br/api/flow-fiscal/v1/homologacao/emitentes/{emitente}/documentos/nfce
Authorization: Bearer {credencial_de_homologacao}
Content-Type: application/json
Idempotency-Key: exemplo-nfce-001
{
"referencia_externa": "exemplo-nfce-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"
}
]
}
}Exemplo de homologação extraído do OpenAPI v1. IDs são fictícios; consulte o contrato completo e acompanhe a operação após HTTP 202.
Pontos de atenção na NFC-e
- CSC: onde a versão do QR Code usa CSC, a SEFAZ fornece um para homologação e outro para produção. Trocar só o ambiente e manter o CSC de teste faz o QR Code falhar.
- Sem carta de correção: a NFC-e não admite CC-e. Erro de dado exige cancelamento, dentro do prazo, e nova emissão.
- Prazo de cancelamento: definido pela legislação de cada UF e, em várias delas, menor que o da NF-e.
- Venda pela internet ou para outra UF: use NF-e. A NFC-e com operação não presencial é rejeitada (rejeição 717), e operação interestadual não cabe na NFC-e.
- Contingência off-line da API, somente em SP e com requisitos próprios: a nota precisa ser transmitida assim que a comunicação voltar, no prazo da UF. Veja o guia de contingência.
Rejeições que aparecem no caixa, com causa e correção:
Perguntas frequentes sobre a API de NFC-e
O que é o CSC da NFC-e e onde consigo?
O Código de Segurança do Contribuinte é um par de identificador e código que a SEFAZ da UF fornece ao emitente, um para homologação e outro para produção. Na versão 2 do QR Code, ele entra no código de verificação. A NT 2025.001 criou a versão 3, com assinatura digital na contingência; confira na SEFAZ da UF qual versão vale para você.
Posso usar NFC-e no e-commerce?
Em regra, não. A NFC-e é para venda a consumidor final, presencial ou com entrega em domicílio, dentro da UF. A NFC-e com operação não presencial é rejeitada (rejeição 717), e operação interestadual usa NF-e.
O que acontece se a SEFAZ estiver fora do ar?
Nesta API, a contingência off-line está habilitada somente em SP, com escopo, aceite explícito e regularização posterior. A falta de resposta exige consulta e conciliação antes de retransmitir. O cancelamento por substituição não está habilitado nesta versão; sua existência nas regras fiscais não significa disponibilidade pela API.
Preciso de impressora fiscal?
Não. O DANFE NFC-e sai em qualquer impressora não fiscal, normalmente térmica, ou é enviado ao consumidor em meio eletrônico quando a UF permite.
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.