NF-e (Produto)

Criar NF-e

Cria a NF-e (modelo 55) com apuração tributária automática e validação de schema. Suporta emissão direta em 1 passo ("transmitir": true) ou modo rascunho em 2 passos para conferência prévia. Consulte também o guia de Emissão de NF-e.

Fluxo de Emissão Direta:
1.
Envio da Requisição (`POST /v1/nfe`): Envie o JSON com "transmitir": true. Caso os grupos de impostos não sejam enviados, o motor de Inteligência Fiscal da NFER apura automaticamente CFOP, ICMS, PIS, COFINS, ST e DIFAL com base na UF e NCM do destinatário (se você já calcular no ERP e enviar os impostos explicitamente, eles serão respeitados integralmente).
2.
Retorno Imediato (`201 Created`): A nota é criada com número fiscal reservado e enfileirada na fila assíncrona de transmissão para a SEFAZ com status "processando".
3.
Webhook de Autorização (`nfe.autorizada`): Em poucos segundos seu webhook recebe o evento nfe.autorizada contendo a chave de acesso de 44 dígitos, protocolo da SEFAZ e links diretos do DANFE PDF e XML protocolado pronto para impressão/envio ao cliente.
POST
https://api.nfer.me
/v1/nfe

Authorizations

X-API-Key
string
header
required

Chave de API emitida no painel NFER enviada no header da requisição.

Content-Type
string
header
required

application/json

Body

application/json
transmitir
boolean
opcional
default:false
Define o modo de emissão da nota fiscal:
•
true: Emissão Direta / Síncrona — o NFER valida, grava e enfileira imediatamente a transmissão para a SEFAZ (retorna HTTP 201 Created com status "processando"), dispensando chamar o endpoint POST /v1/nfe/:id/send.
•
false ou omitido (padrão): Modo Rascunho — grava a nota e realiza o cálculo tributário automático em ~50ms com status "rascunho", sem queimar numeração na SEFAZ e permitindo conferência e transmissão posterior via POST /v1/nfe/:id/send.

Alias aceito em inglês para integrações legadas ou internacionais: transmit (ou emitir).

Exemplo:true
environment
"homologacao" | "producao"
opcional
default:da empresa

Sobrepõe o ambiente salvo da conta para esta emissão ("homologacao" ou "producao"). Se omitido, utiliza a configuração da empresa.

Exemplo:homologacao
naturezaOperacao
string
required

Natureza da operação fiscal (ex.: "VENDA DE MERCADORIA", "DEVOLUCAO DE COMPRA"). Limite: 60 caracteres.

Exemplo:VENDA DE MERCADORIA
tipoOperacao
string
required

"0" para Entrada ou "1" para Saída.

Exemplo:1
finalidade
integer
required
Finalidade da emissão:
•
1: NF-e normal
•
2: NF-e complementar
•
3: NF-e de ajuste
•
4: Devolução de mercadoria
Exemplo:1
serie
integer
opcional
default:1

Número da série fiscal (1 a 999). Padrão: 1.

consumidorFinal
boolean
required
default:true

Indica se a operação destina-se a consumidor final (uso, consumo ou ativo imobilizado). Essencial para a correta apuração pelo motor tributário e aplicação de regras fiscais: define alíquotas interestaduais, apuração do DIFAL / Partilha da EC 87/2015 na SEFAZ e afasta a retenção de ICMS-ST (Art. 264 do RICMS). Na SEFAZ corresponde ao indicador indFinal (1 ou 0).

Exemplo:true
destinatarioId
string<uuid>
opcional

UUID do cliente já cadastrado em /v1/customers. Utilize este campo apenas quando você já tiver o ID cadastrado no seu banco. Para e-commerce, marketplaces e novas vendas, envie o objeto "destinatario" inline. Aliases aceitos: customerId, clienteId.

destinatario
object
opcional

Dados cadastrais e endereço completo do destinatário (aliases aceitos: customer, cliente). Recomendado para e-commerce e integrações ágeis (o NFER faz upsert automático por CPF/CNPJ).

