engineAPIengineAPI
Começar
// referência

Referência de campos — NFe

Todo campo do payload de emissão de NFe (POST /v1/nfe), gerado automaticamente do schema Zod real — nunca escrito à mão.

Referência de campos — NFe

Gerado automaticamente a partir do schema Zod real de POST /v1/nfe (CreateNfeSchema, em apps/api/src/nfe/dto/create-nfe.dto.ts) — não edite este arquivo à mão, ele é sobrescrito a cada build (predev/prebuild) por apps/docs/scripts/generate-campos-nfe.mjs. Se um campo mudar no DTO, esta página muda sozinha na próxima geração.

Esta página lista exatamente o que a engineAPI aceita hoje no payload de emissão de NFe — nem mais, nem menos. Alguns campos aceitos aqui ainda não têm efeito completo no documento fiscal final (ex.: tributação por CST de Regime Normal, hoje recusada com 422 CST_NAO_SUPORTADO_NFE — ver Erros e Rejeições); esta página descreve o contrato de entrada, não a cobertura fiscal completa do leiaute oficial.

84 campos documentados abaixo (contagem recursiva, incluindo objetos aninhados e itens de array).

Campos de nível superior

  • issuerId — string (UUID), opcional — UUID do emissor (retornado por POST /v1/companies). Opcional com 1 emissor cadastrado; obrigatório com 2+ (padrão: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$)
  • naturezaOperacao — string, opcional — Natureza da operação, texto livre (ex.: "VENDA DE MERCADORIA")
  • serie — número inteiro, opcional — Série da NFe. Ausente = série padrão do emissor
  • numero — número inteiro, opcional — Número da NFe (passthrough). Ausente = alocado automaticamente pela engineAPI
  • tpNF — número inteiro, opcional — Tipo de operação: 0=entrada, 1=saída. Padrão: saída
  • idDest — número inteiro, opcional — Identificador de local de destino: 1=interna (mesma UF), 2=interestadual, 3=exterior
  • indFinal — número inteiro, opcional — Indica operação com consumidor final: 0=não, 1=sim
  • indPres — número inteiro, opcional — Indicador de presença do comprador: 0=não se aplica, 1=presencial, 2=internet, 3=teleatendimento, etc.
  • finNFe — número inteiro, opcional — Finalidade da emissão: 1=normal, 2=complementar, 3=ajuste, 4=devolução
  • destinatario — objeto (ver seção abaixo), obrigatório (detalhado em destinatario, abaixo)
  • items — array de objeto (ver seção abaixo), obrigatório — Itens da nota (mínimo 1). Atenção: o campo é "items", não "itens" (detalhado em items[], abaixo)
  • transporte — objeto (ver seção abaixo), opcional — Dados de transporte. Se enviado, modFrete é obrigatório (detalhado em transporte, abaixo)
  • pagamentos — array de objeto (ver seção abaixo), obrigatório — Formas de pagamento (mínimo 1). Atenção: o campo é "pagamentos" (array), não "pagamento" (detalhado em pagamentos[], abaixo)
  • troco — número decimal, opcional — Valor do troco em R$, para venda com pagamento em dinheiro
  • informacoesComplementares — string, opcional — Informações complementares de interesse do contribuinte, impressas no DANFE
  • informacoesFisco — string, opcional — Informações adicionais de interesse do fisco
  • resolverTributacao — booleano, opcional — Ativa a emissão assistida (Cérebro Fiscal): resolve CSOSN e o grupo IBS/CBS de itens sem tributação manual. Requer plano com fiscalBrain + Issuer.fiscalBrainEnabled

destinatario

  • cnpjCpf — string, obrigatório — CNPJ (14 dígitos) ou CPF (11 dígitos) do destinatário, só números (mínimo 11 caractere(s); máximo 14 caractere(s))
  • nome — string, obrigatório — Razão social ou nome completo do destinatário (mínimo 1 caractere(s))
  • ie — string, opcional — Inscrição Estadual do destinatário. Obrigatória (validada pela SEFAZ contra o CNPJ) quando indicadorIE = 1
  • indicadorIE — número inteiro, opcional — Indicador de IE do destinatário: 1 = contribuinte (exige ie); 2 = isento; 9 = não contribuinte
  • email — string, opcional — E-mail do destinatário (informativo, não usado para envio)
  • endereco — objeto (ver seção abaixo), obrigatório (detalhado em destinatario.endereco, abaixo)

