Pular para o conteúdo

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

  1. (Opcional) Cadastrar produtos e cliente

    Se ainda não estão na base:

    Terminal window
    # Produto
    curl -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 PJ
    curl -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"
    }
    }'
  2. 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": "..." }
    }
  3. 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 — Cancelada
    • 900 — Rejeitada SEFAZ (veja data.sefaz.mensagem) — **exceto se data.sefaz.codigo for 217/105: aí é SEFAZ lenta/instável, não é definitivo. Continue consultando, não reemita. Veja SEFAZ lenta ou instável
  4. 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"
}
}
CampoObrigatórioDescrição
tipoNão (opcional)Tipo da guia (enum): 1-GTA, 2-TTA, 3-DTA, 4-ATV, 5-PTV, 6-GTV, 7-Guia Florestal
numeroSe tipo informadoNúmero da guia — apenas dígitos
ufSe tipo informadoSigla 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çãoUso no XML
aliquota-mva (e percentual-reducao-bc-st)vBCSTRet = valor do item com a MVA aplicada (e a redução)
aliquota-icmsvICMSSubstituto = ICMS próprio do substituto
percentual-icms-st-retpST, 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érioComo cada item recebeQuando vale
Igual por linha (padrão)frete ÷ quantidade de itensSempre, a menos que a empresa ative o proporcional
Proporcional ao valorfrete × valor do item ÷ soma dos itensAtivado 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

CampoRegra
serieNumérico entre 1 e 999 (no máx. 3 dígitos)
chave (em referenciadas)Exatamente 44 caracteres
observacaoAté 2.000 caracteres
natureza-operacaoOpcional; até 60 caracteres
marca-volume, especie-volumeAté 60 caracteres
placa-veiculoRegex AAA-9999 ou Mercosul AAA-9A99
itensPelo menos 1 item
guia.tipoSe informado: enum 1–7; torna guia.numero (dígitos) e guia.uf (sigla) obrigatórios

Erros comuns

Mensagem (data.erro)CausaCorreção
Campo nfe@cliente documento não pertence a um cliente cadastrado.CPF/CNPJ desconhecidoCadastre o cliente antes ou envie objeto inline
Campo nfe@cfop inválido.CFOP não numéricoUse 4 dígitos numéricos (ex.: 5102)
Campo nfe@transporte@placa-veiculo inválido.Placa não bate regexUse formato AAA-9999 ou Mercosul AAA-9A99
Campo nfe@itens não pode ser vazio.Array vazioEnvie pelo menos um item
Campo nfe@natureza-operacao inválido: máximo de 60 caracteres ...Texto com mais de 60 caracteresEncurte o texto ou omita o campo para usar a descrição do CFOP

Próximos passos