Conceitos NF-e / NFC-e

Fundamentos fiscais para integrar com a API de NF-e (modelo 55) e NFC-e (modelo 65). Todos os endpoints usam o prefixo https://platform.notaas.com.br/api/v1 e requerem x-api-key.

⚠️ Homologação vs Produção

O ambiente é definido pela variável NFE_AMBIENTE do servidor. Em homologação (tp_amb=2), as notas são emitidas no SEFAZ de teste e não possuem validade fiscal.

Modelo 55 (NF-e) vs Modelo 65 (NFC-e)

	NF-e (55)	NFC-e (65)
Uso	B2B, vendas por atacado, e-commerce	Vendas ao consumidor final (PDV)
Destinatário	Obrigatório (CNPJ/CPF + endereço)	Opcional (consumidor anônimo)
DANFE	A4 completo	Cupom térmico com QR Code
CSC	Não requer	Obrigatório (configurar em Settings)
Emitente	CNPJ (PJ) ou CPF (Produtor Rural PF com IE ativa)	Exclusivo CNPJ (PJ) na plataforma
Séries	1–889 (CNPJ) · 920–969 (CPF Produtor Rural)	Independentes (1–999)
Prazo de Cancelamento (API)	24h padrão nacional (Ajuste SINIEF 07/05, Cl. 12ª); janelas estendidas via Web Service em PR/RS (168h / 7 dias), SP (480h / 20 dias) e CE (720h / 30 dias)	Configurado por UF em `uf_nfe_config` (30min em SP e, na base de produção, SE; 24h nas demais UFs)

CRT — Código de Regime Tributário

CRT	Regime	Tributação dos itens
1	Simples Nacional (ME/EPP)	Usa CSOSN (ex: 102, 500)
2	SN — Excesso de Sublimite	Usa CST (ex: 00, 20, 60)
3	Regime Normal (Lucro Presumido/Real)	Usa CST (ex: 00, 10, 20, 60)
4	Simples Nacional — MEI	Usa CSOSN (NF-e: 102, 300, 400, 900 \| NFC-e: 102, 300)

CST vs CSOSN — ICMS

O campo de tributação de cada item depende do CRT do emitente:

CST (CRT 2 ou 3)

00 — Tributada integralmente

10 — Tributada com cobrança do ICMS ST

20 — Redução de base de cálculo

40 — Isenta

41 — Não tributada

51 — Diferimento

60 — ICMS cobrado anteriormente por ST

70 — Redução de base de cálculo e cobrança do ICMS ST

90 — Outros (com destaque de ICMS próprio e/ou ICMS ST)

CSOSN (CRT 1 — Simples Nacional | CRT 4 — MEI)

102 — Tributada pelo SN sem permissão de crédito (CRT 1 e CRT 4 MEI)

103 — Isenção para faixa de receita bruta (CRT 1)

201 — Tributada pelo SN com permissão de crédito e com cobrança do ICMS ST (apenas CRT 1)

300 — Imune (CRT 1 e CRT 4 MEI)

400 — Não tributada pelo SN (CRT 1 e CRT 4 MEI em NF-e)

500 — ICMS cobrado anteriormente por ST (CRT 1)

900 — Outros (permite destaque de ICMS próprio e ICMS ST em NF-e modelo 55 para devoluções e operações especiais)

Origem da Mercadoria — Tabela A do ICMS (items[].origem ou orig, tag XML <orig>)

Padrão / Fallback: 0 (Nacional)

O valor informado em items[].origem (ou orig) é convertido por Number(...): se o resultado for um inteiro entre 0 e 8 (ex.: número 0..8 ou string numérica "0".."8"), ele é utilizado; quando omitido ou quando a conversão não produzir inteiro no intervalo 0–8, a plataforma aplica automaticamente o fallback legado 0 (Nacional).

0 — Nacional, exceto as indicadas nos códigos 3, 4, 5 e 8

1 — Estrangeira — Importação direta, exceto a indicada no código 6

2 — Estrangeira — Adquirida no mercado interno, exceto a indicada no código 7

3 — Nacional, conteúdo de importação > 40% e ≤ 70%

4 — Nacional, produção conforme processos produtivos básicos (PPB)

5 — Nacional, conteúdo de importação ≤ 40%

6 — Estrangeira — Importação direta, sem similar nacional (CAMEX) ou gás natural

7 — Estrangeira — Adquirida no mercado interno, sem similar nacional (CAMEX) ou gás natural

