NF-e Tax Codes · TF Fiscal API

POST/api/category/create

Create tax category

Creates a new tax category (tax template) bound to the authenticated company. Each category aggregates scenarios of ICMS, IPI, PIS, COFINS, and optionally IBS/CBS and IS. To edit an existing one, use /api/category/edit.

Required headers

Header	Type	Description
token	string	Company token
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body — top-level

Field	Type	Description
descricao *	string	Category description
category_id	string	Custom ID. When omitted, auto-generated as `"TF"` + incremental number
disable_difal	boolean	Disables DIFAL calculation for this category. Default: `false`
desconta_icms_pis_cofins	boolean	Deduct ICMS before computing PIS/COFINS — tax on (amount − ICMS), the current Brazilian standard; default false (no deduction, higher tax)
icms[] *	array	ICMS scenarios (structure below)
ipi[] *	array	IPI scenarios (structure below)
pis[] *	array	PIS scenarios (structure below)
cofins[] *	array	COFINS scenarios (structure below)
ibs_cbs[]	array	IBS/CBS scenarios — tax reform (structure below)
is[]	array	IS scenarios — Selective Tax (structure below)

Body — `icms[]`

Field	Type	Description
tipo_tributacao *	string	ICMS tax type
cenario *	string	Scenario (e.g., `"saida_dentro_estado"`, `"saida_fora_estado"`, `"padrao"`)
tipo_pessoa *	string	`"fisica"` or `"juridica"`
codigo_cfop *	string	CFOP
situacao_tributaria *	string	ICMS CST/CSOSN
nao_contribuinte	boolean	Non-contributor customer
aliquota_importacao	string	Import rate
aliquota_credito	decimal	Credit rate (% for Simples Nacional)
aliquota_diferimento	decimal	Deferral percentage (not returned by `get_detail`)
aliquota_diferimentoFcp	string	FCP deferral (note: field uses camelCase `diferimentoFcp`; not returned by `get_detail`)
aliquota_reducao	decimal	ICMS base reduction percentage
aliquota_reducaoSt	decimal	ICMS-ST base reduction percentage (note: `reducaoSt` camelCase)
motivo_desoneracao	string	ICMS exemption reason code
motivo_desoneracaoSt	string	ICMS-ST exemption reason code (note: camelCase)
ad_rem_icms	decimal	Single-phase ICMS — ad rem rate in BRL/unit (CST 02, 15, 53)
ad_rem_icms_ret	decimal	Single-phase ICMS — withheld ad rem in BRL/unit (CST 15, 61)
p_dif_mono	decimal	Single-phase ICMS — deferral percentage (CST 53)
q_bc_mono	decimal	Single-phase ICMS — taxed quantity (liters/kg); 0 uses the item quantity (CST 02, 15, 53)
valor_desoneracao	decimal	Exempted ICMS amount in BRL — emits vICMSDeson (CST 40, 41, 50, 90)
v_bc_st_ret	decimal	Calculation base of the ICMS-ST withheld in the previous operation (provided, not calculated — CST 60, CSOSN 500)
p_st	decimal	Rate borne by the final consumer, in % (provided, not calculated — CST 60, CSOSN 500)
v_icms_st_ret	decimal	ICMS-ST amount withheld in the previous operation (provided, not calculated — CST 60, CSOSN 500)
v_icms_substituto	decimal	Substitute's own ICMS amount (provided, not calculated — CST 60, CSOSN 500)
v_bc_fcp_st_ret	decimal	Calculation base of the FCP withheld by ST (provided, not calculated — CST 60, CSOSN 500)
p_fcp_st_ret	decimal	FCP rate withheld by ST, in % (provided, not calculated — CST 60, CSOSN 500)
v_fcp_st_ret	decimal	FCP amount withheld by ST (provided, not calculated — CST 60, CSOSN 500)
Per-state rates — optional
aliquota_mva[]	array	MVA per UF — items: `{ estado, aliquota }`
aliquota_icms[]	array	ICMS rate per UF — items: `{ estado, aliquota }`
aliquota_icms_st[]	array	ICMS-ST rate per UF — items: `{ estado, aliquota }`
aliquota_fcp[]	array	FCP rate per UF — items: `{ estado, aliquota }`
aliquota_fcp_st[]	array	FCP-ST rate per UF — items: `{ estado, aliquota }`
beneficio_fiscal[]	array	Tax benefit code per UF — items: `{ estado, codigo }`

Body — `ipi[]`

Field	Type	Description
cenario *	string	Scenario
tipo_pessoa *	string	`"fisica"` or `"juridica"`
situacao_tributaria *	string	IPI CST
codigo_enquadramento *	string	Legal framework code
aliquota *	string	IPI rate
valor_unidade	string	IPI by quantity — value in BRL/unit; only used when there is no percentage rate (CST 00, 50, 49, 99)

Body — `pis[]` and `cofins[]` (same structure)

