# Emitir NF-e

`POST /nfe?ref=SUA-REF`: emite uma NF-e. A resposta é **assíncrona**: `202` significa que a nota foi aceita, tem número reservado e está a caminho da SEFAZ.

| | |
|---|---|
| **Rota** | `POST /api/v2/nfe?ref={ref}` |
| **Corpo** | JSON com a venda (destinatário, itens, pagamentos...) |
| **Qual empresa emite** | `cnpj_emitente` no corpo (ou na query). Conta com **uma só** empresa dispensa o campo |
| **Limite** | 120 emissões por minuto por chave (ajustável por conta) |

| Resposta | Quando |
|---|---|
| `202` | aceita e na fila (ou a nota da `ref` já estava em andamento com este mesmo conteúdo) |
| `200` | a `ref` já tinha uma nota **com este mesmo conteúdo**, em estado final: devolve o estado atual |
| `404` | a empresa não é da sua conta (`empresa_nao_encontrada`) |
| `409` | a `ref` já pertence a uma nota com **outro** conteúdo (`ref_ja_utilizada`) |
| `422` | requisição inválida (`requisicao_invalida`), cálculo fiscal recusado (`validacao_fiscal`) ou empresa não informada (`cnpj_emitente_obrigatorio`) |

Tudo o que dá para recusar sem a SEFAZ volta como `422` **aqui, antes de gastar um número da série**: nota recusada na validação não deixa buraco na numeração.

## O exemplo mínimo

Venda para um consumidor final (pessoa física) em outro estado, paga por PIX. É o menor corpo que emite uma nota completa:

<!-- exemplo:emitir -->
```json
{
  "nome_destinatario": "Maria da Silva",
  "cpf_destinatario": "529.982.247-25",
  "logradouro_destinatario": "Av Atlantica",
  "numero_destinatario": "500",
  "bairro_destinatario": "Copacabana",
  "municipio_destinatario": "Rio de Janeiro",
  "codigo_municipio_destinatario": "3304557",
  "uf_destinatario": "RJ",
  "cep_destinatario": "22010-000",
  "items": [
    {
      "codigo_produto": "CAMISA-P",
      "descricao": "Camiseta basica algodao P",
      "codigo_ncm": "61091000",
      "icms_origem": 0,
      "quantidade_comercial": 1,
      "valor_unitario_comercial": 100.00
    }
  ],
  "formas_pagamento": [ { "forma_pagamento": "17" } ]
}
```

Resposta `202`:

```json
{
  "cnpj_emitente": "11222333000181",
  "ref": "PED-1001",
  "ambiente": "homologacao",
  "status": "processando_autorizacao",
  "numero": "1",
  "serie": "1",
  "chave_nfe": null,
  "protocolo_sefaz": null,
  "status_sefaz": null,
  "mensagem_sefaz": null,
  "mensagem": null,
  "valor_total": 100,
  "autorizada_em": null,
  "caminho_xml_nota_fiscal": null,
  "caminho_danfe": null,
  "eventos": []
}
```

Note que **o ICMS, o DIFAL, o PIS/COFINS e o CFOP não foram informados**: a plataforma calcula pelo regime da empresa e pela operação. Aqui, por ser uma venda interestadual a consumidor final não contribuinte, ela calcula também o DIFAL.

Segundos depois, `GET /nfe/PED-1001` devolve a nota autorizada:

```json
{
  "cnpj_emitente": "11222333000181",
  "ref": "PED-1001",
  "ambiente": "homologacao",
  "status": "autorizado",
  "numero": "1",
  "serie": "1",
  "chave_nfe": "35261011222333000181550010000000011219954665",
  "protocolo_sefaz": "135260000000001",
  "status_sefaz": "100",
  "mensagem_sefaz": "Autorizado o uso da NF-e",
  "mensagem": null,
  "valor_total": 100,
  "autorizada_em": "2026-10-04T15:50:10+00:00",
  "caminho_xml_nota_fiscal": "https://srv1839254.hstgr.cloud/api/v2/nfe/PED-1001/xml?cnpj_emitente=11222333000181",
  "caminho_danfe": "https://srv1839254.hstgr.cloud/api/v2/nfe/PED-1001/danfe?cnpj_emitente=11222333000181",
  "eventos": []
}
```