chaveReferenciada
string (44 dígitos)
opcional

Chave de acesso completa da NF-e referenciada. Para finalidade 1 (NF-e Normal / Retorno de Conserto / Remessas / Exportação indireta), o NFER gera a tag <ide><NFref><refNFe> no cabeçalho do XML da SEFAZ. Aliases aceitos: refChaveAcesso, nfeReferenciada.chaveAcesso.

Exemplo:35260100000000000191550010000001231000001234
pedidoCompra
string (até 60 caracteres)
opcional

Número do Pedido de Compra do cliente ou identificador de marketplace (gera a tag <compra><xPed> no cabeçalho do XML da SEFAZ). Aliases aceitos: xPed, pedido_compra.

Exemplo:LIN5458865195
itens
object[]
required

Lista com ao menos 1 item com os produtos ou mercadorias da nota fiscal. Cada item aceita cálculo automático por Perfil Fiscal ou detalhamento tributário manual.

Exemplo:[{"descricao":"Monitor Gamer 27 Polegadas 165Hz","ncm":"85285200","cfop":"5102","quantidade":1,"valorUnitario":1200.0}]
pagamentos
object[]
required

Formas de pagamento da venda (obrigatório para finalidade 1). A soma dos pagamentos deve ser exatamente igual ao valor total da nota fiscal.

Exemplo:[{"forma":"01","valor":1200.0}]
transporte
object
opcional

Modalidade de frete e dados da transportadora contratada.

cobranca
object
opcional

Estrutura oficial de faturamento e parcelas da nota fiscal (tag <cobr> da SEFAZ). Muito utilizado em vendas faturadas B2B (15/30/45 dias, boleto a prazo). Gera o quadro "Fatura / Duplicatas" no DANFE impresso. Aliases aceitos: cobr, faturamento.

Exemplo:{"fatura":{"numero":"FAT-01","valorOriginal":1200.0,"valorLiquido":1200.0},"duplicatas":[{"numero":"001","vencimento":"2026-11-15","valor":600.0},{"numero":"002","vencimento":"2026-12-15","valor":600.0}]}
localEntrega
object
opcional

Endereço físico de entrega da mercadoria quando diferente do domicílio fiscal do destinatário (tag <entrega> da SEFAZ). Essencial para compras faturadas na matriz e entregues em obras, filiais ou galpões logísticos. Aliases: entrega, enderecoEntrega.

localRetirada
object
opcional

Endereço físico de retirada da mercadoria quando diferente do endereço cadastral do emitente (tag <retirada> da SEFAZ). Muito utilizado em vendas onde o produto sai diretamente de armazém geral ou operador terceiro. Aliases: retirada, enderecoRetirada.

indPres
integer
opcional
default:9
Indicador de presença do comprador no estabelecimento:
•
0: Não se aplica
•
1: Operação presencial
•
2: Operação não presencial (Internet)
•
9: Outros
informacoesAdicionais
string
opcional

Informações complementares de interesse do contribuinte impressas no quadro "Dados Adicionais" do DANFE (tag <infCpl> da SEFAZ, até 5000 caracteres).

Muito utilizado por ERPs e e-commerces para incluir dados operacionais e comerciais:

•
Número do pedido de compra / Ordem de Compra (OC) do cliente (ex.: "Pedido #49812 - OC 8812").
•
Detalhes do cliente e entrega (ex.: "Entregar na portaria central aos cuidados do setor de TI - Bloco B. Horário comercial.").
•
Informações de devolução, troca ou conserto (ex.: "Referente a conserto/garantia sob NF 12345 de 15/09/2026. RMA #9021").
•
Dados de vendedor, filial de despacho ou instruções de pagamento.
Injeção Automática pelo NFER:

O NFER concatena automaticamente os blocos regulatórios (Carga Tributária IBPT da Lei 12.741, enquadramento do Simples Nacional/MEI/sublimite e DIFAL no Regime Normal). Além disso, em operações com chaveReferenciada (como Retorno de Conserto CFOP 5916, remessas e devoluções), o NFER injeta automaticamente no final a linha "Doc. Fiscal Referenciado: <chave>", garantindo exibição no DANFE sem duplicar caso você já a tenha citado no texto.

