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.
| Step | Endpoint | Note |
|---|---|---|
| 1 Create | POST .../classes-imposto | The 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 issuance | NF-e issuance · NFC-e issuance | Send 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 |
| Maintain | List · Get · Update · Delete | The 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.
| Rule | NFe | NFCe |
|---|---|---|
| Allowed groups | icms, ipi, pis, cofins, ibsCbs; no issqn | icms, issqn, pis, cofins, ibsCbs; no ipi |
| Allowed scenarios | All seven | Only SaidaDentroEstado and Padrao |
| Row fields | Every field of the same-name NF-e issuance group | Only fields NFC-e issuance has: an ICMS row without substituicaoTributaria, difal, partilha, percentualCreditoSimples, deferral, etc.; PIS / COFINS only with situacaoTributaria and aliquota |
| On violation | issqn gives 10005218 | ipi 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
| Group | Fields of each row | Row count |
|---|---|---|
icms | Scenario dimensions + cfop + fields of itens[].impostos.icms in NF-e issuance | With issqn, at least 1 row |
issqn | Scenario dimensions + cfop + every field of impostos.issqn in NFC-e issuance; NFCe only | With icms, at least 1 row |
pis / cofins | Scenario dimensions + fields of the same-name issuance group | At least 1 row each |
ipi | Scenario dimensions + fields of the NF-e issuance ipi group; NFe only | Optional |
ibsCbs | Scenario dimensions + fields of the same-name issuance group | Optional |
The scenario dimensions are three fields:
cenario: scenario, required, values in the table below.tipoPessoa: customer type,Fisicaindividual,Juridicacompany,Estrangeirobuyer abroad; omitted, it applies to any type.naoContribuinte: non-taxpayer buyer,trueonly for a buyer that is not an ICMS taxpayer,falseonly 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
cenario | Meaning | When the invoice falls in it | Customer types that match | First digit of cfop |
|---|---|---|---|---|
SaidaDentroEstado | In-state outbound | Outbound invoice, buyer in the company's state; NFC-e always uses this scenario | Fisica, Juridica | 5 |
SaidaForaEstado | Interstate outbound | Outbound invoice, buyer in another state | Fisica, Juridica | 6 |
SaidaExterior | Export | Outbound invoice, buyer abroad | Estrangeiro | 7 |
EntradaDentroEstado | In-state inbound | Return invoice, counterparty in the company's state | Fisica, Juridica | 1 |
EntradaForaEstado | Interstate inbound | Return invoice, counterparty in another state | Fisica, Juridica | 2 |
EntradaExterior | Inbound from abroad | Return invoice, counterparty abroad | Estrangeiro | 3 |
Padrao | General | Any invoice; only used when no row of the scenario fits. Not for ICMS | Any | Free |
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:
| Dimension | On NF-e | On NFC-e |
|---|---|---|
| Scenario | A 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 abroad | Always SaidaDentroEstado |
| Customer type | Buyer with CPF is Fisica, with CNPJ is Juridica, abroad is Estrangeiro | Same; with no identified buyer, Fisica |
| Non-taxpayer | true when the buyer taxpayer indicator is NaoContribuinte, including the one the platform derives | Always true |
Then, in each group, the first row matching in this order wins:
| Order | Matching row |
|---|---|
| 1 | Same scenario, tipoPessoa and naoContribuinte filled and equal to the invoice |
| 2 | Same scenario, tipoPessoa equal, naoContribuinte omitted |
| 3 | Same scenario, tipoPessoa omitted, naoContribuinte equal |
| 4 | Same scenario, both omitted |
| 5 | Padrao 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
| Group | No row |
|---|---|
| ICMS (ISSQN on a service line), PIS, COFINS | Issuance rejected with 10005209; the message gives the class, group, scenario, customer type and whether the buyer is a non-taxpayer |
| IPI, IBS/CBS | The 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.
{"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:
| Situation | Uses |
|---|---|
The request impostos has icms or issqn | The 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 cfop | The ICMS row of the class |
Request without cfop | If 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:
| Field | State used | On issuance |
|---|---|---|
icms[].beneficiosFiscaisPorEstado | Issuer state | A row for the state replaces the row's codigoBeneficioFiscal; without it the row value applies |
icms[].creditosPresumidosPorEstado | Issuer state | Rows for the state (up to 4) replace the row's creditosPresumidos; without them the row values apply |
icmsPorEstado (class root, NFe only) | Buyer state | A 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.
{"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 withoutpercentualCreditoSimpleson the row or in the company record:10004043. A CRT 3 company with PIS / COFINS01or02withoutaliquotaand no legal rate for its PIS/COFINS regime:10005008. - Taxpayer-only codes: an ICMS row with explicit
naoContribuinte=trueortipoPessoa=Fisicacannot use CST / CSOSN 10, 30, 70, 101, 201, 202, 203 orpercentualCreditoSimples; otherwise10004047, the same rule as issuance. - CFOP and group: an ISSQN row only with
5933, an ICMS row never with5933(10005214). - Whole replacement: update takes the whole class, without
codigoand with the sametipo; any group or row not sent stops existing. - Unknown fields rejected: any non-existent field, at any level, gives
10005210with the path, such asicms[0].aliquotaX. This only applies to the class endpoints; issuance is unchanged. - Strict types: numbers as JSON numbers (
"aliquota": 18, never"18") and booleans astrue/false; sent as text they give10005213with the path. - Numbers as sent:
18.00stored comes back18.00on 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:
situacao | Meaning | At issuance |
|---|---|---|
Compativel | Passes validation under the current company regime | Normal |
IncompativelComRegime | The company regime changed and the class no longer passes; reasons in motivosIncompatibilidade | 10005220 |
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:
| Field | Description |
|---|---|
grupo | Group with the problem, such as icms; absent when it cannot be pinpointed |
linha | Row in the group, from 0; absent when it cannot be pinpointed |
campo | Row field, such as situacaoTributaria; absent when it cannot be pinpointed |
codigoErro | Code saving would return, such as 10004046 |
crt | Company CRT at revalidation |
regimeTributario | PIS/COFINS regime at revalidation: 1 Simples Nacional, 2 Lucro Presumido, 3 Lucro Real; absent if not registered |
mensagem | Explanation 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.
{"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:
{ "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
classeImpostoandversaoClasseImpostoon 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
| Code | HTTP | Meaning |
|---|---|---|
| 10005200 | 404 | Tax class not found or deleted |
| 10005202 | 400 | The class referenced at issuance is missing, deleted or from another company |
| 10005203 | 400 | Unsupported tax code |
| 10005204 | 400 | Classification does not belong to the CST |
| 10005205 | 400 | Referenced class with a field NFC-e does not support |
| 10005206 | 409 | Class modified concurrently |
| 10005208 | 400 | codigo in the body; the code is generated by the platform |
| 10005209 | 400 | Group the line needs has no row for this invoice |
| 10005210 | 400 | Unknown field in the body |
| 10005211 | 400 | Scenario combination repeated in the group |
| 10005212 | 400 | First digit of CFOP not matching the scenario |
| 10005213 | 400 | Number or boolean sent as text |
| 10005214 | 400 | CFOP outside its group: ISSQN only with 5933, ICMS never with 5933 |
| 10005215 | 400 | Referenced class type differs from the document |
| 10005216 | 400 | Class type cannot be changed |
| 10005217 | 400 | NFCe class with a field NFC-e does not support |
| 10005218 | 400 | Group the class type does not allow |
| 10005219 | 400 | NFCe class with a scenario outside SaidaDentroEstado or Padrao |
| 10005220 | 400 | Referenced class incompatible with the current company regime |
| 10005230 | 400 | Relief reason outside the values of the CST |
| 10005231 | 400 | Per-invoice amount in the class |
| 10005232 | 400 | icmsPorEstado with a value no ICMS row uses |
| 10005233 | 400 | State repeated in a per-state setting |
| 10005234 | 400 | More than 4 presumed credits for the same state |
| 10005235 | 400 | Relief 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.
