TF Fiscal
Documentation

Tax classes

Tax classes: store NF-e / NFC-e item taxes as per-scenario rows under a code and send only the code on each invoice line; class type, scenarios, row selection order, error when no row fits, CFOP from the class and its override, group override, save rules, regime change and status, versions and idempotency, error codes.

Overview

A tax class is a set of item taxes stored on an issuing company, for example "Goods resale - SP". Instead of a single configuration, each group of the class is a list of rows, one per scenario: in-state sale to a company, interstate sale to an individual… At issuance the platform picks, in each group, the row that fits the scenario, customer type and buyer of the invoice.

StepEndpointNote
1 CreatePOST .../classes-impostoThe platform generates the code and returns it in the response; choose the type NFe or NFCe; every row validated against the company regime
2 Reference at issuanceNF-e issuance · NFC-e issuanceSend that code in classeImposto on the line; cfop and impostos may be omitted; with the Invoice Assistant and the embedded SDK, referencing a tax class needs a connection, see Tax classes and connectivity
MaintainList · Get · Update · DeleteThe list filters by tipo and situacao; update replaces the whole class

All paths are under /openapi/v2/empresas/{empresaId}/, with the same authentication as the other endpoints, see Authentication.

The class code is generated by the platform: TF and 10 digits, the first 9 random and the last a check digit, for example TF4440123455. It is unique across the whole platform and never reused, even after deletion. The creation and whole-replacement bodies do not carry codigo; sending it gives 10005208. Detail, replacement and deletion locate the class by the code in the path. The application must subscribe to the scopes "Tax class management", "Tax class detail and update" and "Tax class deletion"; otherwise the response is 403.

Class type

Each class gets its tipo on creation and it never changes afterwards (10005216). Issuance only accepts its own type: NF-e only references NFe classes and NFC-e only NFCe classes, otherwise 10005215.

RuleNFeNFCe
Allowed groupsicms, ipi, pis, cofins, ibsCbs; no issqnicms, issqn, pis, cofins, ibsCbs; no ipi
Allowed scenariosAll sevenOnly SaidaDentroEstado and Padrao
Row fieldsEvery field of the same-name NF-e issuance groupOnly fields NFC-e issuance has: an ICMS row without substituicaoTributaria, difal, partilha, percentualCreditoSimples, deferral, etc.; PIS / COFINS only with situacaoTributaria and aliquota
On violationissqn gives 10005218ipi gives 10005218, a scenario outside gives 10005219, an unsupported field gives 10005217 with the path

Retail and wholesale usually differ in taxation; if the same business issues both documents, create one class of each type.

Groups and rows

GroupFields of each rowRow count
icmsScenario dimensions + cfop + fields of itens[].impostos.icms in NF-e issuanceWith issqn, at least 1 row
issqnScenario dimensions + cfop + every field of impostos.issqn in NFC-e issuance; NFCe onlyWith icms, at least 1 row
pis / cofinsScenario dimensions + fields of the same-name issuance groupAt least 1 row each
ipiScenario dimensions + fields of the NF-e issuance ipi group; NFe onlyOptional
ibsCbsScenario dimensions + fields of the same-name issuance groupOptional

The scenario dimensions are three fields:

  • cenario: scenario, required, values in the table below.
  • tipoPessoa: customer type, Fisica individual, Juridica company, Estrangeiro buyer abroad; omitted, it applies to any type.
  • naoContribuinte: non-taxpayer buyer, true only for a buyer that is not an ICMS taxpayer, false only for a taxpayer or a buyer exempt from registration; omitted, it applies to any buyer.

The combination of the three cannot repeat within a group (10005211), so an invoice fully matches at most one row per group. Each group has at most 50 rows.

The row tipoPessoa and the NF-e issuance cliente.tipoPessoa are different fields: the issuance one stays F / J and describes the buyer; the row one uses Fisica / Juridica / Estrangeiro and says which customer the row applies to, compared at issuance with the type derived from the CPF, the CNPJ or a buyer abroad.

CRT, Simples option, environment and series always come from the company record; the class has no such fields. CEST and the product origin origem belong to the invoice line and are still sent in itens[].

Scenarios

cenarioMeaningWhen the invoice falls in itCustomer types that matchFirst digit of cfop
SaidaDentroEstadoIn-state outboundOutbound invoice, buyer in the company's state; NFC-e always uses this scenarioFisica, Juridica5
SaidaForaEstadoInterstate outboundOutbound invoice, buyer in another stateFisica, Juridica6
SaidaExteriorExportOutbound invoice, buyer abroadEstrangeiro7
EntradaDentroEstadoIn-state inboundReturn invoice, counterparty in the company's stateFisica, Juridica1
EntradaForaEstadoInterstate inboundReturn invoice, counterparty in another stateFisica, Juridica2
EntradaExteriorInbound from abroadReturn invoice, counterparty abroadEstrangeiro3
PadraoGeneralAny invoice; only used when no row of the scenario fits. Not for ICMSAnyFree