8 — Nacional, mercadoria ou bem com Conteúdo de Importação > 70%

CFOP — Principais códigos

O CFOP define a natureza da operação fiscal de cada item:

Saídas Internas (dentro do estado)

5101 — Venda de produção do estabelecimento (indústria / produtor rural)

5102 — Venda de mercadoria adquirida

5405 — Venda de mercadoria com ST (SN)

5411 — Devolução de compra para comercialização com ST

5949 — Outra saída não especificada

Saídas Interestaduais

6101 — Venda de produção do estabelecimento (indústria / produtor rural)

6102 — Venda de mercadoria adquirida

6108 — Venda para consumidor final (não contribuinte)

6411 — Devolução de compra para comercialização com ST

6949 — Outra saída não especificada

Entradas do Exterior (Importação — tpNF: 0)

3101 — Compra para industrialização

3102 — Compra para comercialização

3551 — Compra de bem para ativo imobilizado

Saídas para o Exterior (Exportação — tpNF: 1)

7101 — Venda de produção do estabelecimento

7102 — Venda de mercadoria adquirida de terceiros

7949 — Outra saída de mercadoria ou prestação de serviço

Nota Fiscal de Produtor Rural Eletrônica (NFP-e — Modelo 55)

A NFP-e (Nota Fiscal de Produtor Rural Eletrônica) não possui um modelo técnico separado na SEFAZ: ela é emitida sob o próprio Modelo 55 (NF-e), seguindo as regras do Ajuste SINIEF 07/05 e da NT 2018.001. A plataforma Notaas suporta integralmente produtores rurais Pessoa Física (CPF + Inscrição Estadual ativa) e Pessoa Jurídica (CNPJ).

Produtor Rural Pessoa Física (CPF)Séries 920–969

Identificação: CPF (11 dígitos) + Inscrição Estadual numérica ativa na UF (2 a 14 dígitos — não admite ISENTO).
Regime Tributário: obrigatoriamente Regime Normal (CRT = 3 / regimeTributario = "1").
Certificado Digital: exige e-CPF A1 (.pfx/.p12) cujo CPF de 11 dígitos coincida exatamente com o CPF do projeto (validado no upload quando o documento ICP-Brasil está presente no certificado, prevenindo a Rejeição SEFAZ 227).
Série Obrigatória: faixa 920 a 969 (padrão 920) para emissão própria (procEmi=0, regras B26-10 / C02a-10, Rejeições 244 e 495). Na chave de acesso de 44 dígitos, as posições 7 a 20 são preenchidas com 000 + 11 dígitos do CPF.
Escopo de Modelo: habilitado exclusivamente para NF-e (modelo 55) na plataforma.

Produtor Rural Pessoa Jurídica (CNPJ)Séries 1–889

Identificação: CNPJ (14 dígitos) + Inscrição Estadual ativa na UF.
Regime Tributário: Regime Normal (CRT = 3) ou Simples Nacional (CRT = 1 ou 2).
Certificado Digital: exige e-CNPJ A1 com mesma raiz de 8 dígitos do CNPJ do projeto (validado no upload quando o documento ICP-Brasil está presente no certificado, prevenindo a Rejeição SEFAZ 213).
Série Obrigatória: faixa 1 a 889 (padrão 1) na emissão própria (procEmi=0). Séries 920–969 são bloqueadas para CNPJ (previne Rejeições 244 e 503).

Diferimento de ICMS (`CST 51`) e Nota de Produtor Referenciada (`refNFP`)

Diferimento Total ou Parcial (CST 51 — Grupo N07): ao informar percentualDiferimento (pDif de 0 a 100), a API calcula automaticamente a base de cálculo (com suporte opcional a redução de BC via percentualReducaoBc e cBenefRBC), o ICMS da operação (vICMSOp), a parcela diferida (vICMSDif) e o ICMS efetivamente devido (vICMS = vICMSOp - vICMSDif), somando apenas o vICMS efetivo no <ICMSTot> (evitando as Rejeições 351, 352, 353 e 532). Caso nenhum subcampo de diferimento seja enviado, a plataforma preserva o caminho legado de compatibilidade (modBC, vBC, pICMS, vICMS).
Referenciamento de NF de Produtor em Papel (refNFP — Grupo BA10): para notas fiscais de entrada em cooperativas/agroindústrias ou remessas vinculadas a talão/nota avulsa estadual (modelos 04 ou 01), utilize o array refNFP no cabeçalho da emissão (finalidade: 1, 2 ou 3).
Funrural, Senar e Dispositivos Legais: menções ao recolhimento de Funrural/Senar, número de guia/termo ou artigo do RICMS estadual que ampara o diferimento devem ser enviados nos campos infCpl (ou alias informacoesComplementares) e/ou infAdFisco (informacoesAdicionaisFisco).

