Todo cenário desta página é regime tributário do emissor (Simples Nacional/MEI ou
Regime Normal) cruzado com operação (venda interna, interestadual, exportação…).
O mesmo documento pode ser suportado num regime e recusado no outro: a substituição
tributária (
cst "10", "30", "70" para o imposto cobrado nesta operação e
"60" para a mercadoria já retida pelo fornecedor) tem caminho em crt: 3 e
crt: 2, e recusa no Simples pleno e no MEI, onde o documento carrega csosn.Como ler esta página
| Estado | Significado |
|---|---|
| Disponível | Emite hoje. Onde o cálculo é automático (Cérebro Fiscal), é dito explicitamente; onde não é, o campo é passthrough: você informa pronto, a engineAPI valida a forma e transmite, sem calcular o valor |
| Não suportado | Recusa antes de transmitir a SEFAZ/SEFIN, com 422/400 e o motivo por item. Nenhum documento sai incompleto ou com número fiscal queimado por um cenário sem suporte |
422 de tributação assistida segue o mesmo formato: code, motivo por item e,
quando existem, as alternativas curadas (candidatas). Formato completo, RFC 7807:
Erros e Rejeições.
NF-e e NFC-e
NFC-e (modelo 65) é sempre venda presencial a consumidor final, na UF do emitente
(a API declara isso ao motor por você). Por isso as linhas de operação interestadual,
DIFAL, exportação, transporte e NF-e referenciada abaixo marcadas “NF-e
apenas” não são um “não suportado” na NFC-e: são cenário que o modelo não representa,
ou grupo do leiaute que o contrato ainda não escreve para esse documento.
Tamanho, formato e enumeração do leiaute (descrição até 120 caracteres, CFOP de
4 dígitos, CNPJ 14 ou CPF 11,
tpNF 0 ou 1, entre outros) recusam 400 na
entrada, nomeando o campo e a faixa, antes de reservar número fiscal. Um
valor que a SEFAZ rejeitaria por falha de schema já não chega a ser transmitido.Por regime tributário
| Cenário | Simples Nacional / MEI (crt: 1/2/4) | Regime Normal (crt: 3, Lucro Real/Presumido) |
|---|---|---|
| Venda interna (mesma UF) | Disponível, NF-e e NFC-e | Disponível, NF-e e NFC-e, 26 das 27 UFs curadas em fonte primária (Mato Grosso fora, recusa 422). Em Sergipe, o adicional de FCP a consumidor final só resolve para os NCM da lista curada (7 hoje); fora dela recusa com 422 TRIBUTACAO_NAO_RESOLVIDA. Como NFC-e é sempre consumidor final, isso alcança toda NFC-e em SE cujo produto não está na lista |
| Venda interestadual, destinatário contribuinte (B2B) (NF-e apenas) | Disponível | Disponível, alíquota federal de 7%/12%/4% (importados) por origem/destino |
| Venda interestadual, consumidor final não contribuinte (DIFAL) (NF-e apenas) | Não suportado: o Supremo, na ADI 5.464, suspendeu a exigência da partilha para os optantes do Simples Nacional (cobrá-la depende de lei complementar, que não existe). Informar items[].icms.ufDestino com emissor no Simples ou no MEI devolve 422 DIFAL_NAO_APLICAVEL antes de numerar | Provado com emissão real autorizada em homologação (protocolo 152260027584597). Disponível na NF-e (modelo 55) como passthrough, para emissor em Regime Normal (crt: 3) ou no Simples com excesso de sublimite (crt: 2). No documento autorizado o grupo saiu íntegro no item e o vICMSUFDest no total da nota (os somatórios zerados ficam ausentes, como o leiaute manda). Informe items[].icms.ufDestino com vBCUFDest, pICMSUFDest, pICMSInter (4, 7 ou 12), pICMSInterPart (100 desde 2019), vICMSUFDest e vICMSUFRemet (0,00 desde 2019); o adicional de FCP do destino (vBCFCPUFDest/pFCPUFDest/vFCPUFDest) é opcional e vai inteiro. A engineAPI não calcula a partilha: a base de cálculo e a alíquota internas aplicáveis são as da legislação da UF de destino, que ela não tem curada. O que ela faz é recusar antes de numerar o que o documento não representa: grupo fora da operação interestadual a consumidor final não contribuinte (422 DIFAL_NAO_APLICAVEL), grupo pela metade (422 DIFAL_INCOMPLETO) e número incoerente, inclusive quando a soma dos itens estoura o total do documento (422 DIFAL_INVALIDO). Em crt: 3 o ICMS da operação própria vem do Cérebro Fiscal (resolverTributacao: true), e informar o grupo destrava o cálculo que antes recusava com 422 TRIBUTACAO_NAO_RESOLVIDA. Detalhe completo: Guia: DIFAL. Na NFC-e (modelo 65) o grupo não existe: enviá-lo devolve 400 nomeando o campo |
Substituição Tributária, revenda de mercadoria já retida (CST 60) | Não suportado, NF-e e NFC-e. No Simples pleno e no MEI o documento carrega csosn, e o código equivalente é o CSOSN 500, que recusa com 422 CSOSN_NAO_SUPORTADO: é válido no leiaute, mas a Regra de Validação (NT 2024.001) exige CEST/CFOP que o motor ainda não resolve. icms.cst: "60" nesses regimes recusa com 422 CST_REGIME_INCOMPATIVEL | Disponível na NF-e (modelo 55), crt: 3 e crt: 2. Informe icms.cst: "60" com os valores da nota de entrada do seu fornecedor (vBCSTRet, pST, vICMSSTRet; opcionalmente vICMSSubstituto, o FCP-ST retido vBCFCPSTRet/pFCPSTRet/vFCPSTRet e o ICMS efetivo pRedBCEfet/vBCEfet/pICMSEfet/vICMSEfet). Cada bloco vai inteiro: bloco pela metade recusa com 422 ICMS_ST_RETIDO_INCOMPLETO, e campo de ST retido sem o cst: "60" recusa com 422 ICMS_ST_RETIDO_INVALIDO. O vFCPSTRet do total da nota é somado dos itens. Provado com emissão real autorizada em homologação (protocolo 152260027561376). Na NFC-e (modelo 65) esses onze campos não fazem parte do contrato: enviá-los devolve 400 nomeando o campo |
Substituição Tributária, imposto cobrado nesta operação (CST 10/30/70, o lado de ST do 90, CSOSN 201/202/203) | Disponível na NF-e (modelo 55) para o Simples Nacional pleno (crt: 1), pelos CSOSN 201 (com permissão de crédito), 202 (sem permissão de crédito) e 203 (isenção na faixa de receita bruta). Mesmo passthrough do Regime Normal: informe modBCST, vBCST, pICMSST e vICMSST (opcionalmente pMVAST, pRedBCST e o trio vBCFCPST/pFCPST/vFCPST, indivisível), e no 201 também pCredSN e vCredICMSSN, o crédito do artigo 23 da LC 123/2006, que sai da SUA apuração do Simples: a API não o calcula, e sem ele o documento sairia declarando crédito zero ao seu cliente. Grupo pela metade recusa com 422 ICMS_ST_INCOMPLETO; campo que o código não comporta (ICMS próprio, crédito num 202/203, cst junto do csosn) recusa com 422 ICMS_ST_INVALIDO. A ST compõe o total da nota aqui também, e os pagamentos precisam fechar com ele. Estrutura validada contra o leiaute real (grupos ICMSSN201/ICMSSN202), ainda aguardando prova por emissão real. Fora desse recorte segue recusando com 422 CSOSN_NAO_SUPORTADO: na NFC-e (a regra de validação que lista os CSOSN aceitos no modelo 65 não traz os códigos de ST, então emita uma NF-e) e no MEI (crt: 4, cujo domínio de CSOSN é mais estreito e não foi auditado para ST). O CSOSN 500 (mercadoria já retida) continua fora, por Regra de Validação. icms.cst de ST no Simples recusa com 422 CST_REGIME_INCOMPATIVEL: aqui o documento carrega csosn | Disponível na NF-e (modelo 55), crt: 3 e crt: 2, por passthrough: você informa os números, a API valida a forma e transmite. CST 10 provado com emissão real autorizada em homologação (protocolo 152260027584436, com o total do documento conferido tag a tag). CST 30 e 70: estrutura validada contra o leiaute real, ainda aguardando prova por emissão real. Informe icms.cst "10" (tributada com ST), "30" (isenta ou não tributada com ST) ou "70" (redução de base com ST), sempre com modBCST, vBCST, pICMSST e vICMSST; nos códigos 10 e 70 vai também o ICMS próprio (modBC, vBC, pICMS, vICMS, mais pRedBC no 70); opcionalmente pMVAST, pRedBCST e os trios de Fundo de Combate à Pobreza (vBCFCP/pFCP/vFCP e vBCFCPST/pFCPST/vFCPST). A margem de valor agregado e a alíquota interna de ST não são estimadas pela API (variam por UF, NCM e convênio): é você quem informa, e nada é recalculado a partir delas. A ST compõe o total da nota: vNF = produtos + vICMSST + vFCPST − desconto + frete/seguro/despesas + IPI, e os pagamentos precisam fechar com esse total. Bloco pela metade recusa com 422 ICMS_ST_INCOMPLETO, e combinação que o documento não representa com 422 ICMS_ST_INVALIDO (inclusive vICMS que não bate com vBC vezes pICMS, a única conta conferida). A desoneração NÃO é emitida nestes três códigos: vICMSDeson/motDesICMS com cst "30" ou "70" recusa com 422 nomeando o motivo (nos CST de benefício da linha abaixo ela emite), e a desoneração da própria ST (vICMSSTDeson) não existe no contrato. O cst: "90" EMITE, mas só a parcela de ICMS próprio dele (ver a linha de benefícios abaixo): a parcela de ST desse mesmo código continua recusada, pelo mesmo motivo de sempre (margem e alíquota interna não se chutam). Na NFC-e (modelo 65) o leiaute não admite esses códigos: 422 antes de numerar, e os campos do grupo devolvem 400 |
| Redução de base / isenção por benefício estadual (CST 20/40/41/50/51/90) | Disponível como passthrough manual (via csosn); sem detecção automática hoje. Os códigos de situação tributária de benefício (cst) são do Regime Normal: no Simples pleno e no MEI informá-los recusa com 422 CST_REGIME_INCOMPATIVEL, e o equivalente de lá (csosn 101/900) ainda não é emitido | Disponível na NF-e (modelo 55) e, para os códigos 20, 40 e 41, também na NFC-e (modelo 65), com crt: 3 e crt: 2. Informe icms.cst com o código do benefício e os números do seu ato concessório: 20 exige o grupo completo (modBC, pRedBC, baseCalculo já reduzida, aliquota, valor, e o valor tem que fechar com base vezes alíquota); 40, 41, 50 e 90 aceitam a desoneração (vICMSDeson + motDesICMS + indDeduzDeson, bloco indivisível, com os motivos válidos DIFERINDO por código); 51 aceita o diferimento (vICMSOp, pDif, vICMSDif, cBenefRBC, FCP diferido) e exige modBC. Bloco pela metade recusa com 422 ICMS_BENEFICIO_INCOMPLETO, campo no código errado ou motivo fora do conjunto daquele código com 422 ICMS_BENEFICIO_INVALIDO, e 50/51/90 na NFC-e com 422 ICMS_BENEFICIO_NAO_SUPORTADO. O ICMS próprio destes grupos usa os nomes do leiaute (vBC, pICMS, vICMS): os nomes clássicos baseCalculo/aliquota/valor continuam valendo no ICMS sem benefício e no Simples, mas junto de um código de benefício recusam com 422 ICMS_BENEFICIO_INVALIDO (dois nomes para a mesma tag fariam o motor descartar um deles em silêncio). No CST 30 (isenta ou não tributada COM substituição tributária) a desoneração ainda não é escrita pela engineAPI: o leiaute a prevê ali, e a recusa diz isso em voz alta em vez de pôr uma limitação nossa na conta da norma. Emitem também, só na NF-e (modelo 55), o crédito presumido do item (items[].gCred, até 4 por item) e o ato concessório do documento (procRef, até 100): na NFC-e esses dois grupos não fazem parte do contrato e enviá-los devolve 400 nomeando o campo. Nota com desonerações MISTAS recusa: se um item declara indDeduzDeson: "1" (deduz do total) e outro "0" (não deduz), o total sairia parcialmente deduzido e não há regra confirmada em texto oficial para esse caso, então a API recusa com 422 ICMS_BENEFICIO_INVALIDO em vez de transmitir um total que pode estar errado: use o mesmo indicador em todos os itens desonerados, ou separe as operações em duas notas. Item com indTot: 0 não pode declarar desoneração dedutora (recusa pelo mesmo código: o item sai do valor de mercadoria e não pode reduzir o total). vICMSDeson que arredonda para 0.00 também recusa, porque o grupo inteiro sumiria do documento. CST 90 sem nenhum bloco EMITE (o leiaute comporta o grupo só com a origem e o código, sem imposto destacado). Isso é comportamento da norma, não atalho da API. No CST 51, Rio de Janeiro e Paraná exigem os campos do diferimento mesmo zerados, o que a validação estrutural da engineAPI não impõe: nessas duas UFs informe o grupo completo. CST 20 provado com emissão real autorizada em homologação (protocolo 152260027584995, XML conferido tag a tag: redução de base de 60%, base R40,00eICMSR 7,20 no item, e o total do documento batendo com ele). CST 40, 41, 50, 51 e 90: estrutura validada contra o leiaute real e as regras de negócio do documento fiscal, ainda aguardando prova por emissão real. ⚠️ Em Goiás a SEFAZ exige o cBenef no CST 20 (medido ao vivo: sem ele a nota volta com a rejeição 930), e o código tem que ser o da tabela de benefícios da própria UF. Conferimos o FORMATO dos códigos de benefício, nunca a existência deles na tabela da sua UF: essa parte é responsabilidade do emitente, e a detecção automática do benefício continua fora (o caminho assistido emite tributação integral). Detalhe completo: Guia: Benefícios de ICMS |
| NF-e referenciada (documento que referencia uma nota anterior) (NF-e apenas) | Disponível, escopo: chave de acesso | Disponível, escopo: chave de acesso. Estrutura validada contra o leiaute real e as regras de negócio do documento fiscal; ainda aguardando prova por emissão real na SEFAZ. referenciadas[].chaveAcesso (44 dígitos do documento original: NF-e 55, NFC-e 65 ou CF-e SAT 59) vira a tag do documento referenciado, até 500 por nota. A chave é conferida antes de emitir (dígito verificador, código de UF, ano/mês, modelo, número não zerado, chave repetida e referência à própria nota): 422 REFERENCIADA_INVALIDA se não fechar. finNFe: 2 (complementar) aceita exatamente uma referência, e finNFe: 4 (devolução) também: na devolução o documento devolvido é referenciado item a item, e a engineAPI estampa a mesma nota de origem em todos os itens. Não conferimos o CNPJ nem a UF embutidos na chave contra o emitente: são regras que não confirmamos em texto oficial, e a API não crava regra fiscal sem fonte. Na devolução também não informamos qual item da nota original corresponde a cada item devolvido: o formato do documento permite omitir esse vínculo, mas há regra da Reforma que pode vir a exigi-lo, e ainda não confirmamos o texto oficial dela. Enquanto isso, a nota de origem vai carimbada em todos os itens. As demais variantes do grupo (nota de papel modelo 1/1A ou 2, produtor rural, CT-e, cupom de ECF) ainda não são suportadas: enviá-las devolve 400, nomeando o campo |
| Transporte (transportadora + volumes) (NF-e apenas) | Disponível, campos básicos: modalidade do frete, dados da transportadora, quantidade/espécie/peso dos volumes | Disponível, mesmos campos básicos |
| Transporte detalhado (veículo, reboque, lacres, balsa, vagão) (NF-e apenas) | Não suportado | Não suportado. O contrato aceita, em transporte, só modFrete, transportadora e volumes. Campos do leiaute completo (veiculo, reboque, lacres…) devolvem 400 nomeando o campo |
Combustíveis e GLP (grupo items[].combustivel) | Disponível, provado com emissão real autorizada em homologação (GLP com o grupo completo, protocolo 152260027547531). csosn manual + grupo combustivel (código ANP, e para GLP os percentuais e vPart); CFOP de combustível sem o grupo recusa antes com 422 COMBUSTIVEL_GRUPO_OBRIGATORIO, sem consumir numeração. Vale para NF-e e NFC-e. Detalhe completo: Guia: Combustíveis | Disponível pelos mesmos caminhos das linhas acima: tributação monofásica (CST 02/61) ou substituição tributária informada por você (CST 10/30/70 para o imposto cobrado nesta operação, 60 para a mercadoria já retida). O que continua fora é o repasse interestadual de ST em combustível (grupo ICMSST, com vBCSTDest/vICMSSTDest): enviá-lo devolve 400 |
| ICMS monofásico de combustíveis (CST 02 e 61) | Disponível: CST 02 (tributação própria, NF-e) e CST 61 (cobrada anteriormente, a revenda: NF-e e NFC-e), com quantidade tributada, alíquota ad rem (R$ por unidade) e valor. Vale também no Simples Nacional. A coerência valor = quantidade × alíquota é conferida antes de emitir, sobre o número que vai no documento. CST 15 e 53 (retenção e diferimento) ainda não. Ver Guia: Combustíveis | Disponível, mesmo comportamento: o grupo monofásico é passthrough e independe do regime |
Venda a prazo, fatura e duplicatas (grupo cobranca) (NF-e apenas) | Disponível, passthrough. pagamentos continua fechando o total transmitido; cobranca é informativo/financeiro e não altera vNF. Fatura e duplicatas auditadas entre si (422 COBRANCA_INVALIDA se divergirem), inclusive duplicatas sem fatura (#930, regra Y10-bis: MOC 7.0 Anexo I, Y01-20/Y10-10). Provado com emissão real transmitida em homologação (nota 608703, emissor RJ Vendas, SEFAZ GO): documento sem <fat> retornou 851, confirmando a recusa. Detalhe completo: Guia: Venda a prazo | Disponível, mesmo comportamento |
Devolução, complementar e ajuste (finNFe: 2/3/4) (NF-e apenas) | Disponível | Disponível. Estrutura validada contra o leiaute real e as regras de negócio do documento fiscal; ainda aguardando prova por emissão real na SEFAZ. As três finalidades exigem referenciadas (linha acima) apontando a nota original: sem ele a engineAPI recusa com 422 FINALIDADE_SEM_NFREF antes de numerar (a SEFAZ rejeitaria depois, com cStat 254 na complementar e cStat 321 na devolução). Ajuste e devolução (finNFe: 3/4) exigem também a forma de pagamento "90" (Sem Pagamento): pagamentos: [{ "forma": "90", "valor": 0 }], única entrada. O grupo de IPI devolvido pela indústria (impostoDevol) ainda não faz parte do contrato |
Sem pagamento (pagamentos[].forma: "90", remessa/bonificação/comodato/devolução) (NF-e apenas) | Disponível | Disponível. Estrutura validada contra o leiaute real e as regras de negócio do documento fiscal; ainda aguardando prova por emissão real na SEFAZ. Única entrada em pagamentos, com valor: 0 e sem troco: a conferência de soma dos pagamentos contra o total da nota não se aplica a essa forma. Outra forma junto de "90", ou troco maior que zero, recusa com 422 SEM_PAGAMENTO_INVALIDO. Na NFC-e a SEFAZ veda a forma "90": 422 SEM_PAGAMENTO_VEDADO_NFCE |
| Exportação (destinatário no exterior) (NF-e apenas) | Disponível como passthrough manual (via csosn); fora da curadoria do Cérebro Fiscal | Não suportado hoje, nenhum caminho: manual recusa (mesma regra de “não existe cst manual em Regime Normal” acima) e a emissão assistida não cobre UF de destino fora do Brasil (422 TRIBUTACAO_NAO_RESOLVIDA). Os grupos específicos de exportação (exporta, detExport) também não existem no contrato: devolvem 400 se enviados |
| Desconto incondicional no item | Disponível, NF-e e NFC-e. Base do ICMS/FCP e do IBS/CBS sai líquida do desconto | Disponível, mesmo comportamento |
| Desconto condicional (sob evento futuro) | Não suportado, sem campo no contrato (por lei integra a base, não é redutor) | Não suportado, mesmo motivo |
Seguro e outras despesas acessórias no item (valorSeguro/outrasDespesas) | Disponível. Somam no vNF e AUMENTAM a base do ICMS/FCP e do IBS/CBS (o inverso do desconto) | Disponível, mesmo comportamento |
Frete no item (valorFrete) | Disponível quando transporte.modFrete é por conta do próprio remetente (0=CIF, 3=transporte próprio, ou ausente/9 sem transporte). Com modFrete 1 (destinatário/FOB), 2 (terceiros) ou 4 (transporte próprio do destinatário), a API recusa (422): a lei só inclui o frete na base quando é o remetente que cobra | Não suportado hoje: a API recusa valorFrete em qualquer item (422). A NFC-e sempre emite como venda presencial (sem transporte); frete pressupõe entrega a domicílio, cenário que a NFC-e ainda não representa |
indTot (o item compõe o total do documento) | Disponível. 1 (default) compõe o vProd/vNF do total; 0 não compõe (a tributação do item não muda) | Só aceita 1 (ausente ou explícito). O leiaute rejeita indTot: 0 na NFC-e (MOC 7.0 Anexo I, RV I17b-10: “NFC-e com indicador de item não participante do total”): a API recusa com 422 antes de transmitir |
| Inutilização de numeração (faixa não usada) | Disponível, NF-e e NFC-e | Disponível, NF-e e NFC-e |
Todo campo fora do contrato de emissão recusa com
400, nomeando o campo (NF-e,
NFC-e, NFS-e e o envelope de lote). Não existe mais campo desconhecido aceito e
descartado em silêncio: se o cenário desta tabela está marcado Não suportado, o campo
correspondente do leiaute completo (refNF, veiculo, pRedBC, exporta…) devolve
erro explicando por que ainda não é suportado, em vez de sumir sem aviso.CST e CSOSN
| Regime | O que a emissão assistida resolve | O que fica de fora |
|---|---|---|
Simples (crt: 1) | CSOSN 102 (tributação pelo Simples, sem permissão de crédito) para todo item sem tributação manual | 103, 300 e 400 não são inferidos, mas emitem quando informados manualmente. 201, 202 e 203 (substituição tributária cobrada nesta operação) emitem só na NF-e, com o grupo da ST informado por você (ver a linha de Substituição Tributária acima). 101 (crédito), 500 e 900 recusam com 422 CSOSN_NAO_SUPORTADO: o 101 porque o leiaute exige pCredSN/vCredICMSSN num grupo que a API ainda não escreve, e 500/900 porque a Regra de Validação da NT 2024.001 exige mais do que a forma (CEST/CFOP para 500; resolução do destinatário para 900) |
MEI (crt: 4) | CSOSN 102 para todo item sem tributação manual | Domínio mais estreito que o Simples “pleno”: NF-e aceita 102/300/400 (sem 103); NFC-e só 102/300. Fora disso, mesmo 422 CSOSN_NAO_SUPORTADO |
Simples com excesso de sublimite (crt: 2) | Nenhum: este sub-regime usa cst, como o Regime Normal (NT 2024.001) | icms.csosn recusa com 422 CSOSN_REGIME_INCOMPATIVEL |
Regime Normal (crt: 3) | CST 00 (tributação integral), com base, alíquota, valor e FCP calculados | Nenhum outro CST é resolvido automaticamente. icms.cst informado à mão recusa com 422 CST_NAO_SUPORTADO_NFE, com quatro exceções, todas na NF-e e por passthrough (você informa os números): cst: "60" (ICMS já retido pelo fornecedor, a revenda) e cst "10"/"30"/"70" (substituição tributária cobrada nesta operação, onde modBC e modBCST fazem parte do contrato). Ver o estado da prova nas linhas de Substituição Tributária acima |
csosn num emissor crt: 3, cst num emissor
Simples) recusa antes da SEFAZ: catálogo completo, com o domínio efetivo de CSOSN
por crt/documento, em Erros e
Rejeições.
PIS, COFINS e IPI
Os três são passthrough: você informa o CST e os valores prontos, a engineAPI
valida a forma (contra o leiaute oficial) e transmite. Nada aqui é calculado: nem a
base, nem a alíquota, nem a quantidade tributável.
| Tributação | O que emite | O que fica de fora |
|---|---|---|
PIS/COFINS por ALÍQUOTA (pis.cst/cofins.cst "01"/"02") | Disponível na NF-e e na NFC-e: informe baseCalculo, aliquota e valor | Grupo pela metade (só um dos três campos) recusa com 422 PIS_NAO_SUPORTADO/COFINS_NAO_SUPORTADO |
PIS/COFINS por QUANTIDADE (pis.cst/cofins.cst "03") | Disponível na NF-e e na NFC-e: informe quantidadeVendida, valorAliquotaUnidade e valor (típico de combustível, bebida e cigarro, cuja base é a quantidade vendida na unidade de tributação, não o valor da operação). A quantidade tributável NÃO é derivada da quantidade comercial do item: pode ser diferente, e você informa a que vale para o tributo. Estrutura validada contra o leiaute real; ainda aguardando prova por emissão real na SEFAZ | Misturar os dois grupos no mesmo item (baseCalculo/aliquota junto de quantidadeVendida/valorAliquotaUnidade, ou vice-versa) recusa com 422, citando o campo que não pertence ao CST informado |
PIS/COFINS não tributado ("04"-"09") e outras operações ("49"-"56", "60"-"67", "70"-"75", "98", "99") | Disponível na NF-e e na NFC-e. No não tributado só o CST vai ao documento; em outras operações, baseCalculo/aliquota/valor são exigidos juntos, ou nenhum | Valor informado num CST não tributado recusa com 422: o documento carregaria só o CST, e o dado seria descartado |
IPI por ALÍQUOTA (ipi.cst "00"/"49"/"50"/"99") | Disponível só na NF-e (modelo 55; o leiaute do modelo 65 não tem grupo de IPI): informe baseCalculo, aliquota e valor. O IPI compõe o total da nota (vNF = produtos + IPI), e os pagamentos precisam fechar com esse total | Na NFC-e, ipi com qualquer conteúdo recusa com 422 IPI_NAO_SUPORTADO antes de emitir |
IPI por QUANTIDADE/pauta (mesmos CST acima, com quantidadeUnidadeTributavel/valorUnidadeTributavel) | Disponível só na NF-e: o MESMO CST tributado aceita, alternativamente, quantidadeUnidadeTributavel + valorUnidadeTributavel + valor (típico de bebida e cigarro, tributados por pauta/unidade em vez de percentual). Estrutura validada contra o leiaute real; ainda aguardando prova por emissão real na SEFAZ | Informar os dois pares (baseCalculo/aliquota E quantidadeUnidadeTributavel/valorUnidadeTributavel) no mesmo item recusa com 422: o leiaute aceita só um dos dois no mesmo IPI |
IPI não tributado ("01"-"05", "51"-"55") | Disponível na NF-e: só o CST vai ao documento | Valor informado num CST não tributado recusa com 422 IPI_NAO_SUPORTADO |
Reforma Tributária (IBS/CBS) na NF-e/NFC-e
IBS/CBS é obrigatório por lei desde 03/08/2026 para NF-e e NFC-e (regra geral), independente do regime do emissor. A engineAPI emite:| Cenário | Estado |
|---|---|
Redução de alíquota por NCM (gRed) | Disponível, provado com emissão real autorizada |
| Espelho divergente da tabela oficial | Recusa antes de transmitir, com o 422 explicando o que fazer |
| NCM em mais de um anexo (multiclasse) | Disponível: resolve automaticamente quando há uma classe única ou acordo entre candidatas; recusa pedindo ibsCbs.cClassTrib quando não há |
| Base de cálculo com desconto incondicional | Disponível |
| Base de cálculo com frete/seguro/outras despesas | Disponível: mesmo mecanismo do desconto, em sentido inverso |
422 específico: Reforma
Tributária: erros de IBS/CBS.
NFS-e
| Cenário | Estado |
|---|---|
| Resolução de CNAE para código de serviço (LC 116) | Disponível para os CNAEs cadastrados na base; CNAE fora da base retorna lista vazia de sugestões, nunca um código inventado |
| Emissão manual (você informa o código de serviço) | Disponível, passthrough |
| Alíquota de ISS | Disponível como passthrough manual. Na emissão assistida, um valor divergente do que a prefeitura calcularia é descartado de propósito (fica em avisos[] na resposta), porque ecoar o valor errado rejeitaria o documento |
| Retenções (ISS retido, IRRF/CSLL/INSS + indicador de PIS/COFINS) | Suportado. retencoes.issRetidoPor vira tpRetISSQN (ISS retido pelo tomador ou pelo intermediário) e os valores retidos de IRRF, CSLL e INSS vão para vRetIRRF, vRetCSLL e vRetCP na DPS. PIS e COFINS não têm campo de valor no leiaute nacional (os campos vPis/vCofins são débito de apuração própria e ficam fora do total de retenções): a retenção deles se declara pelo indicador dpsNacional.tpRetPisCofins, e valor informado recusa com 422 RETENCAO_SEM_CAMPO_NO_LEIAUTE. Passthrough: você informa o valor retido, a engineAPI não aplica alíquota de retenção. O grupo intermediario (identificação de quem intermediou) ainda não é aceito, e a emissão em sandbox simula sem escrever a retenção (a resposta avisa em avisos[]), enquanto o provedor municipal recusa. Ver Serviço B2B com retenção |
| Cancelamento e consulta de status | Disponível |
IBS/CBS na DPS (grupo ibsCbs) | Disponível como passthrough, quando você envia o bloco: o documento carrega o grupo <IBSCBS> do leiaute nacional. Emissão assistida (resolverTributacao: true) não opina sobre este grupo: os códigos cIndOp/cst/cClassTrib de serviço são seus |
IBS/CBS: destinatário diferente do tomador (indDest: "1") | Não suportado. 422 IBSCBS_DPS_DESTINATARIO_NAO_SUPORTADO: o leiaute exige junto o grupo dest (dados do destinatário), que este motor ainda não escreve. Use indDest: "0" quando o destinatário for o próprio tomador |
A DPS com IBS/CBS foi aceita pela SEFIN em produção em 15/09/2026. Além do bloco
ibsCbs, ela exige servico.codigoNBS: sem esse campo a SEFIN retorna E0322. O
contrato continua validado também contra o esquema XSD oficial.Fora do contrato público hoje
CT-e (modelo 57) e MDF-e (modelo 58) existem no roadmap, sem data. Distribuição de DFe (consulta de documentos de terceiros na SEFAZ) está fora do contrato público hoje. Nenhum dos três aparece nos endpoints documentados nesta doc.Próximos passos
Regime Normal
Como ativar a emissão assistida e o detalhe de cada recusa
Reforma Tributária: datas que importam
Calendário de obrigatoriedade do IBS/CBS por documento
Erros e Rejeições
Catálogo completo de códigos, formato RFC 7807
Guia: NFS-e
Emissão de serviços, cancelamento e Padrão Nacional