destinatario.endereco

  • logradouro — string, obrigatório — Nome da rua/avenida do destinatário (mínimo 1 caractere(s))
  • numero — string, obrigatório — Número do endereço (aceita "S/N") (mínimo 1 caractere(s))
  • complemento — string, opcional — Complemento do endereço (apto, sala, bloco)
  • bairro — string, obrigatório — Bairro do destinatário (mínimo 1 caractere(s))
  • codigoMunicipio — string, obrigatório — Código IBGE do município (7 dígitos, ex.: "5208707" para Goiânia) (mínimo 1 caractere(s))
  • municipio — string, obrigatório — Nome do município (mínimo 1 caractere(s))
  • uf — string, obrigatório — Sigla da UF, 2 letras maiúsculas (ex.: "GO", "SP") (mínimo 2 caractere(s); máximo 2 caractere(s))
  • cep — string, obrigatório — CEP do destinatário, só dígitos ou com hífen (mínimo 1 caractere(s))

items[]

  • codigo — string, obrigatório — Código interno do produto (seu SKU) (mínimo 1 caractere(s))
  • ean — string, opcional — Código de barras EAN/GTIN do produto. Ausente = "SEM GTIN"
  • descricao — string, obrigatório — Descrição do produto (mínimo 1 caractere(s))
  • ncm — string, obrigatório — Nomenclatura Comum do Mercosul, 8 dígitos exatos (mínimo 8 caractere(s); máximo 8 caractere(s))
  • cest — string, opcional — Código Especificador da Substituição Tributária, 7 dígitos sem pontuação (ex.: "0100100"). Transmitido no produto do documento; formato inválido devolve 422 CEST_INVALIDO
  • cfop — string, obrigatório — Código Fiscal de Operações e Prestações (ex.: "5102" venda estadual, "6102" interestadual) (mínimo 1 caractere(s))
  • unidade — string, obrigatório — Unidade comercial: "UN", "KG", "MT", "CX", etc. (mínimo 1 caractere(s))
  • quantidade — número decimal, obrigatório — Quantidade vendida (mínimo 0.0001) (mínimo 0.0001)
  • valorUnitario — número decimal, obrigatório — Valor unitário do produto em R$ (mínimo 0.01) (mínimo 0.01)
  • valorTotal — número decimal, opcional — Redundante — sempre recalculado como quantidade × valorUnitario. Se enviado e divergente, 400
  • desconto — número decimal, opcional — Desconto INCONDICIONAL do item em R$ (vDesc do leiaute) — reduz a base do ICMS e do IBS/CBS. NÃO informe desconto condicional (sob condição/evento posterior): por lei ele integra a base e não tem campo no item (mínimo 0)
  • icms — objeto (ver seção abaixo), opcional — Tributação de ICMS do item (obrigatório de fato só sem resolverTributacao) (detalhado em items[].icms, abaixo)
  • pis — objeto (ver seção abaixo), opcional — Tributação de PIS do item (passthrough: vai como informado para o documento) (detalhado em items[].pis, abaixo)
  • cofins — objeto (ver seção abaixo), opcional — Tributação de COFINS do item (passthrough: vai como informado para o documento) (detalhado em items[].cofins, abaixo)
  • ipi — objeto (ver seção abaixo), opcional — Tributação de IPI do item (indústria/importação). Só na NF-e — a NFC-e não tem IPI no leiaute. O valor informado compõe o total da nota (detalhado em items[].ipi, abaixo)
  • ibsCbs — objeto (ver seção abaixo), opcional — Grupo IBS/CBS da Reforma Tributária (opcional, NT 2025.002). Aceita o grupo completo (passthrough) ou só { cClassTrib } — nesse caso o Cérebro Fiscal resolve os percentuais oficiais da classe (requer resolverTributacao: true) (detalhado em items[].ibsCbs, abaixo)

items[].icms

  • origem — número inteiro, opcional — Origem da mercadoria: 0=nacional, 1=estrangeira (importação direta), 2=estrangeira (mercado interno), 3/4/5=nacional com % de conteúdo importado. Ausente = 0
  • cst — string, opcional — Código de Situação Tributária do ICMS (Lucro Real/Presumido) — ex.: "00" tributada integralmente, "40" isenta (padrão: ^\d{1,3}$)
  • csosn — string, opcional — Código de Situação da Operação do Simples Nacional — ex.: "102" tributada pelo Simples sem crédito, "400" não tributada (padrão: ^\d{1,3}$)
  • aliquota — número decimal, opcional — Alíquota do ICMS em % (só com cst, regime CST)
  • baseCalculo — número decimal, opcional — Base de cálculo do ICMS em R$ (só com cst, regime CST)
  • valor — número decimal, opcional — Valor do ICMS em R$ (só com cst, regime CST)
  • baseCalculoST — número decimal, opcional — Base de cálculo do ICMS-ST em R$. AINDA NÃO SUPORTADO: informar ST devolve 422 ICMS_ST_NAO_SUPORTADO (o motor não emite documento sem a ST que você informou)
  • aliquotaST — número decimal, opcional — Alíquota do ICMS-ST em %. AINDA NÃO SUPORTADO — ver baseCalculoST (422 ICMS_ST_NAO_SUPORTADO)
  • valorST — número decimal, opcional — Valor do ICMS-ST em R$. AINDA NÃO SUPORTADO — ver baseCalculoST (422 ICMS_ST_NAO_SUPORTADO)

