Categorias fiscais NF-e · TF Fiscal API

POST/api/category/create

Criar categoria fiscal

Cria uma nova categoria fiscal (template de impostos) vinculada à empresa autenticada. Cada categoria agrega cenários de ICMS, IPI, PIS, COFINS, e opcionalmente IBS/CBS e IS. Para editar uma existente, use /api/category/edit.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa
sign	string	Assinatura MD5
timestamp	string	Unix timestamp em segundos

Body — top-level

Campo	Tipo	Descrição
descricao *	string	Descrição da categoria fiscal
category_id	string	ID customizado. Quando omitido, é auto-gerado no formato `"TF"` + número incremental
disable_difal	boolean	Desabilita o cálculo de DIFAL para esta categoria. Default: `false`
desconta_icms_pis_cofins	boolean	Abate o ICMS antes de calcular PIS/COFINS — tributa (valor − ICMS), padrão atual no Brasil; default false (sem abatimento, imposto maior)
icms[] *	array	Cenários de ICMS (estrutura abaixo)
ipi[] *	array	Cenários de IPI (estrutura abaixo)
pis[] *	array	Cenários de PIS (estrutura abaixo)
cofins[] *	array	Cenários de COFINS (estrutura abaixo)
ibs_cbs[]	array	Cenários de IBS/CBS — reforma tributária (estrutura abaixo)
is[]	array	Cenários de IS — Imposto Seletivo (estrutura abaixo)

Body — `icms[]`

Campo	Tipo	Descrição
tipo_tributacao *	string	Tipo de tributação ICMS
cenario *	string	Cenário (ex.: `"saida_dentro_estado"`, `"saida_fora_estado"`, `"padrao"`)
tipo_pessoa *	string	`"fisica"` ou `"juridica"`
codigo_cfop *	string	CFOP
situacao_tributaria *	string	CST/CSOSN do ICMS
nao_contribuinte	boolean	Cliente não-contribuinte
aliquota_importacao	string	Alíquota de importação
aliquota_credito	decimal	Alíquota de crédito (% para Simples Nacional)
aliquota_diferimento	decimal	Percentual de diferimento (não retornado pelo `get_detail`)
aliquota_diferimentoFcp	string	Diferimento do FCP (atenção: campo usa camelCase `diferimentoFcp`; não retornado pelo `get_detail`)
aliquota_reducao	decimal	Percentual de redução de base ICMS
aliquota_reducaoSt	decimal	Percentual de redução de base ICMS-ST (atenção: `reducaoSt` camelCase)
motivo_desoneracao	string	Código do motivo da desoneração ICMS
motivo_desoneracaoSt	string	Código do motivo da desoneração ICMS-ST (atenção: camelCase)
ad_rem_icms	decimal	ICMS monofásico — alíquota ad rem em R$/unidade (CST 02, 15, 53)
ad_rem_icms_ret	decimal	ICMS monofásico — ad rem retido em R$/unidade (CST 15, 61)
p_dif_mono	decimal	ICMS monofásico — percentual de diferimento (CST 53)
q_bc_mono	decimal	ICMS monofásico — quantidade tributada (litros/kg); 0 usa a quantidade do item (CST 02, 15, 53)
valor_desoneracao	decimal	Valor do ICMS desonerado em R$ — emite vICMSDeson (CST 40, 41, 50, 90)
v_bc_st_ret	decimal	Base de cálculo do ICMS-ST retido na operação anterior (informado, não calculado — CST 60, CSOSN 500)
p_st	decimal	Alíquota suportada pelo consumidor final em % (informado, não calculado — CST 60, CSOSN 500)
v_icms_st_ret	decimal	Valor do ICMS-ST retido na operação anterior (informado, não calculado — CST 60, CSOSN 500)
v_icms_substituto	decimal	Valor do ICMS próprio do substituto (informado, não calculado — CST 60, CSOSN 500)
v_bc_fcp_st_ret	decimal	Base de cálculo do FCP retido por ST (informado, não calculado — CST 60, CSOSN 500)
p_fcp_st_ret	decimal	Alíquota do FCP retido por ST em % (informado, não calculado — CST 60, CSOSN 500)
v_fcp_st_ret	decimal	Valor do FCP retido por ST (informado, não calculado — CST 60, CSOSN 500)
Alíquotas por estado — opcional
aliquota_mva[]	array	MVA por UF — itens: `{ estado, aliquota }`
aliquota_icms[]	array	Alíquota ICMS por UF — itens: `{ estado, aliquota }`
aliquota_icms_st[]	array	Alíquota ICMS-ST por UF — itens: `{ estado, aliquota }`
aliquota_fcp[]	array	Alíquota FCP por UF — itens: `{ estado, aliquota }`
aliquota_fcp_st[]	array	Alíquota FCP-ST por UF — itens: `{ estado, aliquota }`
beneficio_fiscal[]	array	Código de benefício fiscal por UF — itens: `{ estado, codigo }`

Body — `ipi[]`

Campo	Tipo	Descrição
cenario *	string	Cenário
tipo_pessoa *	string	`"fisica"` ou `"juridica"`
situacao_tributaria *	string	CST IPI
codigo_enquadramento *	string	Código de enquadramento legal
aliquota *	string	Alíquota IPI
valor_unidade	string	IPI por quantidade — valor em R$/unidade; só usado quando não há alíquota percentual (CST 00, 50, 49, 99)

Body — `pis[]` e `cofins[]` (mesma estrutura)

Campo	Tipo	Descrição
cenario *	string	Cenário
tipo_pessoa *	string	`"fisica"` ou `"juridica"`
situacao_tributaria *	string	CST PIS/COFINS
aliquota *	string	Alíquota
valor_unidade	string	PIS/COFINS por quantidade — valor em R$/unidade; v = quantidade × valor (CST 03 e demais formas por quantidade)