First digit of cfop not matching the scenario: 10005212. The ISSQN row cfop is always 5933, including on Padrao, and an ICMS row cannot use 5933; otherwise 10005214. For groups that are the same in every scenario, such as PIS and COFINS, a single Padrao row is enough.

How the row is picked at issuance

The platform derives three values from the invoice:

DimensionOn NF-eOn NFC-e
ScenarioA return is inbound, everything else outbound; buyer in the company's state is in-state, another state is interstate, a buyer abroad (cliente.idEstrangeiro, endereco.uf equal to EX) is abroadAlways SaidaDentroEstado
Customer typeBuyer with CPF is Fisica, with CNPJ is Juridica, abroad is EstrangeiroSame; with no identified buyer, Fisica
Non-taxpayertrue when the buyer taxpayer indicator is NaoContribuinte, including the one the platform derivesAlways true

Then, in each group, the first row matching in this order wins:

OrderMatching row
1Same scenario, tipoPessoa and naoContribuinte filled and equal to the invoice
2Same scenario, tipoPessoa equal, naoContribuinte omitted
3Same scenario, tipoPessoa omitted, naoContribuinte equal
4Same scenario, both omitted
5Padrao rows, in the same order 1 to 4; ICMS has no such step

A filled dimension that differs from the invoice never matches. For example, a row with "tipoPessoa": "Juridica" is not picked on a sale to an individual, even if it is the only in-state row.

When no row fits

GroupNo row
ICMS (ISSQN on a service line), PIS, COFINSIssuance rejected with 10005209; the message gives the class, group, scenario, customer type and whether the buyer is a non-taxpayer
IPI, IBS/CBSThe invoice line goes without the group

To fix it, add a row to the class or send the group directly in the request.

CFOP from the class

With no cfop on the invoice line, the cfop of the chosen ICMS row applies; when the chosen row is ISSQN, its 5933 applies. With cfop in the request, the request one applies. So the same product goes in-state or interstate with an identical invoice line, and the CFOP 5102 or 6102 comes from the scenario.

Direct sending and group override

A group sent in impostos on the invoice line is used whole, and the class picks no row for it; groups not sent still come from the class. Fields within a group are not mixed: if the chosen ICMS row is CST 20 with base reduction and the request replaces ICMS with CST 00, the result is the request's CST 00, with no leftover reduction.

json
{
"codigo": "SKU-1",
"classeImposto": "TF4440123455",
"cfop": "6102",
"impostos": { "icms": { "situacaoTributaria": "00", "aliquota": 12 } }
}

In the example ICMS is the request's 00 / 12 %; PIS, COFINS and IBS/CBS come from the class rows. With icms (or issqn) in the request there is no row to take the CFOP from, so cfop must come in the request, otherwise 10001002.

ICMS and ISSQN go together, and each invoice line uses only one of them:

SituationUses
The request impostos has icms or issqnThe request group; no ICMS or ISSQN row of the class
Request with cfop 5933 (NFC-e service line)The ISSQN row of the class
Request with another cfopThe ICMS row of the class
Request without cfopIf the class icms group has rows, it only picks among them, and with no fitting row it gives 10005209; only with an empty icms group does it use the ISSQN row. NF-e only has ICMS

Precedence: request > tax class > company record > platform rate table (CRT 3 only) > rejected naming the field. An ICMS row without aliquota and FCP uses the platform rate table. The tax share percentualCargaTributaria is not in the class: it only applies when sent in the request impostos; without it, the platform uses the IBPT table.

Per-state settings, relief and presumed credit

Besides the issuance fields (including motivoDesoneracao, motivoDesoneracaoSt, deduzDesonerado, codigoBeneficioFiscalReducaoBase and creditosPresumidos), an ICMS row accepts per-state settings:

FieldState usedOn issuance
icms[].beneficiosFiscaisPorEstadoIssuer stateA row for the state replaces the row's codigoBeneficioFiscal; without it the row value applies
icms[].creditosPresumidosPorEstadoIssuer stateRows for the state (up to 4) replace the row's creditosPresumidos; without them the row values apply
icmsPorEstado (class root, NFe only)Buyer stateA row for the state replaces aliquota, substituicaoTributaria.aliquota and substituicaoTributaria.mva of the chosen ICMS row; what is not given follows the row and, without it, the platform table