items[].pis

  • cst — string, opcional — Código de Situação Tributária do PIS. Tributado por alíquota: "01"/"02" (exige baseCalculo, aliquota e valor). Não tributado: "04"-"09" (só o CST vai no documento). Outras operações: "49"-"56", "60"-"67", "70"-"75", "98" e "99". Ausente = "99" com valores zerados (padrão: ^\d{1,3}$)
  • baseCalculo — número decimal, opcional — Base de cálculo do PIS em R$ (transmitida como vBC)
  • aliquota — número decimal, opcional — Alíquota do PIS em % (transmitida como pPIS)
  • valor — número decimal, opcional — Valor do PIS em R$ (transmitido como vPIS e somado no total da nota)

items[].cofins

  • cst — string, opcional — Código de Situação Tributária da COFINS. Mesmas faixas do PIS: "01"/"02" por alíquota (exige baseCalculo, aliquota e valor), "04"-"09" não tributado, outras operações: "49"-"56", "60"-"67", "70"-"75", "98" e "99". Ausente = "99" com valores zerados (padrão: ^\d{1,3}$)
  • baseCalculo — número decimal, opcional — Base de cálculo da COFINS em R$ (transmitida como vBC)
  • aliquota — número decimal, opcional — Alíquota da COFINS em % (transmitida como pCOFINS)
  • valor — número decimal, opcional — Valor da COFINS em R$ (transmitido como vCOFINS e somado no total da nota)

items[].ipi

  • cst — string, opcional — Código de Situação Tributária do IPI (obrigatório quando o grupo ipi é enviado). Tributados: "00", "49", "50", "99" (exigem baseCalculo, aliquota e valor). Não tributados: "01".."05" e "51".."55" (só o CST vai no documento) (padrão: ^\d{1,3}$)
  • baseCalculo — número decimal, opcional — Base de cálculo do IPI em R$ (transmitida como vBC)
  • aliquota — número decimal, opcional — Alíquota do IPI em % (transmitida como pIPI)
  • valor — número decimal, opcional — Valor do IPI em R$ (transmitido como vIPI). Atenção: o IPI COMPÕE o total da nota — vNF = produtos + IPI, e os pagamentos precisam fechar com esse total
  • cEnq — string, opcional — Código de Enquadramento Legal do IPI, 1 a 3 dígitos (tabela da Receita). Ausente = "999" (demais casos)

items[].ibsCbs

  • cst — string, opcional — Código de Situação Tributária do IBS/CBS (Reforma Tributária). Ausente = "000" (padrão: ^\d{1,3}$)
  • cClassTrib — string, opcional — Código de Classificação Tributária do IBS/CBS. Ausente = "000001" (tributação integral) (padrão: ^\d{1,6}$)
  • vBC — número decimal, opcional — Base de cálculo do IBS/CBS em R$. Ausente = vProd − desconto do item (LC 214/2025 art. 12 § 2º III: descontos incondicionais não integram a base) (mínimo 0)
  • ibsUf — objeto (ver seção abaixo), obrigatório — Componente estadual do IBS (Imposto sobre Bens e Serviços) (detalhado em items[].ibsCbs.ibsUf, abaixo)
  • ibsMun — objeto (ver seção abaixo), obrigatório — Componente municipal do IBS (detalhado em items[].ibsCbs.ibsMun, abaixo)
  • vIbs — número decimal, opcional — Valor total do IBS em R$ (UF + Município). Ausente = vIbsUf + vIbsMun (mínimo 0)
  • cbs — objeto (ver seção abaixo), obrigatório — CBS (Contribuição sobre Bens e Serviços, componente federal) (detalhado em items[].ibsCbs.cbs, abaixo)

