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. Formatos decimais fixos respeitam casas e teto do dicionário: 13v2 aceita até 13 dígitos inteiros e 2 casas. Excesso devolve 400 com campo e valor, sem arredondamento silencioso. valorUnitario conserva as até 10 casas e respeita os 11 dígitos inteiros do 11v0-10. Ver Erros e respostas. Tamanho, formato e enumeração do leiaute recusam 400 na entrada, nomeando campo e faixa, antes de alocar número fiscal.
Leiaute: versão 4.00 · Contrato revisado em: 2026-09-19
128 campos documentados abaixo (contagem recursiva, incluindo objetos aninhados e itens de array).
Navegação por grupo do leiaute
- Identificação
- Emitente
- Destinatário
- Itens
- Totais (sem campo no contrato hoje, ver nota)
- Transporte (sem campo no contrato hoje, ver nota)
- Cobrança
- Pagamento
- Informações adicionais
- Tributação assistida (Cérebro Fiscal)
Identificação
number
Tamanho: 1-3 (0 a 999) · Tag do leiaute:
serie (grupo ide: Identificação da NF-e) · Obrigatoriedade do leiaute: obrigatório no leiaute · Preenche: preenchido automaticamente pela engineAPISérie da NFC-e. Ausente = série padrão do emissorCondição do leiaute: Ausente = série padrão do emissor. Emitente comum usa 0-889; o leiaute reserva 890-899 para avulsa do Fisco e 900-999 para contingência.Fonte do leiaute: leiauteNFe_v4.00.xsd (PL_009p_NT2024_003_v103): TNFe/infNFe/ide/serie (TSerie)number
Tamanho: 1-9 · Tag do leiaute:
nNF (grupo ide: Identificação da NF-e) · Obrigatoriedade do leiaute: obrigatório no leiaute · Preenche: preenchido automaticamente pela engineAPINúmero da NFC-e (passthrough). Ausente = alocado automaticamente pela engineAPICondição do leiaute: Ausente = número alocado pela engineAPI no controle de numeração do emissor. Informar o número é passthrough e a responsabilidade pela sequência passa a ser do integrador.Fonte do leiaute: leiauteNFe_v4.00.xsd (PL_009p_NT2024_003_v103): TNFe/infNFe/ide/nNF (TNF)number
Tamanho: 1 · Tag do leiaute:
indPres (grupo ide: Identificação da NF-e) · Obrigatoriedade do leiaute: obrigatório no leiaute · Preenche: você, na requisiçãoIndicador de presença do comprador no estabelecimento no momento da operação. 1=operação presencial, 2=não presencial pela internet, 3=não presencial por teleatendimento, 4=NFC-e com entrega em domicílio, 5=operação presencial fora do estabelecimento, 9=não presencial, outros. 0 (“não se aplica”) NÃO é aceito: esse valor descreve nota complementar/de ajuste (finNFe 2/3), documento que esta NFC-e nunca emite (finNFe=1 fixo). Ausente = 1 (presencial), o padrão histórico da NFC-e no balcão. Declare o valor real da operação: venda por delivery/telefone/internet com indPres=1 é uma declaração falsa ao fiscoCondição do leiaute: Ausente = 1 (presencial). O valor 0 (não se aplica, usado em nota complementar ou de ajuste) não é aceito: a NFC-e sempre emite como nota normal.Fonte do leiaute: leiauteNFe_v4.00.xsd (PL_009p_NT2024_003_v103): TNFe/infNFe/ide/indPresboolean
Tamanho: 1 · Tag do leiaute:
tpEmis (grupo ide: Identificação da NF-e) · Obrigatoriedade do leiaute: obrigatório no leiaute · Preenche: você, na requisiçãoEmitir em contingência offline (tpEmis 9): a NFC-e é assinada e devolvida com XML e DANFE para o PDV imprimir SEM passar pela SEFAZ, e a engineAPI retransmite automaticamente quando o autorizador voltar (prazo legal de 24 h). true = forçar contingência; false = proibir contingência automática nesta nota (a emissão falha se a SEFAZ estiver fora); ausente = a engineAPI decide pelo monitor de disponibilidade da UFCondição do leiaute: Governa o tpEmis do documento. true força 9 (contingência offline), que é a única contingência prevista para o modelo 65, já que a NFC-e não tem SEFAZ Virtual de Contingência. false proíbe a contingência automática nesta nota. Ausente deixa a engineAPI decidir pelo monitoramento de disponibilidade da UF e pela falha de transmissão. Em contingência a nota volta assinada e imprimível, sem protocolo, e é transmitida em até 24 horas.Fonte do leiaute: leiauteNFe_v4.00.xsd (PL_009p_NT2024_003_v103): TNFe/infNFe/ide/tpEmisstring
Tamanho: 15-256 · Tag do leiaute:
xJust (grupo ide: Identificação da NF-e) · Obrigatoriedade do leiaute: condicional no leiaute · Preenche: você, na requisiçãoJustificativa da entrada em contingência (xJust do leiaute, 15 a 256 caracteres). Vai impressa no documento fiscal. Ausente = “Indisponibilidade do servico de autorizacao da SEFAZ da UF do emitente”Condição do leiaute: Obrigatório no documento sempre que tpEmis é 9. Ausente no payload, a engineAPI escreve a justificativa padrão de indisponibilidade da SEFAZ. Texto fora da faixa de 15 a 256 caracteres recusa com 422 JUSTIFICATIVA_CONTINGENCIA_INVALIDA antes de consumir número. O texto nunca é completado nem truncado, porque é a declaração que o contribuinte faz ao fisco.Fonte do leiaute: leiauteNFe_v4.00.xsd (PL_009p_NT2024_003_v103): TNFe/infNFe/ide/xJustEmitente
Os dados completos do emitente (razão social, CNPJ, endereço, Inscrição Estadual) vêm do cadastro da empresa selecionada emissuerId, não são enviados campo a campo no payload de emissão.
string
Tag do leiaute: sem tag própria no XML (grupo
engineAPI: plataforma) · Obrigatoriedade do leiaute: não é campo do leiaute (informativo/de compatibilidade) · Preenche: você, na requisiçãoUUID 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)$)Condição do leiaute: Opcional com um emissor cadastrado; obrigatório com dois ou mais (a API não escolhe o CNPJ emitente por conta própria).Nota do leiaute: Campo de plataforma: identifica qual emissor cadastrado assina o documento. Não existe no leiaute fiscal, onde o emitente é identificado pelo CNPJ no grupo emit.Fonte do leiaute: contrato da engineAPI (POST /v1/companies devolve o UUID)Destinatário
NFC-e identifica o consumidor só por CPF e nome (os dois opcionais); não há endereço completo como na NF-e.string
Tamanho: 11 (CPF) ou 14 (CNPJ) · Tag do leiaute:
CPF (grupo dest: Identificação do Destinatário) · Obrigatoriedade do leiaute: condicional no leiaute · Preenche: você, na requisiçãoCPF do consumidor final, só dígitos. Ausente = venda sem identificaçãoCondição do leiaute: Na NFC-e o grupo do destinatário é opcional: sem documento informado, a venda sai sem identificação do consumidor e o grupo não é emitido. Emitido o grupo, o documento é obrigatório dentro dele, e o motor fiscal escolhe entre as tags CPF e CNPJ pelo tamanho informado.Fonte do leiaute: leiauteNFe_v4.00.xsd (PL_009p_NT2024_003_v103): TNFe/infNFe/dest/CPF (TCpf) e /CNPJ (TCnpj)string
Tamanho: 2-60 · Tag do leiaute:
xNome (grupo dest: Identificação do Destinatário) · Obrigatoriedade do leiaute: condicional no leiaute · Preenche: você, na requisiçãoNome do consumidor final. Ausente = “CONSUMIDOR FINAL”Condição do leiaute: Obrigatório sempre que o grupo do destinatário é emitido, que na NFC-e depende de destCPF: sem documento do consumidor o grupo inteiro não sai. Com documento e sem nome, a engineAPI escreve “CONSUMIDOR FINAL”.Fonte do leiaute: leiauteNFe_v4.00.xsd (PL_009p_NT2024_003_v103): TNFe/infNFe/dest/xNomeItens
object[]
required
Tag do leiaute:
det (grupo I: Produtos e Serviços) · Obrigatoriedade do leiaute: obrigatório no leiauteItens da nota (mínimo 1)Nota do leiaute: Grupo, não campo: det é o contêiner do item e não carrega valor próprio (só o atributo nItem, gerado pela ordem do array).Fonte do leiaute: leiauteNFe_v4.00.xsd (PL_009p_NT2024_003_v103): TNFe/infNFe/det (maxOccurs=“990”)Totais
O grupo de totais do leiaute não é enviado no payload: a engineAPI soma os itens e calcula o total automaticamente.Transporte
NFC-e (modelo 65) é venda presencial ao consumidor final: o leiaute não tem grupo de transporte.Cobrança
O grupo é aceito pelo contrato, mas a validação de negócio da NFC-e recusa hoje toda emissão com cobrança a prazo (é venda com pagamento imediato ao consumidor final); ver Estado dos campos do leiaute, abaixo.object
Tag do leiaute:
cobr (grupo Y: Cobrança) · Obrigatoriedade do leiaute: opcional no leiauteNÃO SUPORTADO na NFC-e: devolve 422 COBRANCA_NAO_SUPORTADA_NFCE. NFC-e documenta venda com pagamento imediato ao consumidor final; use NF-e (modelo 55) para venda a prazoCondição do leiaute: Grupo informativo/financeiro na NF-e; não altera o total nem substitui pagamentos. Na NFC-e não chega a importar: qualquer cobranca com fatura e/ou duplicatas é recusada com 422 COBRANCA_NAO_SUPORTADA_NFCE antes da validação Y01-20/Y10-10 da NF-e, que só vale no modelo 55. Não é a regra de “duplicata sem fatura”, é o grupo inteiro.Nota do leiaute: Grupo, não campo: cobr é o contêiner da fatura e das duplicatas.Fonte do leiaute: leiauteNFe_v4.00.xsd (PL_009p_NT2024_003_v103): TNFe/infNFe/cobrPagamento
object[]
required
Tag do leiaute:
pag (grupo pag: Informações de Pagamento) · Obrigatoriedade do leiaute: obrigatório no leiauteFormas de pagamento (mínimo 1, máximo 100). Atenção: o campo é “pagamentos” (array), não “pagamento”Condição do leiaute: Uma entrada do array vira um subgrupo detPag do leiaute (máximo 100). A soma dos valores tem que fechar com o total do documento.Nota do leiaute: Grupo, não campo: pag é o contêiner das formas de pagamento e do troco.Fonte do leiaute: leiauteNFe_v4.00.xsd (PL_009p_NT2024_003_v103): TNFe/infNFe/pag e /pag/detPag (maxOccurs=“100”)number
Tamanho: 13v2 · Tag do leiaute:
vTroco (grupo pag: Informações de Pagamento) · Obrigatoriedade do leiaute: opcional no leiaute · Preenche: você, na requisiçãoValor do troco em R$, para venda com pagamento em dinheiro (máximo 2 casas decimais)Condição do leiaute: Só é escrito quando maior que zero. No documento a tag é irmã de detPag (pertence ao grupo de pagamento inteiro, não a uma forma). O pré-voo confere soma dos pagamentos menos troco contra o total.Fonte do leiaute: leiauteNFe_v4.00.xsd (PL_009p_NT2024_003_v103): TNFe/infNFe/pag/vTroco (TDec_1302)Informações adicionais
string
Tamanho: 1-5000 · Tag do leiaute:
infCpl (grupo infAdic: Informações Adicionais) · Obrigatoriedade do leiaute: opcional no leiaute · Preenche: você, na requisiçãoInformações complementares de interesse do contribuinte, impressas no cupomCondição do leiaute: Texto livre de interesse do contribuinte, IMPRESSO no cupom. Ausente, a engineAPI escreve o texto padrão “NFC-e emitida via Engine”, que sai impresso no cupom; informe o campo para substituí-lo. Observação ESTRUTURADA (blocos nomeados obsCont) ainda não é suportada.Fonte do leiaute: leiauteNFe_v4.00.xsd (PL_009p_NT2024_003_v103): TNFe/infNFe/infAdic/infCplTributação assistida (Cérebro Fiscal)
Fora da taxonomia clássica do leiaute:resolverTributacao ativa a emissão assistida; ver guia do Cérebro Fiscal. O grupo IBS/CBS por item (items[].ibsCbs) já aparece em contexto, dentro de Itens, acima.
boolean
Tag do leiaute: sem tag própria no XML (grupo
engineAPI: plataforma) · Obrigatoriedade do leiaute: não é campo do leiaute (informativo/de compatibilidade) · Preenche: você, na requisiçãoAtiva 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.fiscalBrainEnabledNota do leiaute: Chave de comportamento, não campo fiscal: liga a emissão assistida, em que a engineAPI resolve CSOSN e o grupo IBS/CBS dos itens sem tributação manual. Não vira tag nenhuma no documento.Fonte do leiaute: contrato da engineAPI (Cérebro Fiscal)Índice reverso: tag do leiaute → nosso campo
Procure pelo nome que o leiaute usa (ex.:natOp, vFrete) e encontre o campo correspondente no contrato da engineAPI.
Estado dos campos do leiaute
Todo campo listado acima é suportado: está no contrato e a engineAPI o usa. Esta seção cobre o resto do leiaute: o que a API aceita com outro nome, o que ela recusa hoje e as ressalvas de campos que estão no contrato mas o leiaute trata de um jeito específico.Preenchidos automaticamente ou derivados
Aceitos, mas com outro nome
Aceitos no contrato, com ressalva do leiaute
issuerId: Campo de plataforma: identifica qual emissor cadastrado assina o documento. Não existe no leiaute fiscal, onde o emitente é identificado pelo CNPJ no grupo emit.items[].icms: Grupo, não campo: o leiaute escolhe o subgrupo (ICMS00, ICMS61, ICMSSN102…) pelo CST/CSOSN informado, e é o subgrupo que carrega as tags.items[].pis: Grupo, não campo: o leiaute escolhe o subgrupo pelo CST informado, e é o subgrupo que carrega as tags.items[].cofins: Grupo, não campo: o leiaute escolhe o subgrupo pelo CST informado, e é o subgrupo que carrega as tags.items[].ipi: Grupo, não campo: o leiaute escolhe entre IPITrib e IPINT pelo CST, e é o subgrupo que carrega as tags de valor.items[].ibsCbs.ibsUf: Grupo, não campo: o subgrupo é o contêiner da alíquota e do valor do componente.items[].ibsCbs.ibsMun: Grupo, não campo: o subgrupo é o contêiner da alíquota e do valor do componente.items[].ibsCbs.cbs: Grupo, não campo: o subgrupo é o contêiner da alíquota e do valor do componente.items[].ibsCbs: Grupo, não campo: IBSCBS é o contêiner do CST, do cClassTrib e dos subgrupos de alíquota.items[].combustivel: Grupo, não campo: comb é o contêiner do detalhamento específico de combustíveis.items: Grupo, não campo:deté o contêiner do item e não carrega valor próprio (só o atributo nItem, gerado pela ordem do array).cobranca.fatura: Grupo, não campo: fat é o contêiner dos dados da fatura.cobranca.duplicatas: Grupo, não campo: dup é o contêiner de uma parcela.cobranca: Grupo, não campo: cobr é o contêiner da fatura e das duplicatas.pagamentos[].cartao: Grupo, não campo: card é o contêiner dos dados do meio de pagamento eletrônico.pagamentos: Grupo, não campo: pag é o contêiner das formas de pagamento e do troco.resolverTributacao: Chave de comportamento, não campo fiscal: liga a emissão assistida, em que a engineAPI resolve CSOSN e o grupo IBS/CBS dos itens sem tributação manual. Não vira tag nenhuma no documento.