Benefit and presumed credit codes come from the issuer state's table, so they follow the issuer state; ST rate and MVA follow the destination, so they follow the buyer state. The per-state rate applies only to rows with CST 00, 10, 20, 30, 51, 70, 90 and CSOSN 201, 202, 203, 900; the per-state ST only to rows with CST 10, 30, 70, 90 and CSOSN 201, 202, 203, 900. When the invoice sends the icms group it applies whole and none of this is used.

Relief amount, ICMS-ST relief amount and presumed credit amount are per-invoice amounts and do not exist in the class (10005231); omitted, the platform computes them by CST, see NF-e issuance. When the platform cannot compute the amount, the class is rejected on save with 10005235: the ICMS-ST relief reason motivoDesoneracaoSt needs the ST base reduction substituicaoTributaria.percentualReducaoBase, and the platform takes the ICMS-ST without the reduction minus the one due; a CST 90 relief reason needs percentualReducaoBase. Relief that does not come from a base reduction can only be sent in the issuance request, with reason and amount, without a class.

json
{
"tipo": "NFe",
"icms": [
{ "cenario": "SaidaDentroEstado", "cfop": "5102", "situacaoTributaria": "20", "aliquota": 18,
"percentualReducaoBase": 33.33, "motivoDesoneracao": 9,
"beneficiosFiscaisPorEstado": [ { "uf": "SP", "codigo": "SP800001" } ],
"creditosPresumidosPorEstado": [ { "uf": "SP", "codigo": "SP000001", "percentual": 2.5 } ] },
{ "cenario": "SaidaForaEstado", "cfop": "6102", "situacaoTributaria": "10", "aliquota": 12,
"substituicaoTributaria": { "mva": 40, "aliquota": 18 } }
],
"icmsPorEstado": [
{ "uf": "RJ", "aliquota": 12, "substituicaoTributaria": { "aliquota": 20, "mva": 55 } }
],
"pis": [ { "cenario": "Padrao", "situacaoTributaria": "01", "aliquota": 1.65 } ],
"cofins": [ { "cenario": "Padrao", "situacaoTributaria": "01", "aliquota": 7.6 } ]
}

A row with an ST CST needs the ST mva and aliquota; when icmsPorEstado provides them the row may omit them, and issuance only rejects (10004043) when the buyer state has no setting and the row has none either.

Save rules

  • Validation by company regime: a company with CRT 1 / 4 only uses a 3-digit CSOSN, CRT 2 / 3 only a 2-digit CST; otherwise 10004046. CSOSN 101 / 201 without percentualCreditoSimples on the row or in the company record: 10004043. A CRT 3 company with PIS / COFINS 01 or 02 without aliquota and no legal rate for its PIS/COFINS regime: 10005008.
  • Taxpayer-only codes: an ICMS row with explicit naoContribuinte = true or tipoPessoa = Fisica cannot use CST / CSOSN 10, 30, 70, 101, 201, 202, 203 or percentualCreditoSimples; otherwise 10004047, the same rule as issuance.
  • CFOP and group: an ISSQN row only with 5933, an ICMS row never with 5933 (10005214).
  • Whole replacement: update takes the whole class, without codigo and with the same tipo; any group or row not sent stops existing.
  • Unknown fields rejected: any non-existent field, at any level, gives 10005210 with the path, such as icms[0].aliquotaX. This only applies to the class endpoints; issuance is unchanged.
  • Strict types: numbers as JSON numbers ("aliquota": 18, never "18") and booleans as true / false; sent as text they give 10005213 with the path.
  • Numbers as sent: 18.00 stored comes back 18.00 on read.
  • Row limit: up to 50 rows per group; above that, 10001001.

Every row also goes through all the checks of the same-name issuance group; save-time checks and errors are in Create tax class. Every value of each field and the fields each code requires on save are in that page's enums section and in "Formats of the other fields".

Regime change and status

The response and the list items carry situacao:

situacaoMeaningAt issuance
CompativelPasses validation under the current company regimeNormal
IncompativelComRegimeThe company regime changed and the class no longer passes; reasons in motivosIncompatibilidade10005220

When the company CRT, PIS/COFINS regime or record percentualCreditoSimples changes, the platform revalidates every class of the company with the same rules as saving and marks or unmarks each one by itself. The marking does not change versao. On the move from compatible to incompatible the tax_class.incompatible webhook arrives (explicit subscription required, see Webhooks); a class that was already incompatible only updates its reasons, without a new delivery.

Each item of motivosIncompatibilidade:

FieldDescription
grupoGroup with the problem, such as icms; absent when it cannot be pinpointed
linhaRow in the group, from 0; absent when it cannot be pinpointed
campoRow field, such as situacaoTributaria; absent when it cannot be pinpointed
codigoErroCode saving would return, such as 10004046
crtCompany CRT at revalidation
regimeTributarioPIS/COFINS regime at revalidation: 1 Simples Nacional, 2 Lucro Presumido, 3 Lucro Real; absent if not registered
mensagemExplanation in the request language, the same text as the save error

