engineAPIengineAPI
Começar
// referência

Referência de campos: NFSe

Todo campo do payload de emissão de NFSe (POST /v1/nfse): tipo, obrigatoriedade e condição de uso.

Referência de campos: NFSe

Esta página lista exatamente o que a engineAPI aceita hoje no payload de emissão de NFSe, nem mais, nem menos. A NFSe tem provider por município (ABRASF) ou Padrão Nacional (SEFIN/ADN, bloco dpsNacional): o formato aceito é o mesmo nos dois, mas cada provider usa um subconjunto. Com resolverTributacao: true (Cérebro Fiscal), campos da DPS ausentes são preenchidos pelo cadastro do emissor; campo obrigatório sem fonte devolve 422 com camposNaoResolvidos; ver Cérebro Fiscal. O bloco ibsCbs (Reforma Tributária) é passthrough puro: nada nele é resolvido pelo Cérebro Fiscal. Esta página descreve o contrato de entrada, não a cobertura fiscal completa do leiaute oficial.

73 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.

Campos de nível superior

  • issuerId: string, obrigatório. (mínimo 1 caractere(s))
  • rps: objeto (ver seção abaixo), opcional. (detalhado em rps, abaixo)
  • serie: string, opcional.
  • dpsNacional: objeto (ver seção abaixo), opcional. (detalhado em dpsNacional, abaixo)
  • ibsCbs: objeto (ver seção abaixo), opcional. (detalhado em ibsCbs, abaixo)
  • naturezaOperacao: número inteiro, opcional.
  • regimeTributacao: número inteiro, opcional.
  • optanteSimples: booleano, opcional.
  • exigibilidadeISS: número inteiro, opcional.
  • competencia: string, opcional. (padrão: ^\d{4}-\d{2}-\d{2}$)
  • tomador: objeto (ver seção abaixo), obrigatório. (detalhado em tomador, abaixo)
  • servico: objeto (ver seção abaixo), obrigatório. (detalhado em servico, abaixo)
  • retencoes: objeto (ver seção abaixo), opcional. (detalhado em retencoes, abaixo)
  • informacoesComplementares: string, opcional.
  • resolverTributacao: booleano, opcional.

rps

  • numero: número inteiro, obrigatório.
  • serie: string, opcional.
  • tipo: número inteiro, opcional.

dpsNacional

  • opSimpNac: string, obrigatório.
  • regApTribSN: string, opcional.
  • regEspTrib: string, opcional.
  • cTribNac: string, obrigatório. (mínimo 1 caractere(s))
  • cTribMun: string, opcional.
  • tribISSQN: string, obrigatório.
  • tpRetISSQN: string, opcional.
  • cstPisCofins: string, opcional.
  • pTotTribSN: número decimal, opcional.