Exemplo:Pedido #49812 | Entregar aos cuidados do setor de TI | Ref. Conserto sob NF 12345
intermediador
object
opcional

Dados do intermediador da transação ou marketplace (infIntermed / NT 2020.006). Obrigatório em operações pela internet (indPres: 2) realizadas em plataformas de terceiros (ex: Mercado Livre, Shopee, Amazon, iFood).

Exemplo:{"cnpj":"03007331000141","idCadIntTran":"MLB123456789"}
autXml
string[]
opcional

Lista com até 10 CPFs ou CNPJs (apenas números) de pessoas autorizadas perante a SEFAZ a consultar e baixar o XML completo da nota no Web Service de Distribuição de DF-e (tag <autXML>).

Muito utilizado para autorizar previamente a contabilidade, a transportadora contratada ou o operador logístico parceiro.

Exemplo:["03007331000141","12345678000199","12345678909"]
informacoesAdicionaisFisco
string
opcional

Informações reservadas de interesse do fisco (até 2000 caracteres).

regime_irpj_csll
"LUCRO_REAL" | "LUCRO_PRESUMIDO" | "LUCRO_ARBITRADO" | "NAO_SEI"
opcional

Sobrepõe o regime de apuração do IRPJ/CSLL configurado na empresa emitente (aplicável a empresas do Regime Normal - CRT 3). Se omitido, herda do cadastro da empresa.

Exemplo:LUCRO_REAL
regime_pis_cofins
"NON_CUMULATIVE" | "CUMULATIVE" | "MIXED" | "NAO_SEI"
opcional

Sobrepõe o regime de apuração de PIS/COFINS da empresa emitente para esta nota. "NON_CUMULATIVE" aplica as alíquotas não-cumulativas de 1,65% (PIS) e 7,60% (COFINS) (CST 01). "CUMULATIVE" aplica 0,65% (PIS) e 3,00% (COFINS). Se omitido, herda do cadastro da empresa.

Exemplo:NON_CUMULATIVE
rbt12
number
opcional

Receita Bruta Acumulada nos últimos 12 meses (R$) da empresa emitente (aplicável a emitentes do Simples Nacional - CRT 1). Utilizado para o cálculo de DAS preciso e determinação da alíquota de aproveitamento de crédito de ICMS pelo destinatário (tag <pCredSN> / CST 101 e 201).

Exemplo:360000.00

Response

application/json

NF-e criada com sucesso. Suporta Emissão Direta ("transmitir": true -> status "processando" com número reservado e transmissão SEFAZ enfileirada) ou Modo Rascunho ("transmitir": false -> status "rascunho" com apuração fiscal em ~50ms sem queimar numeração). Em ambos os casos, retorna o objeto consolidador "totais" e a lista "itens" com os impostos e perfil_fiscal apurados.

id
string<uuid>
opcional

Identificador único do recurso.

Exemplo:b7c2930a-48a1-4fd8-879e-4a671cfbd992
company_id
string<uuid>
opcional

Identificador único da empresa emissora.

Exemplo:a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11
customer_id
string<uuid>
opcional

Identificador único do cliente destinatário.

Exemplo:c1f7b882-990a-41d9-95e2-6320a0ee1234
numero
integer
opcional

Número da nota fiscal.

Exemplo:1042
serie
integer
opcional

Série da nota fiscal.

Exemplo:1
modelo
string
opcional

Modelo fiscal (55 para NF-e, 65 para NFC-e).

Exemplo:55
natureza_operacao
string
opcional

Natureza da operação fiscal.

Exemplo:VENDA DE MERCADORIA
tipo_operacao
string
opcional

Tipo da operação (0: Entrada, 1: Saída).

Exemplo:1
finalidade
integer
opcional

Finalidade da emissão (1: Normal, 2: Complementar, 3: Ajuste, 4: Devolução).

Exemplo:1
status
string
opcional