To fix it, replace the whole class under the new regime (update tax class); once it passes validation it is back to Compativel and versao adds 1. The list with situacao=IncompativelComRegime shows every class to fix.

Example

An SP company in the regular regime (CRT 3): four ICMS rows, in-state / interstate × individual / company, and one Padrao row for PIS, COFINS and IBS/CBS.

json
{
"tipo": "NFe",
"descricao": "Revenda de mercadorias - SP",
"icms": [
{ "cenario": "SaidaDentroEstado", "tipoPessoa": "Juridica", "cfop": "5102", "situacaoTributaria": "00", "aliquota": 18 },
{ "cenario": "SaidaDentroEstado", "tipoPessoa": "Fisica", "cfop": "5102", "situacaoTributaria": "00", "aliquota": 18 },
{ "cenario": "SaidaForaEstado", "tipoPessoa": "Juridica", "cfop": "6102", "situacaoTributaria": "00", "aliquota": 12 },
{ "cenario": "SaidaForaEstado", "tipoPessoa": "Fisica", "cfop": "6108", "situacaoTributaria": "00", "aliquota": 12 }
],
"pis": [{ "cenario": "Padrao", "situacaoTributaria": "01", "aliquota": 1.65 }],
"cofins": [{ "cenario": "Padrao", "situacaoTributaria": "01", "aliquota": 7.6 }],
"ibsCbs": [{ "cenario": "Padrao", "situacaoTributaria": "000", "classificacaoTributaria": "000001" }]
}

An NF-e to a company in RJ, with the line sending only the code returned on creation:

json
{ "codigo": "000068", "descricao": "Pendrive 16GB", "ncm": "85235190", "quantidade": 1, "unidadeMedida": "UN", "valorUnitario": 28.47, "classeImposto": "TF4440123455" }

The derived scenario is SaidaForaEstado with Juridica, and ICMS matches the third row: CFOP 6102, CST 00, rate 12 %; PIS, COFINS and IBS/CBS come from the Padrao rows.

A Simples company (CRT 1 / 4) uses CSOSN; the example is in Create tax class, section "Example: Simples Nacional company".

Classes for NFC-e

NFC-e only references NFCe classes. Their rows are already validated on save with the NFC-e issuance rules (see "Class type"), so issuance does not reject them for an unsupported field. NFC-e always picks with SaidaDentroEstado and a non-taxpayer buyer: ICMS rows other than Padrao use SaidaDentroEstado, and a row with "naoContribuinte": false never matches.

Versions and past invoices

  • Creation is version 1; after that, every change adds 1, including only descricao; a replacement with identical content keeps the version.
  • The expanded result is stored with the invoice at acceptance, and query responses show classeImposto and versaoClasseImposto on the line. Lines without a class do not carry these two fields.
  • Changing or deleting the class later does not affect accepted invoices.
  • On an identical resubmission with the same id, the comparison uses the original request, before the class is expanded; on a match the original task comes back without reading the class, even if it changed version, was deleted or no longer has a fitting row. This applies to NF-e and NFC-e. A different body is still rejected by the usual rules.

Error codes

CodeHTTPMeaning
10005200404Tax class not found or deleted
10005202400The class referenced at issuance is missing, deleted or from another company
10005203400Unsupported tax code
10005204400Classification does not belong to the CST
10005205400Referenced class with a field NFC-e does not support
10005206409Class modified concurrently
10005208400codigo in the body; the code is generated by the platform
10005209400Group the line needs has no row for this invoice
10005210400Unknown field in the body
10005211400Scenario combination repeated in the group
10005212400First digit of CFOP not matching the scenario
10005213400Number or boolean sent as text
10005214400CFOP outside its group: ISSQN only with 5933, ICMS never with 5933
10005215400Referenced class type differs from the document
10005216400Class type cannot be changed
10005217400NFCe class with a field NFC-e does not support
10005218400Group the class type does not allow
10005219400NFCe class with a scenario outside SaidaDentroEstado or Padrao
10005220400Referenced class incompatible with the current company regime
10005230400Relief reason outside the values of the CST
10005231400Per-invoice amount in the class
10005232400icmsPorEstado with a value no ICMS row uses
10005233400State repeated in a per-state setting
10005234400More than 4 presumed credits for the same state
10005235400Relief amount cannot be computed; send it on issuance

General codes: 10001001 field validation failed, 10001002 cfop missing with icms or issqn sent directly, 10004043 field required by the code missing, 10004044 field does not apply to the code, 10004046 code incompatible with the company regime, 10004047 taxpayer-only code on a non-taxpayer row, 10005008 missing legal PIS/COFINS rate, 10003000 company not found.