ibsCbs

  • finNFSe: string, opcional. Finalidade da emissão. O leiaute v1.01 prevê um único valor: "0" (NFS-e regular). Ausente = "0" (valores aceitos: 0)
  • indFinal: string, opcional. Operação de uso ou consumo pessoal (LC 214/2025, art. 57): "0" não · "1" sim (valores aceitos: 0, 1)
  • cIndOp: string, obrigatório. Código indicador da operação de fornecimento (6 dígitos), conforme a tabela oficial "Código Indicador de Operação" (ANEXO_C/AnexoVII do portal nacional da NFS-e). Obrigatório quando o bloco ibsCbs é enviado (padrão: ^\d{6}$)
  • tpOper: string, opcional. Tipo de operação com entes governamentais ou serviços sobre bens imóveis: 1 fornecimento com pagamento posterior · 2 recebimento com fornecimento já realizado · 3 fornecimento com pagamento já realizado · 4 recebimento com fornecimento posterior · 5 fornecimento e recebimento concomitantes (valores aceitos: 1, 2, 3, 4, 5)
  • tpEnteGov: string, opcional. Tipo de ente governamental: 1 União · 2 Estado · 3 DF · 4 Município (valores aceitos: 1, 2, 3, 4)
  • indDest: string, opcional. Destinatário do serviço: "0" o destinatário é o próprio tomador (padrão) · "1" o destinatário é outra pessoa, o que exige o grupo dest do leiaute, ainda NÃO suportado por este motor, que recusa com 422 IBSCBS_DPS_DESTINATARIO_NAO_SUPORTADO em vez de emitir sem o grupo (valores aceitos: 0, 1)
  • cst: string, obrigatório. Código de Situação Tributária do IBS/CBS (3 dígitos). Obrigatório quando o bloco ibsCbs é enviado (o motor não infere CST na NFS-e) (padrão: ^\d{3}$)
  • cClassTrib: string, obrigatório. Código de Classificação Tributária do IBS/CBS (6 dígitos). Obrigatório quando o bloco ibsCbs é enviado (padrão: ^\d{6}$)
  • cCredPres: string, opcional. Código e classificação do crédito presumido de IBS/CBS (2 dígitos) (padrão: ^\d{2}$)
  • gTribRegular: objeto (ver seção abaixo), opcional. Tributação regular: a situação que valeria se o benefício não existisse (detalhado em ibsCbs.gTribRegular, abaixo)
  • gDif: objeto (ver seção abaixo), opcional. Diferimento do IBS/CBS. Os três percentuais (pDifUF, pDifMun, pDifCBS) são exigidos juntos pelo leiaute (detalhado em ibsCbs.gDif, abaixo)

ibsCbs.gTribRegular

  • cstReg: string, obrigatório. CST do IBS/CBS que valeria na tributação regular (sem o benefício aplicado) (padrão: ^\d{3}$)
  • cClassTribReg: string, obrigatório. Código de classificação tributária do IBS/CBS na tributação regular (padrão: ^\d{6}$)

ibsCbs.gDif

  • pDifUF: número decimal, obrigatório. Percentual de diferimento do IBS estadual, em % (ex.: 30 para 30%). Máximo 2 casas decimais (mínimo 0; máximo 100)
  • pDifMun: número decimal, obrigatório. Percentual de diferimento do IBS municipal, em %. Máximo 2 casas decimais (mínimo 0; máximo 100)
  • pDifCBS: número decimal, obrigatório. Percentual de diferimento da CBS, em %. Máximo 2 casas decimais (mínimo 0; máximo 100)

tomador

  • cnpjCpf: string, obrigatório. (mínimo 1 caractere(s))
  • razaoSocial: string, obrigatório. (mínimo 1 caractere(s))
  • email: string, opcional.
  • telefone: string, opcional.
  • inscricaoMunicipal: string, opcional.
  • endereco: objeto (ver seção abaixo), obrigatório. (detalhado em tomador.endereco, abaixo)

tomador.endereco

  • logradouro: string, obrigatório. (mínimo 1 caractere(s))
  • numero: string, obrigatório. (mínimo 1 caractere(s))
  • complemento: string, opcional.
  • bairro: string, obrigatório. (mínimo 1 caractere(s))
  • codigoMunicipio: string, obrigatório. (mínimo 1 caractere(s))
  • uf: string, obrigatório. (mínimo 1 caractere(s))
  • cep: string, obrigatório. (mínimo 1 caractere(s))

servico

  • codigoMunicipio: string, obrigatório. (mínimo 1 caractere(s))
  • itemListaServico: string, opcional. (mínimo 1 caractere(s))
  • codigoCnae: string, opcional.
  • codigoTributacaoMunicipio: string, opcional.
  • codigoNBS: string, opcional.
  • discriminacao: string, obrigatório. (mínimo 1 caractere(s))
  • valorServicos: número decimal, obrigatório.
  • aliquotaIss: número decimal, opcional.
  • valorDeducoes: número decimal, opcional.
  • descontoIncondicionado: número decimal, opcional.
  • descontoCondicionado: número decimal, opcional.

retencoes

  • irrf: número decimal, opcional.
  • csll: número decimal, opcional.
  • cofins: número decimal, opcional.
  • pis: número decimal, opcional.
  • inss: número decimal, opcional.
  • outrasRetencoes: número decimal, opcional.