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.

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:

{
  "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:

{
  "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:

{
  "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#

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#

Destinatário#

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

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.

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.

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:

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:

{ "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:

{
  "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:

{
  "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:

{
  "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, o item pode ir só com o essencial: o NCM, a origem, a descrição e a unidade vêm do cadastro.

{
  "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):

{
  "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.

{ "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.

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

{
  "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.