Body — `ibs_cbs[]` (Reforma Tributária)

Campo	Tipo	Descrição
cenario *	string	Cenário
tipo_pessoa *	string	`"fisica"` ou `"juridica"`
situacao_tributaria *	string	CST IBS/CBS
classificacao_tributaria *	string	Classificação tributária
p_ibs_uf	string	Alíquota do IBS UF em % (opcional; vazio usa o padrão da transição, 0,10 em 2026). Aceita ponto ou vírgula
p_ibs_mun	string	Alíquota do IBS Município em % (opcional; padrão 0 em 2026)
p_cbs	string	Alíquota da CBS em % (opcional; padrão 0,90 em 2026)
p_red_aliq	string	Percentual de redução de alíquota (CST 011, 200, 515)
p_dif	string	Percentual de diferimento (CST 510, 515)
p_red_bc	string	Percentual de redução da base de cálculo (CST 222)
proporcao	string	Proporção da operação em % (CST 221)
aliquota_cbs_mono	string	CBS monofásica — alíquota em % sobre a base; prevalece sobre `valor_unidade_cbs` (CST 620)
aliquota_ibs_mono	string	IBS monofásico — alíquota em % sobre a base; prevalece sobre `valor_unidade_ibs` (CST 620)
valor_unidade_cbs	string	CBS monofásica — ad rem em R$/unidade; só usado quando não há alíquota percentual (CST 620)
valor_unidade_ibs	string	IBS monofásico — ad rem em R$/unidade; só usado quando não há alíquota percentual (CST 620)
valor_deducao_legal	string	Valor da dedução legal da base em R$ (CST 830)

Body — `is[]` (Imposto Seletivo)

Campo	Tipo	Descrição
cenario *	string	Cenário
tipo_pessoa *	string	`"fisica"` ou `"juridica"`
situacao_tributaria *	string	CST IS
aliquota *	string	Alíquota IS

* Campo obrigatório.

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os 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

Detalhes da categoria fiscal

Retorna a configuração completa de uma categoria fiscal: todos os cenários de ICMS, IPI, PIS, COFINS, IBS/CBS, incluindo arrays por UF (MVA, alíquotas, benefícios fiscais).

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa
sign	string	Assinatura MD5 (path inclui a query string)
timestamp	string	Unix timestamp em segundos

Query string

Parâmetro	Tipo	Descrição
category_id *	string	ID da categoria fiscal

* Campo obrigatório.

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os 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

Listar categorias fiscais

Lista as categorias fiscais da empresa autenticada com paginação. Retorna category_id, descricao e o bloco ibs_cbs (Reforma Tributária) de cada categoria — use /api/category/get_detail para os demais impostos.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa
sign	string	Assinatura MD5 (path inclui a query string)
timestamp	string	Unix timestamp em segundos

Query string

Parâmetro	Tipo	Descrição
page *	int	Número da página (≥ 1)
page_size *	int	Tamanho da página (1–50)

* Campo obrigatório.

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os 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

Editar categoria fiscal

Edita uma categoria fiscal existente. O corpo é idêntico ao de /api/category/create, com a única diferença de que category_id é obrigatório e deve corresponder a uma categoria existente. O upsert substitui completamente os arrays icms, ipi, pis, cofins, ibs_cbs, is — envie todos os cenários atualizados (não há merge por cenário).

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa
sign	string	Assinatura MD5
timestamp	string	Unix timestamp em segundos

Body

A estrutura completa do body está documentada em /api/category/create. Aqui só o category_id tem tratamento diferente:

Campo	Tipo	Descrição
category_id *	string	ID da categoria a editar (deve existir; caso contrário retorna erro)
descricao *	string	Descrição
icms[] *	array	Cenários ICMS (substitui completamente)
ipi[] *	array	Cenários IPI
pis[] *	array	Cenários PIS
cofins[] *	array	Cenários COFINS
ibs_cbs[]	array	Cenários IBS/CBS (opcional)
is[]	array	Cenários IS (opcional)
disable_difal	boolean	Default: `false`
desconta_icms_pis_cofins	boolean	Abate o ICMS antes de calcular PIS/COFINS — tributa (valor − ICMS), padrão atual no Brasil; default false (sem abatimento, imposto maior)

* Campo obrigatório. Para os campos internos de cada array (icms[].codigo_cfop etc.), veja /api/category/create.

POST/api/category/delete

Excluir categoria fiscal

Remove uma categoria fiscal da empresa. Operação irreversível. Produtos que estavam vinculados a esta categoria continuarão referenciando o category_id removido, então a emissão de NFe vai falhar — atualize os produtos antes de excluir.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa
sign	string	Assinatura MD5
timestamp	string	Unix timestamp em segundos

Body

Campo	Tipo	Descrição
category_id *	string	ID da categoria a excluir

* Campo obrigatório.

Criar categoria fiscal

Headers obrigatórios

Body — top-level

Body — icms[]

Body — ipi[]

Body — pis[] e cofins[] (mesma estrutura)

Body — ibs_cbs[] (Reforma Tributária)

Body — is[] (Imposto Seletivo)

Detalhes da categoria fiscal

Headers obrigatórios

Query string

Listar categorias fiscais

Headers obrigatórios

Query string

Editar categoria fiscal

Headers obrigatórios

Body

Excluir categoria fiscal

Headers obrigatórios

Body

Body — `icms[]`

Body — `ipi[]`

Body — `pis[]` e `cofins[]` (mesma estrutura)

Body — `ibs_cbs[]` (Reforma Tributária)

Body — `is[]` (Imposto Seletivo)