## A resposta da nota

| Campo | Significado |
|---|---|
| `cnpj_emitente`, `ref`, `ambiente` | quem emitiu, o seu identificador e `homologacao` ou `producao` |
| `status` | estado atual: veja [os estados](01-conceitos.md#estados-da-nota) |
| `numero`, `serie` | número fiscal da NF-e e série (texto). Reservados na aceitação; **não mudam** se a nota for rejeitada e reenviada |
| `chave_nfe` | chave de acesso de 44 dígitos (existe depois que a nota é montada e assinada) |
| `protocolo_sefaz` | protocolo de autorização |
| `status_sefaz`, `mensagem_sefaz` | código (`cStat`) e texto da última resposta da SEFAZ. **Sempre o original** |
| `mensagem` | por que a nota está parada ou foi recusada, numa frase (rejeição da SEFAZ ou pendência de validação) |
| `valor_total` | valor da nota em reais |
| `autorizada_em` | quando a SEFAZ autorizou |
| `caminho_xml_nota_fiscal` | link do XML autorizado. Continua disponível **depois do cancelamento** (guarda obrigatória de 5 anos) |
| `caminho_danfe` | link do DANFE (PDF), enquanto a nota vale |
| `eventos` | cancelamentos e cartas de correção, com o estado de cada um (veja [Consultar e eventos](06-eventos.md)) |

Os links exigem a chave de API, como qualquer chamada. **Guarde o XML autorizado:** é o documento fiscal, e você precisa mantê-lo por 5 anos.

## Referência dos campos

Campo desconhecido é recusado (`422`, com o caminho do campo). Valores em reais (número). Documentos aceitam máscara.

### Nota

| Campo | Regra |
|---|---|
| `cnpj_emitente` | a empresa que emite. Dispensável se a conta tem uma só |
| `serie` | série em que a nota sai, `0` a `889`. Padrão `1`. O próximo número de cada série se configura em [Numeração](03-empresas.md#numeracao-da-nf-e-series-e-proximo-numero) |
| `natureza_operacao` | texto, até 60. Padrão `VENDA DE MERCADORIA` |
| `presenca_comprador` | `0` não se aplica, `1` presencial, `2` internet, `3` teleatendimento, `4` entrega a domicílio, `5` presencial fora do estabelecimento, `9` outros. Padrão `2` |
| `modalidade_frete` | `0` por conta do remetente, `1` do destinatário, `2` de terceiros, `3` transporte próprio do remetente, `4` do destinatário, `9` sem frete. Padrão `9` |
| `consumidor_final` | `0` ou `1`. Padrão: `1` se o destinatário **não é contribuinte** de ICMS e `0` se é |
| `valor_frete`, `valor_seguro`, `valor_desconto`, `valor_outras_despesas` | valores **da nota**, que a API rateia entre os itens ([como](#frete-desconto-e-rateio)) |
| `valor_total` | opcional: o total que **você** calculou, com IPI (o `vNF`). A nota só sai se o total calculado pela API fechar com ele |
| `valor_produtos` | opcional: soma dos itens, só para conferência |
| `informacoes_adicionais_contribuinte` | texto livre (até 2000) que vai nas informações complementares da nota |
| `cnpj_intermediador`, `identificador_intermediador` | venda por marketplace ([abaixo](#venda-por-marketplace-com-cartao)) |
| `tipo_documento` | só `1` (saída) |
| `finalidade_emissao` | só `1` (normal). Devolução, complementar e ajuste ainda não |
| `local_destino` | `1` interna, `2` interestadual. Precisa **bater com as UFs** (emitente e destinatário) |

### Destinatário

Informe **um** documento: `cpf_destinatario` ou `cnpj_destinatario` (com dígito verificador válido; o CNPJ pode ser alfanumérico).

| Campo | Regra |
|---|---|
| `nome_destinatario` | obrigatório |
| `cpf_destinatario` / `cnpj_destinatario` | exatamente um dos dois |
| `inscricao_estadual_destinatario` | dígitos, ou o texto `ISENTO` |
| `indicador_inscricao_estadual_destinatario` | `1` contribuinte, `2` isento, `9` não contribuinte. Padrão: CNPJ com IE → `1`; `ISENTO` → `2`; o resto → `9`. Com `1` a IE é obrigatória |
| `logradouro_destinatario`, `bairro_destinatario`, `municipio_destinatario` | obrigatórios |
| `numero_destinatario` | padrão `S/N` |
| `complemento_destinatario`, `telefone_destinatario`, `email_destinatario` | opcionais |
| `uf_destinatario` | obrigatório; UF válida |
| `cep_destinatario` | obrigatório, 8 dígitos |
| `codigo_municipio_destinatario` | código IBGE do município (7 dígitos). **Informe sempre que puder**: se faltar, a API tenta descobrir pelo CEP (consulta externa) e, se não conseguir, devolve `422` pedindo o código |
| `pais_destinatario` | só Brasil (`Brasil` ou `1058`). Destinatário no exterior não é suportado |

> Em **homologação** a SEFAZ exige o texto `NF-E EMITIDA EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL` no nome do destinatário e na descrição do item 1: a plataforma coloca sozinha. Você manda os dados reais normalmente.

### Itens (`items`)

De 1 a 990 itens, **na ordem**.

| Campo | Regra |
|---|---|
| `codigo_produto` | obrigatório (até 60). É o SKU e a chave do [catálogo](04-produtos.md) |
| `descricao` | descrição do item (até 120 saem na nota). Se faltar, vem do catálogo |
| `codigo_ncm` | NCM, 8 dígitos. Se faltar, vem do catálogo |
| `icms_origem` | origem da mercadoria, 0 a 8. Se faltar, vem do catálogo |
| `quantidade_comercial` | obrigatória, maior que zero, até 4 casas |
| `valor_unitario_comercial` | obrigatório, até 10 casas (`0.3333` vale) |
| `valor_bruto` | opcional: quantidade × preço. Se vier, precisa bater com a conta (tolerância de R$ 0,01, como a SEFAZ) |
| `unidade_comercial` | padrão `UN` (ou a do catálogo) |
| `codigo_barras_comercial` | GTIN válido, ou `SEM GTIN`/omitido |
| `codigo_cest` | 7 dígitos |
| `producao_propria` | `true` para o que você fabrica (CFOP x101). Padrão: revenda (x102) |
| `valor_desconto`, `valor_frete`, `valor_seguro`, `valor_outras_despesas` | valores **do item**, somados ao rateio da nota |
| `numero_item` | opcional; se vier, tem de ser a posição do item (1, 2, 3...) |
| `unidade_tributavel`, `quantidade_tributavel`, `valor_unitario_tributavel` | só aceitos se **iguais** aos comerciais (unidade tributável diferente ainda não é suportada) |
| `inclui_no_total` | só `1` |
| `cfop`, `icms_situacao_tributaria`, `icms_aliquota`, `icms_reducao_base_calculo`, `fcp_aliquota`, `icms_difal`, `pis_situacao_tributaria`, `pis_aliquota_porcentual`, `cofins_situacao_tributaria`, `cofins_aliquota_porcentual`, `ipi_situacao_tributaria`, `ipi_aliquota` | **parâmetros fiscais** do [modo híbrido](07-modo-hibrido.md). Opcionais: o que você não informa a plataforma calcula |

Valores de imposto (`icms_valor`, `icms_base_calculo`, `pis_valor`, `ipi_valor`...) são **recusados**, com uma mensagem que explica: a API calcula os valores a partir dos parâmetros.

### Pagamentos (`formas_pagamento`)

Pelo menos uma forma de pagamento.

| Campo | Regra |
|---|---|
| `forma_pagamento` | obrigatório. Código da NF-e: `01` dinheiro, `02` cheque, `03` cartão de crédito, `04` cartão de débito, `05` crédito loja, `10` a `13` vales (alimentação, refeição, presente, combustível), `14` duplicata mercantil, `15` boleto, `16` depósito, `17` PIX, `90` sem pagamento, `99` outros. `18` a `22` são os demais meios da tabela de formas de pagamento do leiaute da NF-e (`tPag`) |
| `valor_pagamento` | opcional com **uma** forma (paga a nota inteira); **obrigatório** com duas ou mais, e a soma tem de fechar com o valor da nota |
| `descricao_pagamento` | obrigatória na forma `99` |
| `indicador_pagamento` | `0` à vista, `1` a prazo. Padrão `1` para `03`, `05` e `14`; `0` para as demais |
| `tipo_integracao_pagamento` | cartão (`03` e `04`): `1` integrado ao sistema de pagamento, `2` não integrado. **Obrigatório** no cartão. PIX dinâmico (`17`) também leva o grupo de pagamento eletrônico na nota: se você não informar, sai como `2` (não integrado) — a SEFAZ rejeita (391) o PIX sem esse grupo |
| `cnpj_credenciadora`, `bandeira_operadora`, `numero_autorizacao` | cartão **integrado** (`tipo_integracao_pagamento` = 1): obrigatórios. Bandeira: `01` Visa, `02` Mastercard, `03` Amex, `04` Sorocred, `05` Diners, `06` Elo, `07` Hipercard, `08` Aura, `09` Cabal, `99` outras |

## Frete, desconto e rateio

Você pode informar frete, seguro, desconto e outras despesas **na nota** e/ou **em cada item**. Os valores da nota são **rateados entre os itens, proporcionalmente ao valor de cada um**, e a soma dos itens bate exatamente com o que você informou (a diferença de arredondamento vai para os maiores restos). Os valores de cada item entram **além** do rateio.

Exemplo: dois itens de R$ 100,00 e R$ 30,00, frete de R$ 10,00 na nota e desconto de R$ 5,00. O frete se divide em R$ 7,69 e R$ 2,31; o desconto em R$ 3,85 e R$ 1,15. A nota fecha em `100 + 30 + 10 − 5 = 135,00`.

O desconto de um item não pode passar do valor dele.

## Total e pagamentos precisam fechar

Antes de emitir, a API calcula o total da nota e confere:

- se você informou `valor_total`, ele tem de bater com o total calculado **(incluindo IPI)**. Se não bater: `422 validacao_fiscal` com a mensagem `Total calculado (11500) difere do total informado (9990).` (valores em centavos). É a rede de segurança para um erro de cálculo do seu lado não virar uma nota errada;
- com duas ou mais formas de pagamento, a soma de `valor_pagamento` tem de fechar com o valor da nota.

## Campos aceitos e ignorados

Para facilitar a migração de quem vem de outro emissor, estes campos são **aceitos e ignorados de propósito**:

- `data_emissao`, `data_entrada_saida`: a nota sai com o horário real da emissão, o da plataforma;
- `cpf_emitente`, `nome_emitente`, `nome_fantasia_emitente`, `logradouro_emitente`, `numero_emitente`, `bairro_emitente`, `municipio_emitente`, `uf_emitente`, `cep_emitente`, `inscricao_estadual_emitente`, `regime_tributario_emitente`: os dados do emitente vêm do **cadastro da empresa**.

Qualquer outro campo desconhecido é recusado.

## Reenvio de uma `ref`

O que acontece ao enviar de novo uma `ref` que já existe depende do estado da nota:

| Estado da nota | Mesmo conteúdo | Conteúdo diferente |
|---|---|---|
| `processando_autorizacao` | `202`, devolve o estado (repetir por falha de rede é seguro) | `409 ref_ja_utilizada` |
| `autorizado`, `cancelado`, `denegado`, `inutilizado` | `200`, devolve o estado | `409 ref_ja_utilizada`: use uma `ref` nova |
| `erro_autorizacao` ou `erro_validacao` | reenfileira (é o "tentar de novo") | aceita o conteúdo corrigido e reenfileira, com o **mesmo número** |

Em resumo: **nota rejeitada se corrige reenviando na mesma `ref`**; nota cancelada, denegada ou inutilizada nunca reaproveita a `ref` para outro conteúdo (assim, uma repetição por falha de rede jamais emite uma segunda nota). Para uma venda nova, use sempre uma `ref` nova.

O corpo do `409`:

```json
{ "codigo": "ref_ja_utilizada", "mensagem": "A ref PED-1001 já pertence a uma nota (autorizado) com outro conteúdo. Use uma ref nova para uma nota nova.", "status_atual": "autorizado" }
```

## Exemplos prontos

### Venda B2B com frete, desconto e pagamento dividido

Empresa do Simples Nacional vendendo para uma empresa contribuinte de outro estado. Dois itens, frete de R$ 10,00 e desconto de R$ 5,00 na nota, total conferido, pago em PIX e boleto a prazo:

<!-- exemplo:emitir -->
```json
{
  "natureza_operacao": "VENDA DE MERCADORIA ADQUIRIDA",
  "modalidade_frete": 1,
  "valor_frete": 10.00,
  "valor_desconto": 5.00,
  "valor_total": 135.00,
  "informacoes_adicionais_contribuinte": "Pedido de compra 4471.",
  "nome_destinatario": "COMERCIAL RIO LTDA",
  "cnpj_destinatario": "11.444.777/0001-61",
  "inscricao_estadual_destinatario": "12345678",
  "logradouro_destinatario": "Av Atlantica",
  "numero_destinatario": "500",
  "bairro_destinatario": "Copacabana",
  "municipio_destinatario": "Rio de Janeiro",
  "codigo_municipio_destinatario": "3304557",
  "uf_destinatario": "RJ",
  "cep_destinatario": "22010-000",
  "items": [
    { "codigo_produto": "CAMISA-P", "descricao": "Camiseta basica algodao P", "codigo_ncm": "61091000", "icms_origem": 0,
      "quantidade_comercial": 2, "valor_unitario_comercial": 50.00, "codigo_barras_comercial": "7891000100103" },
    { "codigo_produto": "BONE-U", "descricao": "Bone aba curva", "codigo_ncm": "65050090", "icms_origem": 0,
      "quantidade_comercial": 1, "valor_unitario_comercial": 30.00 }
  ],
  "formas_pagamento": [
    { "forma_pagamento": "17", "valor_pagamento": 85.00 },
    { "forma_pagamento": "15", "valor_pagamento": 50.00, "indicador_pagamento": 1 }
  ]
}
```

### Venda por marketplace com cartão

Quando a venda foi intermediada por um marketplace, informe o CNPJ do intermediador (e o seu identificador de vendedor lá). O pagamento por cartão **integrado** exige credenciadora, bandeira e número de autorização:

<!-- exemplo:emitir -->
```json
{
  "cnpj_intermediador": "03.007.331/0001-41",
  "identificador_intermediador": "123456789",
  "nome_destinatario": "Maria da Silva",
  "cpf_destinatario": "529.982.247-25",
  "logradouro_destinatario": "Av Atlantica",
  "numero_destinatario": "500",
  "bairro_destinatario": "Copacabana",
  "municipio_destinatario": "Rio de Janeiro",
  "codigo_municipio_destinatario": "3304557",
  "uf_destinatario": "RJ",
  "cep_destinatario": "22010-000",
  "items": [
    { "codigo_produto": "CAMISA-P", "descricao": "Camiseta basica algodao P", "codigo_ncm": "61091000", "icms_origem": 0,
      "quantidade_comercial": 1, "valor_unitario_comercial": 100.00 }
  ],
  "formas_pagamento": [
    {
      "forma_pagamento": "03",
      "tipo_integracao_pagamento": 1,
      "cnpj_credenciadora": "03.007.331/0001-41",
      "bandeira_operadora": "01",
      "numero_autorizacao": "A12345"
    }
  ]
}
```

Com `cnpj_intermediador` a nota sai com o indicador de intermediador ligado. O `identificador_intermediador` sozinho (sem o CNPJ) é recusado.

### Empresa do regime normal, venda interna

Empresa do Lucro Presumido vendendo dentro do próprio estado. O ICMS, o PIS, a COFINS e o IBS/CBS são calculados pelo regime, sem você informar nada:

<!-- exemplo:emitir regime=presumido -->
```json
{
  "nome_destinatario": "COMERCIAL PAULISTA LTDA",
  "cnpj_destinatario": "11.444.777/0001-61",
  "inscricao_estadual_destinatario": "110042490114",
  "logradouro_destinatario": "Rua Augusta",
  "numero_destinatario": "1000",
  "bairro_destinatario": "Consolacao",
  "municipio_destinatario": "Sao Paulo",
  "codigo_municipio_destinatario": "3550308",
  "uf_destinatario": "SP",
  "cep_destinatario": "01304-001",
  "items": [
    { "codigo_produto": "CAMISA-P", "descricao": "Camiseta basica algodao P", "codigo_ncm": "61091000", "icms_origem": 0,
      "quantidade_comercial": 2, "valor_unitario_comercial": 50.00 }
  ],
  "formas_pagamento": [ { "forma_pagamento": "15", "indicador_pagamento": 1 } ]
}
```

### Item só com o SKU, usando o catálogo

Se o produto está no [catálogo](04-produtos.md), o item pode ir só com o essencial: o NCM, a origem, a descrição e a unidade vêm do cadastro.

<!-- exemplo:emitir -->
```json
{
  "nome_destinatario": "Maria da Silva",
  "cpf_destinatario": "529.982.247-25",
  "logradouro_destinatario": "Av Atlantica",
  "numero_destinatario": "500",
  "bairro_destinatario": "Copacabana",
  "municipio_destinatario": "Rio de Janeiro",
  "codigo_municipio_destinatario": "3304557",
  "uf_destinatario": "RJ",
  "cep_destinatario": "22010-000",
  "items": [ { "codigo_produto": "CAMISA-P", "quantidade_comercial": 3, "valor_unitario_comercial": 100.00 } ],
  "formas_pagamento": [ { "forma_pagamento": "17" } ]
}
```

## Quando a emissão é recusada

Exemplos reais do que a API devolve na hora, antes de gastar um número:

**Campos inválidos** (`422 requisicao_invalida`, com **todos** os problemas de uma vez):

```json
{
  "codigo": "requisicao_invalida",
  "mensagem": "O campo nome destinatario é obrigatório.",
  "erros": {
    "nome_destinatario": ["O campo nome destinatario é obrigatório."],
    "uf_destinatario": ["O valor informado em uf destinatario é inválido."],
    "items.0.codigo_ncm": ["O campo items.0.codigo_ncm deve ter 8 dígitos."],
    "items.0.icms_valor": ["A API calcula icms_valor a partir da situação tributária e da alíquota informadas; não envie este valor."]
  }
}
```

**Recusa fiscal** (`422 validacao_fiscal`): o cálculo ou a empresa não permitem emitir. Exemplos: total que não fecha, cenário tributário que o motor não suporta, certificado vencido, empresa inativa, produção bloqueada.

```json
{ "codigo": "validacao_fiscal", "mensagem": "Total calculado (11500) difere do total informado (9990)." }
```

**`ref` já usada com outro conteúdo** (`409`): veja [Reenvio de uma `ref`](#reenvio-de-uma-ref).

Se a nota passou pela validação e a SEFAZ a **rejeitar**, o `status` fica `erro_autorizacao` e a nota traz o motivo original:

```json
{
  "ref": "PED-1005", "status": "erro_autorizacao", "numero": "3", "chave_nfe": "35261011222333000181550010000000031948157050",
  "status_sefaz": "225", "mensagem_sefaz": "Rejeicao: Falha no Schema XML da NFe", "mensagem": "Rejeição 225: Rejeicao: Falha no Schema XML da NFe"
}
```

Corrija o problema e reenvie na **mesma `ref`**: o número fiscal é o mesmo (rejeição não consome número). Veja os motivos mais comuns em [Erros](09-erros.md#rejeicoes-comuns-da-sefaz).