Data de Emissão e Retroatividade (Competência)

Diferente da NFS-e (onde existe um campo explícito de competência municipal separado da emissão do RPS), na NF-e e NFC-e a competência fiscal é determinada exclusivamente pela data e hora de emissão (dhEmi / dataEmissao).

NF-e (Modelo 55)Até 30 dias

Permite retroatividade de até 30 dias em relação à data/hora de transmissão (regra SEFAZ B09-20 / Rejeição 228). Esse recurso é essencial para operações de fechamento contábil mensal, notas de entrada por importação ou remessas faturadas retroativamente.

NFC-e (Modelo 65)Máx. 5 minutos

Por ser voltada ao comércio varejista presencial (PDV), a NFC-e não admite retroatividade contábil. A SEFAZ tolera atraso máximo de 5 minutos entre a geração e a transmissão (regra SEFAZ B09-40).

Regras de Validação e Chave de Acesso

Tolerância no Futuro (ambos os modelos): a data de emissão não pode ultrapassar 5 minutos no futuro em relação ao relógio oficial da SEFAZ (regra B09-10 / Rejeição 703).
Dígitos AAMM da Chave de Acesso: as posições 3 a 6 da chave de 44 dígitos (ano e mês) são calculadas com base na data de emissão informada no horário oficial de Brasília (America/Sao_Paulo), e não no momento do envio à SEFAZ. Uma nota emitida em 03/09 com data retroativa de 31/08 terá o prefixo mensal da chave referente a agosto (2608).
Formato Apenas-Data (YYYY-MM-DD): quando informada apenas a data sem horário, para datas passadas o sistema fixa 12:00:00 (horário de Brasília). Se a data informada for o dia corrente (“hoje”), o sistema utiliza o menor entre o horário atual e 12:00:00, evitando rejeição indevida de notas transmitidas pela manhã.
Data e Hora de Saída ou Entrada (dataSaida / dhSaiEnt — Campo B10): opcional e exclusiva para NF-e Modelo 55 (proibida na NFC-e Modelo 65 — Regra B10-10 / Rejeição 705). Quando informada, gera a tag <dhSaiEnt> no XML e preenche o quadro de saída/entrada no DANFE. Deve respeitar o limite de até 30 dias no futuro (Regra B10-20 / Rejeição 504) ou 30 dias no passado (Regra B10-30 / Rejeição 505) em relação à transmissão, e nas notas de saída (tpNF=1) não pode ser anterior à dataEmissao (Regra B10-40 / Rejeição 506). Quando enviada apenas como YYYY-MM-DD, o parser aplica primeiro o horário-base de data pura (12:00:00 BRT para datas passadas/futuras ou min(agora, 12:00:00 BRT) quando a data é hoje) e, sempre que YYYY-MM-DD coincidir com o mesmo dia civil de dhEmi em Brasília e o instante base ficar anterior a dhEmi, eleva o horário para dhEmi (evitando violação da Regra B10-40 em notas de saída).

CNPJ Alfanumérico e Chave de Acesso (IN RFB nº 2.229/2024 & NT Conjunta 2025.001)

A plataforma Notaas suporta integralmente o CNPJ Alfanumérico (SS.SSS.SSS/SSSS-DD — regex canônica [0-9A-Z]{12}\d{2}) em coexistência com os CNPJs puramente numéricos já emitidos, seguindo a Instrução Normativa RFB nº 2.229/2024 e a Nota Técnica Conjunta 2025.001 (ENCAT/RFB).

Estrutura e Cálculo do DV do CNPJASCII − 48 (Módulo 11)

Posições 1 a 8 (Raiz) e 9 a 12 (Ordem): aceitam dígitos (0–9) e letras maiúsculas (A–Z).
Posições 13 e 14 (Dígitos Verificadores): permanecem estritamente numéricas (0–9).
Conversão ASCII − 48: cada caractere é convertido pelo código ASCII subtraído de 48 ('0'=0 .. '9'=9, 'A'=17 .. 'Z'=42), preservando 100% de retrocompatibilidade para CNPJs numéricos.
Exemplo oficial RFB: 12.ABC.345/01DE-35 (sem máscara: 12ABC34501DE35, DV = 35).