Status atual do processamento da nota.

Exemplo:processando
environment
string
opcional

Ambiente de emissão (homologacao ou producao).

Exemplo:homologacao
mod_frete
integer
opcional

Modalidade do frete.

Exemplo:9
valor_total
integer
opcional

Valor total da nota fiscal.

Exemplo:1200
origem
string
opcional

Origem da emissão.

Exemplo:api
created_at
string<date-time>
opcional

Data e hora de criação do registro.

Exemplo:2026-10-15T04:20:00.000Z
updated_at
string<date-time>
opcional

Data e hora da última atualização.

Exemplo:2026-10-15T04:20:00.000Z
totais
object
opcional
itens
object[]
opcional
curl --request POST \
  --url https://api.nfer.me/v1/nfe \
  --header 'X-API-Key: <sua_chave_api>' \
  --header 'Content-Type: application/json' \
  --data '{
  "transmitir": true,
  "naturezaOperacao": "VENDA DE MERCADORIA",
  "tipoOperacao": "1",
  "finalidade": 1,
  "serie": 1,
  "consumidorFinal": true,
  "destinatario": {
    "tipoPessoa": "F",
    "cpfCnpj": "12345678901",
    "nome": "JOAO DA SILVA",
    "email": "joao.silva@email.com",
    "endereco": {
      "logradouro": "Avenida Paulista",
      "numero": "1500",
      "bairro": "Bela Vista",
      "cMun": "3550308",
      "xMun": "São Paulo",
      "UF": "SP",
      "CEP": "01310200"
    }
  },
  "itens": [
    {
      "codigo": "MON-165",
      "descricao": "Monitor Gamer 27 Polegadas 165Hz",
      "ncm": "85285200",
      "unidade": "UN",
      "quantidade": 1,
      "valorUnitario": 1200,
      "tipoItem": "00"
    }
  ],
  "pagamentos": [
    {
      "forma": "01",
      "valor": 1200
    }
  ],
  "informacoesAdicionais": "Pedido #49812 - Emissão com transmissão direta."
}'
{
  "id": "b7c2930a-48a1-4fd8-879e-4a671cfbd992",
  "company_id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "customer_id": "c1f7b882-990a-41d9-95e2-6320a0ee1234",
  "numero": 1042,
  "serie": 1,
  "modelo": "55",
  "natureza_operacao": "VENDA DE MERCADORIA",
  "tipo_operacao": "1",
  "finalidade": 1,
  "status": "processando",
  "environment": "homologacao",
  "mod_frete": 9,
  "valor_total": 1200,
  "origem": "api",
  "created_at": "2026-10-15T04:20:00.000Z",
  "updated_at": "2026-10-15T04:20:00.000Z",
  "totais": {
    "baseCalculoIcms": 1200,
    "valorIcms": 216,
    "valorPis": 19.8,
    "valorCofins": 91.2,
    "valorProdutos": 1200,
    "valorTotal": 1200
  },
  "itens": [
    {
      "id": "f5e4d3c2-1100-44aa-bb22-998877665544",
      "numeroItem": 1,
      "codigo": "MON-165",
      "descricao": "Monitor Gamer 27 Polegadas 165Hz",
      "ncm": "85285200",
      "cfop": "5102",
      "quantidade": 1,
      "valorUnitario": 1200,
      "valorTotal": 1200,
      "perfil_fiscal": {
        "id": "f1a2b3c4-5566-4778-8990-abcdef123456",
        "nome": "Revenda de Informática",
        "segmento": "TI / Eletrônicos",
        "origem": "motor_ia"
      },
      "impostos": {
        "icms": {
          "cst": "00",
          "origem": 0,
          "vBC": 1200,
          "pICMS": 18,
          "vICMS": 216
        },
        "pis": {
          "cst": "01",
          "vBC": 1200,
          "pPIS": 1.65,
          "vPIS": 19.8
        },
        "cofins": {
          "cst": "01",
          "vBC": 1200,
          "pCOFINS": 7.6,
          "vCOFINS": 91.2
        }
      }
    }
  ]
}