Emitir uma NFe (Nota Fiscal Eletrônica)
A NFe é o documento fiscal padrão para operações B2B e B2C com entrega. Este recipe cobre o fluxo completo desde o cadastro até o XML autorizado.
Pré-requisitos
- Token de integração obtido (ver Autenticação)
- Configurações fiscais cadastradas na empresa (CFOP, CST, alíquotas)
- Cliente (CPF/CNPJ) e produtos cadastrados ou enviados inline
Fluxo
-
(Opcional) Cadastrar produtos e cliente
Se ainda não estão na base:
Terminal window # Produtocurl -X POST $BASE/produtos \-H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \-d '{"referencia": "SKU-001","nome": "Camiseta Polo","valor": "89.90","medida": "UN","ncm": "61051000","origem": "0","cfop-preferencial": "5102"}'# Cliente PJcurl -X POST $BASE/clientes \-H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \-d '{"tipo": "J","razao-social": "Cliente Exemplo Ltda","cnpj": "12345678000199","tipo-inscricao-estadual": "1","inscricao-estadual": "123456789","endereco": {"cep": "01310100", "rua": "Av. Paulista", "numero": "1000","bairro": "Bela Vista", "cidade": "São Paulo", "estado": "SP"}}' -
Emitir a NFe
Terminal window curl -X POST $BASE/nfe/emissao \-H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \-d '{"serie": "1","cfop": "5102","numero-origem": "PED-2026-00042","tipo": "S","finalidade": "N","valor-despesas": "0.00","cliente": "12345678000199","transporte": {"modalidade": "9"},"itens": [{ "produto": "SKU-001", "quantidade": "2", "valor-unitario": "89.90" }]}'Resposta:
{"status": "001","descricao": "Nota registrada com sucesso.","data": { "recibo": "rec_abc123" },"meta": { "request_id": "req_...", "timestamp": "..." }} -
Aguardar processamento (polling)
Use intervalo mínimo de 2 segundos. Veja Fluxo assíncrono.
Terminal window curl $BASE/nfe/nota/rec_abc123 \-H "Authorization: Token $TOKEN"Status terminal:
004— NFe emitida ✅010— Cancelada900— Rejeitada SEFAZ (vejadata.sefaz.mensagem) — **exceto sedata.sefaz.codigofor217/105: aí é SEFAZ lenta/instável, não é definitivo. Continue consultando, não reemita. Veja SEFAZ lenta ou instável
-
Pegar o DANFE e XML
Quando
status: "004":{"status": "004","data": {"sefaz": {"chave": "3526...","protocolo": "...","url-danfe": "https://...","url-xml": "https://..."}}}Baixe e armazene esses arquivos (XML é o documento fiscal, DANFE é a representação visual).
Variações comuns
Com transporte (modalidade ≠ 9)
{ "serie": "1", "cfop": "5102", "cliente": "12345678000199", "transporte": { "modalidade": "0", "transportadora": "98765432000111", "placa-veiculo": "ABC-1D23", "valor-frete": "150.00", "valor-seguro": "0.00", "peso-bruto": "5.5", "peso-liquido": "5.0", "quantidade-volume": "1", "especie-volume": "Caixa", "marca-volume": "Embalagem padrão" }, "itens": [ ... ]}Nas modalidades 0 (por conta do remetente) e 1 (por conta do destinatário), a transportadora é
opcional desde a 3.22.0 — omitida, a nota sai sem transportador identificado. Nas modalidades 2,
3 e 4 ela continua obrigatória.
Com faturas (vendas a prazo)
{ ..., "faturas": [ { "valor": "299.50", "data": "2026-06-15" }, { "valor": "299.50", "data": "2026-07-15" } ]}Com notas referenciadas (devolução / complementar)
{ ..., "finalidade": "D", "notas-referenciadas": [ "35260512345678000199550010000000011000000010" ]}Com guia de trânsito agropecuário (rejeições 311 / 836)
Exclusivo de NFe. Use quando a operação exige Guia de Trânsito (produtos agropecuários animais, vegetais ou florestais) — o que evita as rejeições SEFAZ 311 (Guia de Trânsito Vegetal) e 836 (Guia de Trânsito Animal). O preenchimento é manual: você informa a guia quando sabe que aquela operação (pela combinação de NCM, CFOP e UF) a exige — a API não infere isso sozinha. O objeto guia é opcional; omita-o quando não houver guia.
{ ..., "guia": { "tipo": "6", "numero": "123456789", "uf": "SP" }}| Campo | Obrigatório | Descrição |
|---|---|---|
tipo | Não (opcional) | Tipo da guia (enum): 1-GTA, 2-TTA, 3-DTA, 4-ATV, 5-PTV, 6-GTV, 7-Guia Florestal |
numero | Se tipo informado | Número da guia — apenas dígitos |
uf | Se tipo informado | Sigla do estado da guia (ex.: SP, RS, MG) |
Natureza da operação
O texto da natureza da operação (natOp do XML e do DANFE) é, por padrão, a descrição do CFOP — para o
5102, “Venda de mercad adquirida ou receb de Terc.”. Para usar outro texto, envie natureza-operacao
(opcional, até 60 caracteres):
{ ..., "cfop": "5102", "natureza-operacao": "VENDA DE MERCADORIA"}Omitido ou em branco, vale a descrição do CFOP, como sempre.
Substituição tributária retida (CSOSN 500 / CST 60) e CEST
Venda de mercadoria com ICMS-ST já recolhido anteriormente (ex.: CFOP 5405 com CSOSN 500): os campos de ST
retido do XML (vBCSTRet, pST, vICMSSubstituto, vICMSSTRet) não são enviados na emissão — a
nota os calcula a partir da configuração fiscal do produto (bloco icms.aliquotas em POST /produtos ou
PUT /produtos/{ref}):
| Campo da configuração | Uso no XML |
|---|---|
aliquota-mva (e percentual-reducao-bc-st) | vBCSTRet = valor do item com a MVA aplicada (e a redução) |
aliquota-icms | vICMSSubstituto = ICMS próprio do substituto |
percentual-icms-st-ret | pST, e vICMSSTRet = vBCSTRet × pST − vICMSSubstituto |
Os cálculos acima só acontecem com percentual-icms-st-ret maior que zero. Com ele zerado ou omitido
— mesmo que haja MVA —, os quatro campos saem 0.00, inclusive a base vBCSTRet (não assume o valor do
produto). O grupo é sempre enviado para CSOSN 500; não há opção para omiti-lo. O CEST vai pelo campo cest do
cadastro do produto (7 dígitos) e é levado ao XML automaticamente.
Tributos aproximados (Lei 12.741/2012)
A Faz Nota calcula o valor aproximado dos tributos de cada item pela tabela do IBPT (por NCM e UF,
atualizada mensalmente) e informa no XML da NF-e o vTotTrib de cada item e o total da nota
(ICMSTot/vTotTrib). Não há campo para enviar: o cálculo é automático. O envio do vTotTrib é
ativado por empresa — peça ao suporte. Item cujo NCM não consta no IBPT sai sem o campo.
Rateio do frete entre os itens
O transporte.valor-frete é o frete total da nota; a Faz Nota o distribui entre os itens no XML
(prod/vFrete), e o frete de cada item entra na base do ICMS-ST quando a empresa calcula ICMS sobre o frete.
| Critério | Como cada item recebe | Quando vale |
|---|---|---|
| Igual por linha (padrão) | frete ÷ quantidade de itens | Sempre, a menos que a empresa ative o proporcional |
| Proporcional ao valor | frete × valor do item ÷ soma dos itens | Ativado por empresa — peça ao suporte |
Nos dois critérios o valor de cada item é truncado em 2 casas e a diferença de arredondamento vai para o
último item, de modo que a soma sempre fecha com o vFrete da nota. Exemplo com frete de R$ 45,00 e itens
de R$ 1,00, R$ 2,00 e R$ 1,00: igual = 15,00 / 15,00 / 15,00; proporcional = 11,25 / 22,50 / 11,25.
Não há campo para enviar no payload: o critério é configuração da empresa e vale para a API e para o
painel. Nota com todos os itens a R$ 0,00 usa o rateio igual.
Com IBS / CBS (reforma tributária)
A v3 já contempla os tributos IBS e CBS, dentro da configuração fiscal do produto (bloco cbs-ibs, ao lado de ipi/pis-cofins/icms). O bloco é opcional — se omitido, a API preenche valores padrão. Veja a página dedicada IBS / CBS (Reforma Tributária) para a estrutura completa, os campos e os defaults.
Limites de validação importantes
| Campo | Regra |
|---|---|
serie | Numérico entre 1 e 999 (no máx. 3 dígitos) |
chave (em referenciadas) | Exatamente 44 caracteres |
observacao | Até 2.000 caracteres |
natureza-operacao | Opcional; até 60 caracteres |
marca-volume, especie-volume | Até 60 caracteres |
placa-veiculo | Regex AAA-9999 ou Mercosul AAA-9A99 |
itens | Pelo menos 1 item |
guia.tipo | Se informado: enum 1–7; torna guia.numero (dígitos) e guia.uf (sigla) obrigatórios |
Erros comuns
Mensagem (data.erro) | Causa | Correção |
|---|---|---|
Campo nfe@cliente documento não pertence a um cliente cadastrado. | CPF/CNPJ desconhecido | Cadastre o cliente antes ou envie objeto inline |
Campo nfe@cfop inválido. | CFOP não numérico | Use 4 dígitos numéricos (ex.: 5102) |
Campo nfe@transporte@placa-veiculo inválido. | Placa não bate regex | Use formato AAA-9999 ou Mercosul AAA-9A99 |
Campo nfe@itens não pode ser vazio. | Array vazio | Envie pelo menos um item |
Campo nfe@natureza-operacao inválido: máximo de 60 caracteres ... | Texto com mais de 60 caracteres | Encurte o texto ou omita o campo para usar a descrição do CFOP |