Chave de Acesso de 44 Posições (cDV)NT Conjunta 2025.001

Posições 7 a 20 (Emitente): comportam os 14 caracteres do CNPJ alfanumérico ([0-9A-Z]{12}\d{2}) ou o CPF com prefixo 000.
Cálculo do 44º caractere (cDV): calculado automaticamente pelo Módulo 11 aplicando charCodeAt(i) - 48 e pesos de 2 a 9 da direita para a esquerda sobre as 43 posições anteriores.
Eventos e Inutilização: o Id de eventos (110110 CC-e e 110111 Cancelamento) e o Id de 43 caracteres da Inutilização (ID + 41 posições) aceitam nativamente CNPJ alfanumérico.
Impressão no DANFE: formatado como SS.SSS.SSS/SSSS-DD nos quadros de Emitente, Destinatário e Transportador, e em 11 blocos de 4 caracteres na Chave de Acesso.

Motor Fiscal Inteligente — ICMS e DIFAL Automáticos

A API da Notaas foi projetada para emissão sem atrito. Na maioria das operações, você não precisa calcular nem enviar alíquotas ou valores de imposto no payload.

✨ Autonomia Total por Padrão

Ao receber uma emissão, o motor fiscal cruza automaticamente o endereço do emitente e do destinatário, o regime tributário da empresa (CRT) e as tabelas tributárias oficiais dos 27 estados para:

Identificar a rota interestadual: aplica 7% (Sul/Sudeste para N/NE/CO/ES) ou 12% (demais rotas);
Proteger o ICMS próprio na saída: em vendas interestaduais, assegura o teto legal da rota, evitando rejeições da SEFAZ (cStat 693);
Calcular o DIFAL com Base Dupla (LC 190/2021): para Regime Normal (CRT 3), embute a alíquota interna da UF de destino na base e deduz o crédito interestadual sobre a base original (cStat 815);
Calcular o DIFAL em Base Simples: para empresas do Simples Nacional (CRT 1, 2 e 4 - MEI);
Apurar FCP (Fundo de Combate à Pobreza): aplica o percentual padrão da UF de destino (ex: RJ 4%, AM 2%, SP 0%).

Campos de Override Opcionais (Casos Especiais)

Os campos de alíquota são 100% opcionais. Envie-os apenas se o seu produto tiver uma regra ou benefício fiscal específico:

Campo no Item	Tipo	Quando utilizar
aliquotaInterestadual	number (ex: 4)	Produtos importados com mais de 40% de conteúdo de importação (Resolução do Senado nº 13/2012), forçando 4%.
aliquotaIcmsUfDest	number (ex: 25)	Produtos com alíquota interna específica no estado de destino (ex: cosméticos a 25%, bebidas a 32% ou medicamentos a 12%).
percentualFcpUfDest	number (ex: 2)	Produtos supérfluos sujeitos a FCP adicional no estado de destino (quando diferente do padrão da UF).
aliquotaIcms	number (ex: 12)	Alíquota interna própria para vendas estaduais ou benefícios fiscais com redução na origem.

Configuração NFC-e

A NFC-e (modelo 65) exige configurações adicionais em relação à NF-e. Sem elas, a SEFAZ rejeita a emissão com códigos específicos.

CSC — Código de Segurança do Contribuinte

O CSC é um par (ID + Token) exclusivo do CNPJ, obtido no portal da SEFAZ da UF do emitente. Ele é usado para gerar o hash SHA-1 do QR Code que acompanha o DANFE NFC-e.

⚠️ Sem CSC configurado

A emissão será rejeitada com cStat=600 (CSC não cadastrado). Configure o CSC em Configurações → NFC-e ou via PATCH /api/v1/org (campos nfceCscId e nfceCscToken).

Diferenças de Configuração NFC-e vs NF-e

Aspecto	NF-e (55)	NFC-e (65)
CSC	Não requer	Obrigatório (par ID + Token)
Destinatário	Obrigatório (CNPJ/CPF + endereço)	Opcional (consumidor anônimo)
Presença	0–5, 9 (qualquer)	Apenas 1, 4 ou 5
Numeração	Série própria	Série independente da NF-e
Credenciamento	SEFAZ UF	Pode exigir credenciamento separado na SEFAZ

