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:

# 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"
    }
  }'

Emitir a NFe

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

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": [ ... ]
}

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

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
`marca-volume`, `especie-volume`	Até 60 caracteres
`placa-veiculo`	Regex `AAA-9999` ou Mercosul `AAA-9A99`
`itens`	Pelo menos 1 item

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