Skip to main content
A NF-e (Nota Fiscal Eletrônica, modelo 55) é o documento fiscal para operações com produtos entre empresas ou entre empresa e pessoa física que não seja consumo em balcão — venda para revenda, remessa, transferência, devolução, exportação etc. Se a operação é venda de produto direto ao consumidor final em PDV/varejo, veja Emissão de NFC-e em vez desta página; se é prestação de serviço, veja Emissão de NFS-e.
Emitir pela API é sempre assíncrono: a resposta 2xx confirma que a nota foi aceita, não que foi autorizada pela SEFAZ. Veja Síncrono vs assíncrono e Ciclo de vida da nota antes de integrar o fluxo de emissão ao restante do seu sistema.

​
Exemplo de criação

cURL
Exemplo mínimo para empresas do Simples Nacional. A tributação por item usa:
  • icms.csosn: 102 — Tributada pelo Simples Nacional, sem permissão de crédito de ICMS ao destinatário.
  • pis.cst e cofins.cst: 49 — Outras operações de saída: um CST comum no Simples Nacional, em que PIS e COFINS são recolhidos no DAS, sem valor destacado na nota.
No Regime Normal o bloco taxes é diferente (ICMS com cst + base e alíquota, e PIS/COFINS com seus valores) — veja Regimes e códigos fiscais. O cfop 5102 é para operação dentro do estado; use 6102 quando emissor e destinatário estiverem em UFs diferentes.
Os valores de tributação deste exemplo têm fins didáticos e não substituem a orientação de um contador. A tributação correta depende do seu regime, do produto (NCM), da operação e da UF — valide com o seu contador ou responsável fiscal antes de emitir em produção.
Item informado inline (sem produto cadastrado) precisa do trio de tributação por unidade — unitTax (uTrib), quantityTax (qTrib) e unitTaxAmount (vUnTrib). Na maioria dos casos a unidade tributável é a mesma da comercial — basta espelhar unit/quantity/unitAmount. Elas só diferem quando a embalagem de venda ≠ unidade tributada (ex.: bebida vendida por fardo e tributada por lata, ovo por dúzia × unidade, atacado por caixa). Sem o trio, uTrib pode sair vazio (erro SPD003) ou vUnTrib zerado (rejeição SEFAZ 630). Se o item referencia um produto cadastrado, a Spedy preenche esse trio automaticamente.

​
Quando usar NF-e

Use POST /v1/product-invoices sempre que a operação envolver a saída ou entrada de produtos e não for venda a consumidor final em balcão (esse caso é NFC-e). Exemplos típicos: venda para outra empresa, remessa para industrialização, devolução de mercadoria, transferência entre filiais, venda de veículo por concessionária.

​
Fluxo de emissão

Assim como os demais modelos, a NF-e pode nascer de uma venda (order) com autoIssueMode, ou ser criada diretamente no endpoint de nota — veja Fluxo de emissão para os dois caminhos. Criando direto:
  1. POST /v1/product-invoices — cria a nota e já a enfileira para a SEFAZ (status: enqueued), sem passo de emissão separado.
  2. A Spedy envia o lote à SEFAZ e aguarda o retorno.
  3. Você acompanha o resultado por webhook (invoice.status_changed, invoice.authorized, invoice.rejected) ou consultando a nota — nunca pelo código HTTP do passo 1.

​
Estrutura do payload

O schema CreateProductInvoiceDto formalmente exige apenas isFinalCustomer. Na prática, a SEFAZ rejeita a nota se faltarem os blocos abaixo — eles são condicionalmente obrigatórios conforme o tipo de operação:
Há dois blocos de veículo distintos e não intercambiáveis: items[].specificProduct.vehicle descreve o veículo quando ele é o produto vendido (nota de concessionária), enquanto transport.vehicle descreve o veículo usado para transportar a mercadoria. Confirme qual dos dois a sua operação precisa antes de montar o payload.

​
Operações relacionadas

Além de criar e emitir, o endpoint de NF-e expõe operações para o ciclo de vida completo da nota: Cancelamento, carta de correção e inutilização têm regras de prazo e uso específicas — veja Cancelamento, correção e inutilização antes de implementar qualquer uma delas.

​
Próximos passos