Resiliência, Idempotência de Retry e Contingência Automática

O motor de emissão da Notaas combina idempotência estrita em retries, auto-reconciliação com a SEFAZ e Contingência Automática (SVC) para impedir duplicidade de chaves (cStat 539) e garantir consistência mesmo sob lentidão ou instabilidade da SEFAZ estadual.

🔒 Idempotência de Retry e Auto-Reconciliação SEFAZ

Persistência Atômica Pré-Transmissão: antes de enviar o SOAP NFeAutorizacao4 à SEFAZ, o worker adquire lock exclusivo na invoice (SELECT ... FOR UPDATE) e persiste o n_nf, a chave_acesso (incluindo o cNF aleatório de 8 dígitos) e o XML <NFe> já assinado.
Reutilização Integral em Retries Pós-Envio Ambíguos: se a comunicação sofrer falha pós-conexão com resultado incerto (ETIMEDOUT / ECONNRESET) ou rejeição transitória sem troca de regime (ex.: cStat 999), qualquer nova tentativa da fila no mesmo regime (tpEmis) reutiliza exatamente a mesma chave de acesso e o mesmo XML assinado, eliminando o risco de gerar uma segunda chave diferente para o mesmo número (cStat 539). A única exceção em que a chave e o XML são regenerados é quando ocorre fallback explícito para contingência SVC (tpEmis 6 ou 7) diante de falha pré-envio (ECONNREFUSED/ENOTFOUND/EHOSTUNREACH) ou retorno explícito de indisponibilidade (cStat 108, 109), mantendo ainda assim o mesmo cNF.
Auto-Reconciliação Automática (NFeRetAutorizacao4 / NFeConsultaProtocolo4): ao retomar uma emissão após timeout ou ao receber cStat 204 (Duplicidade de NF-e), o worker consulta automaticamente o recibo (nRec) e o protocolo da chave de 44 dígitos na SEFAZ. Se a nota já tiver sido autorizada (cStat 100/150), a plataforma recupera o <protNFe> oficial, monta o <nfeProc versao="4.00">, marca a nota como issued e dispara o webhook nfe.issued normalmente.

Como funciona o Fallback SVC

Caso o autorizador primário recuse a conexão antes do envio (ECONNREFUSED, ENOTFOUND, EHOSTUNREACH) ou retorne indisponibilidade explícita (cStat 108, 109), o Notaas realiza automaticamente:

Troca do regime de emissão para SVC-AN (tpEmis=6) ou SVC-RS (tpEmis=7) conforme a UF (exclusivo NF-e mod. 55).
Geração de uma nova Chave de Acesso com o mesmo cNF e o novo tpEmis, atualizada atomicamente antes do envio.
Proteção contra Dupla Autorização: em erros pós-conexão onde o pacote SOAP já pode ter sido recebido pelo autorizador normal (ETIMEDOUT / ECONNRESET), o fallback SVC não é acionado — a nota aguarda retry e auto-reconciliação no autorizador de origem.

💡 Importante para o Integrador:

A Chave de Acesso autorizada na contingência será diferente da chave teórica do regime normal. Sempre utilize o campo chaveAcesso retornado no webhook nfe.issued ou na consulta de status como única fonte da verdade.

Reciclagem Conservadora vs. Inutilização de Numeração (`POST /api/v1/nfe/inutilizar`)

Quando o número é reciclado automaticamente: se a SEFAZ rejeitar a nota por erro determinístico de schema ou regra de validação (ex.: cStat 215, 225, 531, 778), o número jamais existiu na SEFAZ e é devolvido ao pool nfe_numeros_liberados para ser reaproveitado automaticamente na próxima emissão da série.
Quando o número é bloqueado por segurança: em códigos de duplicidade (204, 539), inutilização prévia (206, 241, 256, 563, 662), uso denegado (110, 301, 302, 303) ou falhas de comunicação pós-transmissão sem confirmação da SEFAZ, o número nunca é reciclado para o pool, evitando colisões em emissões futuras.
Quando inutilizar via API (POST /api/v1/nfe/inutilizar): sempre que um número ou faixa ficar pulado na sequência da série (por exemplo, após avançar manualmente a numeração em Configurações ou migrar de outro emissor) e nunca tiver sido autorizado na SEFAZ, envie o pedido de inutilização pelo endpoint POST /api/v1/nfe/inutilizar até o encerramento da apuração mensal.