> ## Documentation Index > Fetch the complete documentation index at: https://docs.spedy.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Emissão de NF-e > Como emitir Notas Fiscais Eletrônicas (NF-e) pela API da Spedy. 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](/pages/guides/emissao-nfce) em vez desta página; se é prestação de serviço, veja [Emissão de NFS-e](/pages/guides/emissao-nfse). 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](/pages/guides/sincrono-vs-assincrono) e [Ciclo de vida da nota](/pages/guides/ciclo-de-vida-da-nota) antes de integrar o fluxo de emissão ao restante do seu sistema. ## Exemplo de criação ```bash cURL theme={null} curl -X POST https://sandbox-api.spedy.com.br/v1/product-invoices \ -H "X-Api-Key: sua-chave-de-api" \ -H "Content-Type: application/json" \ -d '{ "integrationId": "pedido-12345", "effectiveDate": "2026-08-03T10:00:00Z", "operationNature": "Venda de mercadoria", "isFinalCustomer": true, "receiver": { "name": "Cliente Exemplo", "federalTaxNumber": "11144477735", "email": "cliente@exemplo.com.br", "address": { "street": "Rua Exemplo", "number": "100", "district": "Centro", "postalCode": "01001000", "city": { "name": "São Paulo", "state": "SP" } } }, "payments": [ { "method": "pix", "amount": 100.0 } ], "items": [ { "code": "SKU-001", "description": "Produto Exemplo", "ncm": "61091000", "cfop": 5102, "unit": "UN", "quantity": 1, "unitAmount": 100.0, "unitTax": "UN", "quantityTax": 1, "unitTaxAmount": 100.0, "totalAmount": 100.0, "taxes": { "icms": { "origin": 0, "csosn": 102 }, "pis": { "cst": 49 }, "cofins": { "cst": 49 } } } ] }' ``` 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](/pages/guides/regimes-e-codigos-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](/pages/guides/fluxo-de-emissao) 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: | Bloco | Campo | Conteúdo | | ---------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Destinatário | `receiver` | Nome, `federalTaxNumber` (CPF/CNPJ), inscrição estadual/municipal, `email`, `address`. Para operações isentas em ZFM/Áreas de Livre Comércio, inclua `suframaTaxNumber`. | | Itens | `items[]` | Um item por produto: `code`, `description`, `ncm`, `cfop`, `unit`, `quantity`, `unitAmount`, `totalAmount`, além de `taxes` (tributação do item) e, quando aplicável, `specificProduct` (combustível, medicamento ou **veículo** — `specificProduct.vehicle`) e `trackings` (rastreabilidade por lote). | | Transporte/frete | `transport` | `freightModality`, `carrier` (transportadora), `volume`, `trailer` (reboque) e `vehicle` (veículo de transporte). Obrigatório quando há transporte físico da mercadoria associado à operação. | | Pagamentos | `payments[]` | `method` (`money`, `pix`, `creditCard`, `debitCard`, `bankDeposit`, `noPayment` etc.) e `amount`. **Obrigatório para autorizar**: desde a NF-e 4.0 a SEFAZ exige o grupo de pagamento em toda nota — em operações sem pagamento (remessa, devolução), informe `method: noPayment`. | | Faturamento | `billing` / `duplicates[]` | Dados da fatura (`billing`) e a lista de parcelas/duplicatas (`duplicates`), usados em vendas a prazo. | | Totais | `total` | Totais calculados da nota (`SefazInvoiceTotalDto`) — normalmente você envia os totais já calculados pelo seu sistema. | 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: | Operação | Endpoint | | -------------------------------------------- | ------------------------------------------------------------------ | | Listar notas | `GET /v1/product-invoices` | | Obter a nota (por ID) | `GET /v1/product-invoices/{id}` | | Baixar PDF (DANFE) | `GET /v1/product-invoices/{id}/pdf` | | Baixar XML | `GET /v1/product-invoices/{id}/xml` | | Consultar diretamente na SEFAZ (reconciliar) | `POST /v1/product-invoices/{id}/check-status` | | Emitir carta de correção | `POST /v1/product-invoices/{id}/corrections` | | Baixar PDF/XML da carta de correção | `GET /v1/product-invoices/{id}/corrections/{eventId}/pdf` e `/xml` | | Inutilizar faixa de numeração | `POST /v1/product-invoices/disablement` | | Reenviar e-mail ao destinatário | `POST /v1/product-invoices/{id}/resend-email` | Cancelamento, carta de correção e inutilização têm regras de prazo e uso específicas — veja [Cancelamento, correção e inutilização](/pages/guides/cancelamento-correcao-inutilizacao) antes de implementar qualquer uma delas. ## Próximos passos * Referência dos endpoints de NF-e: [Referência da API](/pages/reference/introducao) * Reenvios seguros e idempotência: [Idempotência e reprocessamento](/pages/start/idempotencia) * Estados possíveis da nota: [Ciclo de vida da nota](/pages/guides/ciclo-de-vida-da-nota) * Por que a emissão não é imediata: [Síncrono vs assíncrono](/pages/guides/sincrono-vs-assincrono) * CFOP, NCM e regime tributário: [Regimes e códigos fiscais](/pages/guides/regimes-e-codigos-fiscais)