Field	Type	Description
cenario *	string	Scenario
tipo_pessoa *	string	`"fisica"` or `"juridica"`
situacao_tributaria *	string	PIS/COFINS CST
aliquota *	string	Rate
valor_unidade	string	PIS/COFINS by quantity — value in BRL/unit; v = quantity × value (CST 03 and other per-quantity forms)

Body — `ibs_cbs[]` (Tax Reform)

Field	Type	Description
cenario *	string	Scenario
tipo_pessoa *	string	`"fisica"` or `"juridica"`
situacao_tributaria *	string	IBS/CBS CST
classificacao_tributaria *	string	Tax classification
p_ibs_uf	string	IBS state rate in % (optional; empty uses the transition default, 0.10 in 2026). Accepts dot or comma
p_ibs_mun	string	IBS municipal rate in % (optional; default 0 in 2026)
p_cbs	string	CBS rate in % (optional; default 0.90 in 2026)
p_red_aliq	string	Rate reduction percentage (CST 011, 200, 515)
p_dif	string	Deferral percentage (CST 510, 515)
p_red_bc	string	Tax base reduction percentage (CST 222)
proporcao	string	Operation proportion in % (CST 221)
aliquota_cbs_mono	string	Single-phase CBS — rate in % over the base; takes precedence over `valor_unidade_cbs` (CST 620)
aliquota_ibs_mono	string	Single-phase IBS — rate in % over the base; takes precedence over `valor_unidade_ibs` (CST 620)
valor_unidade_cbs	string	Single-phase CBS — ad rem in BRL/unit; only used when there is no percentage rate (CST 620)
valor_unidade_ibs	string	Single-phase IBS — ad rem in BRL/unit; only used when there is no percentage rate (CST 620)
valor_deducao_legal	string	Legal base deduction value in BRL (CST 830)

Body — `is[]` (Selective Tax)

Field	Type	Description
cenario *	string	Scenario
tipo_pessoa *	string	`"fisica"` or `"juridica"`
situacao_tributaria *	string	IS CST
aliquota *	string	IS rate

* Required field.

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the placeholders
curl -X POST "https://api.tffiscal.com/api/category/create" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "descricao": "Venda de mercadoria padrão",
          "icms": [{
            "tipo_tributacao": "normal",
            "cenario": "padrao",
            "tipo_pessoa": "juridica",
            "codigo_cfop": "5102",
            "situacao_tributaria": "00"
          }],
          "ipi": [{
            "cenario": "padrao",
            "tipo_pessoa": "juridica",
            "situacao_tributaria": "99",
            "codigo_enquadramento": "999",
            "aliquota": "0"
          }],
          "pis": [{
            "cenario": "padrao",
            "tipo_pessoa": "juridica",
            "situacao_tributaria": "01",
            "aliquota": "0.65"
          }],
          "cofins": [{
            "cenario": "padrao",
            "tipo_pessoa": "juridica",
            "situacao_tributaria": "01",
            "aliquota": "3"
          }],
          "ibs_cbs": [{
            "cenario": "padrao",
            "tipo_pessoa": "juridica",
            "situacao_tributaria": "000",
            "classificacao_tributaria": "000001",
            "p_ibs_uf": "0.1",
            "p_ibs_mun": "0",
            "p_cbs": "0.9"
          }]
        }

        {
          "success": true,
          "data": {
            "category_id": "TF123"
          }
        }

GET/api/category/get_detail

Tax category details

Returns the complete configuration of a tax category: all ICMS, IPI, PIS, COFINS, IBS/CBS scenarios, including per-UF arrays (MVA, rates, tax benefits).

Required headers

Header	Type	Description
token	string	Company token
sign	string	MD5 signature (path includes the query string)
timestamp	string	Unix timestamp in seconds

Query string

Parameter	Type	Description
category_id *	string	Tax category ID

* Required field.

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the placeholders
curl -X GET "https://api.tffiscal.com/api/category/get_detail" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN"