items[].ibsCbs.ibsUf

  • p — número decimal, obrigatório — Alíquota EFETIVA do componente, em % (ex.: 0.04). É ela que gera o valor do tributo (v = p × vBC). Em item COM redução, vai no documento dentro de gRed/pAliqEfet (mínimo 0)
  • pNominal — número decimal, opcional — Alíquota NOMINAL do componente, em % (ex.: 0.1) — a alíquota cheia, antes da redução do cClassTrib. É a que o documento grava em pIBSUF/pIBSMun/pCBS. Obrigatória junto com pRedAliq; ausente = item sem redução (nominal = efetiva) (mínimo 0)
  • pRedAliq — número decimal, opcional — Percentual de redução de alíquota do cClassTrib, em % (ex.: 60 para o Anexo VII). Presente e maior que 0 faz o documento emitir o grupo gRed{pRedAliq, pAliqEfet}. Obrigatória junto com pNominal (mínimo 0; máximo 100)
  • v — número decimal, opcional — Valor do componente em R$. Ausente = calculado como p × vBC (mínimo 0)

items[].ibsCbs.ibsMun

  • p — número decimal, obrigatório — Alíquota EFETIVA do componente, em % (ex.: 0.04). É ela que gera o valor do tributo (v = p × vBC). Em item COM redução, vai no documento dentro de gRed/pAliqEfet (mínimo 0)
  • pNominal — número decimal, opcional — Alíquota NOMINAL do componente, em % (ex.: 0.1) — a alíquota cheia, antes da redução do cClassTrib. É a que o documento grava em pIBSUF/pIBSMun/pCBS. Obrigatória junto com pRedAliq; ausente = item sem redução (nominal = efetiva) (mínimo 0)
  • pRedAliq — número decimal, opcional — Percentual de redução de alíquota do cClassTrib, em % (ex.: 60 para o Anexo VII). Presente e maior que 0 faz o documento emitir o grupo gRed{pRedAliq, pAliqEfet}. Obrigatória junto com pNominal (mínimo 0; máximo 100)
  • v — número decimal, opcional — Valor do componente em R$. Ausente = calculado como p × vBC (mínimo 0)

items[].ibsCbs.cbs

  • p — número decimal, obrigatório — Alíquota EFETIVA do componente, em % (ex.: 0.04). É ela que gera o valor do tributo (v = p × vBC). Em item COM redução, vai no documento dentro de gRed/pAliqEfet (mínimo 0)
  • pNominal — número decimal, opcional — Alíquota NOMINAL do componente, em % (ex.: 0.1) — a alíquota cheia, antes da redução do cClassTrib. É a que o documento grava em pIBSUF/pIBSMun/pCBS. Obrigatória junto com pRedAliq; ausente = item sem redução (nominal = efetiva) (mínimo 0)
  • pRedAliq — número decimal, opcional — Percentual de redução de alíquota do cClassTrib, em % (ex.: 60 para o Anexo VII). Presente e maior que 0 faz o documento emitir o grupo gRed{pRedAliq, pAliqEfet}. Obrigatória junto com pNominal (mínimo 0; máximo 100)
  • v — número decimal, opcional — Valor do componente em R$. Ausente = calculado como p × vBC (mínimo 0)

transporte

  • modFrete — número inteiro, obrigatório — Modalidade do frete: 0=por conta do emitente, 1=por conta do destinatário, 2=por conta de terceiros, 9=sem transporte
  • transportadora — objeto (ver seção abaixo), opcional (detalhado em transporte.transportadora, abaixo)
  • volumes — array de objeto (ver seção abaixo), opcional (detalhado em transporte.volumes[], abaixo)

transporte.transportadora

  • cnpjCpf — string, opcional — CNPJ ou CPF da transportadora
  • nome — string, opcional — Razão social ou nome da transportadora
  • ie — string, opcional — Inscrição Estadual da transportadora
  • endereco — string, opcional — Endereço da transportadora
  • municipio — string, opcional — Município da transportadora
  • uf — string, opcional — UF da transportadora

transporte.volumes[]

  • quantidade — número inteiro, opcional — Quantidade de volumes transportados
  • especie — string, opcional — Espécie dos volumes (ex.: "Caixa", "Pallet")
  • pesoBruto — número decimal, opcional — Peso bruto total em kg
  • pesoLiquido — número decimal, opcional — Peso líquido total em kg

pagamentos[]

  • forma — string, obrigatório — Código da forma de pagamento SEFAZ (ex.: "01" dinheiro, "03" cartão de crédito, "15" boleto) (mínimo 1 caractere(s))
  • valor — número decimal, obrigatório — Valor pago nesta forma, em R$