Referência de campos: NFCe

Esta página lista exatamente o que a engineAPI aceita hoje no payload de emissão de NFCe, nem mais, nem menos. O modelo 65 (NFCe) não tem IPI nem ICMS-ST no leiaute oficial: os campos items[].ipi e items[].icms.baseCalculoST/aliquotaST/valorST são aceitos no contrato só para poderem ser recusados com 422 IPI_NAO_SUPORTADO/422 ICMS_ST_NAO_SUPORTADO em vez de descartados em silêncio; ver Erros e Rejeições. Esta página descreve o contrato de entrada, não a cobertura fiscal completa do leiaute oficial.

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

---

Tributação assistida (Cérebro Fiscal)

Campos que ativam ou compõem a emissão assistida. Com resolverTributacao: true, a engineAPI resolve tributos automaticamente para itens sem tributação manual. Ver guia do Cérebro Fiscal. Os mesmos campos abaixo também aparecem em contexto, no grupo estrutural onde o schema os declara.

• 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

items[].ibsCbs (Cérebro Fiscal)

• 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 (Cérebro Fiscal)

• 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, e 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 (Cérebro Fiscal)

• 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, e 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 (Cérebro Fiscal)

• 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, e 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)

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)$)
• serie: número decimal, opcional. Série da NFCe. Ausente = série padrão do emissor
• numero: número decimal, opcional. Número da NFCe (passthrough). Ausente = alocado automaticamente pela engineAPI
• destCPF: string, opcional. CPF do consumidor final, só dígitos. Ausente = venda sem identificação
• destNome: string, opcional. Nome do consumidor final. Ausente = "CONSUMIDOR FINAL"
• items: array de objeto (ver seção abaixo), obrigatório. Itens da nota (mínimo 1) (detalhado em items[], 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 cupom
• 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

items[]

• codigo: string, obrigatório. Código interno do produto (seu SKU) (mínimo 1 caractere(s))
• descricao: string, obrigatório. Descrição do produto (mínimo 1 caractere(s))
• ean: string, opcional. Código de barras EAN/GTIN do produto. Ausente = "SEM GTIN"
• 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 (predominantemente estadual, ex.: "5102") (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 (detalhado em items[].pis, abaixo)
• cofins: objeto (ver seção abaixo), opcional. Tributação de COFINS do item (detalhado em items[].cofins, abaixo)
• ipi: objeto (ver seção abaixo), opcional. IPI: NÃO SUPORTADO na NFC-e (o modelo 65 não tem o grupo no leiaute). Aceito no contrato só para recusar com 422 IPI_NAO_SUPORTADO em vez de descartar em silêncio (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). Ausente = 0
• 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
• cst: string, opcional. Código de Situação Tributária do ICMS (Lucro Real/Presumido), ex.: "00" tributada integralmente
• 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$. NÃO SUPORTADO: informar ST devolve 422 ICMS_ST_NAO_SUPORTADO
• aliquotaST: número decimal, opcional. Alíquota do ICMS-ST em %. NÃO SUPORTADO: ver baseCalculoST (422 ICMS_ST_NAO_SUPORTADO)
• valorST: número decimal, opcional. Valor do ICMS-ST em R$. NÃO SUPORTADO: ver baseCalculoST (422 ICMS_ST_NAO_SUPORTADO)

items[].pis

• cst: string, opcional. Código de Situação Tributária 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" zerado
• 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)

items[].cofins

• cst: string, opcional. Código de Situação Tributária da COFINS. Mesmas faixas do PIS. Ausente = "99" zerado
• 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)

items[].ipi

• cst: string, opcional. CST do IPI. NÃO SUPORTADO na NFC-e (422 IPI_NAO_SUPORTADO)
• baseCalculo: número decimal, opcional. NÃO SUPORTADO na NFC-e
• aliquota: número decimal, opcional. NÃO SUPORTADO na NFC-e
• valor: número decimal, opcional. NÃO SUPORTADO na NFC-e
• cEnq: string, opcional. NÃO SUPORTADO na NFC-e

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, e 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, e 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, e 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)

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$