GET /api/category/get_detail?category_id=TF123

        {
          "success": true,
          "data": {
            "category_id": "TF123",
            "descricao": "Venda de mercadoria padrão",
            "disable_difal": false,
            "desconta_icms_pis_cofins": false,
            "icms": [{
              "tipo_tributacao": "normal",
              "cenario": "padrao",
              "tipo_pessoa": "juridica",
              "nao_contribuinte": false,
              "codigo_cfop": "5102",
              "situacao_tributaria": "00",
              "aliquota_importacao": "",
              "aliquota_credito": 0,
              "aliquota_reducao": 0,
              "aliquota_reducao_st": 0,
              "motivo_desoneracao": "",
              "motivo_desoneracao_st": "",
              "ad_rem_icms": 0,
              "ad_rem_icms_ret": 0,
              "p_dif_mono": 0,
              "q_bc_mono": 0,
              "valor_desoneracao": 0,
              "v_bc_st_ret": 0,
              "p_st": 0,
              "v_icms_st_ret": 0,
              "v_icms_substituto": 0,
              "v_bc_fcp_st_ret": 0,
              "p_fcp_st_ret": 0,
              "v_fcp_st_ret": 0,
              "aliquota_icms": [{"estado":"SP","aliquota":18}]
            }],
            "ipi": [{
              "cenario": "padrao",
              "tipo_pessoa": "juridica",
              "situacao_tributaria": "99",
              "codigo_enquadramento": "999",
              "aliquota": "0",
              "valor_unidade": ""
            }],
            "pis": [{
              "cenario": "padrao",
              "tipo_pessoa": "juridica",
              "situacao_tributaria": "01",
              "aliquota": "0.65",
              "valor_unidade": ""
            }],
            "cofins": [{
              "cenario": "padrao",
              "tipo_pessoa": "juridica",
              "situacao_tributaria": "01",
              "aliquota": "3",
              "valor_unidade": ""
            }],
            "ibs_cbs": [{
              "cenario": "padrao",
              "tipo_pessoa": "juridica",
              "situacao_tributaria": "000",
              "classificacao_tributaria": "000001",
              "p_ibs_uf": "0.1",
              "p_ibs_mun": "0",
              "p_cbs": "0.9",
              "p_red_aliq": "",
              "p_dif": "",
              "p_red_bc": "",
              "proporcao": "",
              "aliquota_cbs_mono": "",
              "aliquota_ibs_mono": "",
              "valor_unidade_cbs": "",
              "valor_unidade_ibs": "",
              "valor_deducao_legal": ""
            }]
          }
        }

GET/api/category/get_list

List tax categories

Lists the tax categories of the authenticated company with pagination. Returns category_id, descricao and the ibs_cbs block (Tax Reform) of each category — for the remaining taxes use /api/category/get_detail.

Required headers

Header	Type	Description
token	string	Company token
sign	string	MD5 signature (path includes the query string)
timestamp	string	Unix timestamp in seconds

Query string

Parameter	Type	Description
page *	int	Page number (≥ 1)
page_size *	int	Page size (1–50)

* Required field.

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the placeholders
curl -X GET "https://api.tffiscal.com/api/category/get_list" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN"

GET /api/category/get_list?page=1&page_size=20

        {
          "success": true,
          "data": {
            "list": [
              {
                "category_id": "TF123",
                "descricao": "Venda de mercadoria padrão",
                "ibs_cbs": [{
                  "situacao_tributaria": "000",
                  "classificacao_tributaria": "000001",
                  "p_ibs_uf": "0.1",
                  "p_ibs_mun": "0",
                  "p_cbs": "0.9",
                  "p_red_aliq": "",
                  "p_dif": "",
                  "p_red_bc": "",
                  "proporcao": "",
                  "aliquota_cbs_mono": "",
                  "aliquota_ibs_mono": "",
                  "valor_unidade_cbs": "",
                  "valor_unidade_ibs": "",
                  "valor_deducao_legal": ""
                }]
              },
              {
                "category_id": "TF124",
                "descricao": "Devolução de venda",
                "ibs_cbs": []
              }
            ],
            "page": 1,
            "total": 2,
            "total_pages": 1
          }
        }

POST/api/category/edit

Edit tax category

Edits an existing tax category. The body is identical to /api/category/create, the only difference being that category_id is required and must match an existing category. The upsert fully replaces the icms, ipi, pis, cofins, ibs_cbs, is arrays — send all updated scenarios (there is no per-scenario merge).

Required headers

Header	Type	Description
token	string	Company token
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

The full body structure is documented in /api/category/create. Only category_id is handled differently here:

Field	Type	Description
category_id *	string	ID of the category to edit (must exist; otherwise returns an error)
descricao *	string	Description
icms[] *	array	ICMS scenarios (fully replaces)
ipi[] *	array	IPI scenarios
pis[] *	array	PIS scenarios
cofins[] *	array	COFINS scenarios
ibs_cbs[]	array	IBS/CBS scenarios (optional)
is[]	array	IS scenarios (optional)
disable_difal	boolean	Default: `false`
desconta_icms_pis_cofins	boolean	Deduct ICMS before computing PIS/COFINS — tax on (amount − ICMS), the current Brazilian standard; default false (no deduction, higher tax)

* Required field. For the inner fields of each array (icms[].codigo_cfop etc.), see /api/category/create.

POST/api/category/delete

Delete tax category

Removes a tax category from the company. Irreversible operation. Products bound to this category will continue referencing the removed category_id, so NFe issuance will fail — update the products before deleting.

Required headers

Header	Type	Description
token	string	Company token
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
category_id *	string	ID of the category to delete

* Required field.

Create tax category

Required headers

Body — top-level

Body — icms[]

Body — ipi[]

Body — pis[] and cofins[] (same structure)

Body — ibs_cbs[] (Tax Reform)

Body — is[] (Selective Tax)

Tax category details

Required headers

Query string

List tax categories

Required headers

Query string

Edit tax category

Required headers

Body

Delete tax category

Required headers

Body

Body — `icms[]`

Body — `ipi[]`

Body — `pis[]` and `cofins[]` (same structure)

Body — `ibs_cbs[]` (Tax Reform)

Body — `is[]` (Selective Tax)