Categorías fiscales NF-e · TF Fiscal API

POST/api/category/create

Crear categoría fiscal

Crea una nueva categoría fiscal (plantilla de impuestos) vinculada a la empresa autenticada. Cada categoría agrega escenarios de ICMS, IPI, PIS, COFINS, y opcionalmente IBS/CBS e IS. Para editar una existente, use /api/category/edit.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body — nivel superior

Campo	Tipo	Descripción
descricao *	string	Descripción de la categoría fiscal
category_id	string	ID personalizado. Si se omite, se genera automáticamente como `"TF"` + número incremental
disable_difal	boolean	Desactiva el cálculo de DIFAL para esta categoría. Default: `false`
desconta_icms_pis_cofins	boolean	Descuenta el ICMS antes de calcular PIS/COFINS — tributa (importe − ICMS), estándar actual en Brasil; por defecto false (sin descuento, impuesto mayor)
icms[] *	array	Escenarios ICMS (estructura abajo)
ipi[] *	array	Escenarios IPI (estructura abajo)
pis[] *	array	Escenarios PIS (estructura abajo)
cofins[] *	array	Escenarios COFINS (estructura abajo)
ibs_cbs[]	array	Escenarios IBS/CBS — reforma tributaria (estructura abajo)
is[]	array	Escenarios IS — Impuesto Selectivo (estructura abajo)

Body — `icms[]`

Campo	Tipo	Descripción
tipo_tributacao *	string	Tipo de tributación ICMS
cenario *	string	Escenario (ej.: `"saida_dentro_estado"`, `"saida_fora_estado"`, `"padrao"`)
tipo_pessoa *	string	`"fisica"` o `"juridica"`
codigo_cfop *	string	CFOP
situacao_tributaria *	string	CST/CSOSN del ICMS
nao_contribuinte	boolean	Cliente no-contribuyente
aliquota_importacao	string	Alícuota de importación
aliquota_credito	decimal	Alícuota de crédito (% para Simples Nacional)
aliquota_diferimento	decimal	Porcentaje de diferimiento (no se devuelve en `get_detail`)
aliquota_diferimentoFcp	string	Diferimiento de FCP (atención: el campo usa camelCase `diferimentoFcp`; no se devuelve en `get_detail`)
aliquota_reducao	decimal	Porcentaje de reducción de base ICMS
aliquota_reducaoSt	decimal	Porcentaje de reducción de base ICMS-ST (atención: `reducaoSt` camelCase)
motivo_desoneracao	string	Código del motivo de exoneración ICMS
motivo_desoneracaoSt	string	Código del motivo de exoneración ICMS-ST (atención: camelCase)
ad_rem_icms	decimal	ICMS monofásico — alícuota ad rem en R$/unidad (CST 02, 15, 53)
ad_rem_icms_ret	decimal	ICMS monofásico — ad rem retenido en R$/unidad (CST 15, 61)
p_dif_mono	decimal	ICMS monofásico — porcentaje de diferimiento (CST 53)
q_bc_mono	decimal	ICMS monofásico — cantidad tributada (litros/kg); 0 usa la cantidad del ítem (CST 02, 15, 53)
valor_desoneracao	decimal	Valor del ICMS exonerado en BRL — emite vICMSDeson (CST 40, 41, 50, 90)
v_bc_st_ret	decimal	Base de cálculo del ICMS-ST retenido en la operación anterior (informado, no calculado — CST 60, CSOSN 500)
p_st	decimal	Alícuota soportada por el consumidor final en % (informado, no calculado — CST 60, CSOSN 500)
v_icms_st_ret	decimal	Valor del ICMS-ST retenido en la operación anterior (informado, no calculado — CST 60, CSOSN 500)
v_icms_substituto	decimal	Valor del ICMS propio del sustituto (informado, no calculado — CST 60, CSOSN 500)
v_bc_fcp_st_ret	decimal	Base de cálculo del FCP retenido por ST (informado, no calculado — CST 60, CSOSN 500)
p_fcp_st_ret	decimal	Alícuota del FCP retenido por ST en % (informado, no calculado — CST 60, CSOSN 500)
v_fcp_st_ret	decimal	Valor del FCP retenido por ST (informado, no calculado — CST 60, CSOSN 500)
Alícuotas por estado — opcional
aliquota_mva[]	array	MVA por UF — ítems: `{ estado, aliquota }`
aliquota_icms[]	array	Alícuota ICMS por UF — ítems: `{ estado, aliquota }`
aliquota_icms_st[]	array	Alícuota ICMS-ST por UF — ítems: `{ estado, aliquota }`
aliquota_fcp[]	array	Alícuota FCP por UF — ítems: `{ estado, aliquota }`
aliquota_fcp_st[]	array	Alícuota FCP-ST por UF — ítems: `{ estado, aliquota }`
beneficio_fiscal[]	array	Código de beneficio fiscal por UF — ítems: `{ estado, codigo }`

Body — `ipi[]`

Campo	Tipo	Descripción
cenario *	string	Escenario
tipo_pessoa *	string	`"fisica"` o `"juridica"`
situacao_tributaria *	string	CST IPI
codigo_enquadramento *	string	Código de encuadre legal
aliquota *	string	Alícuota IPI
valor_unidade	string	IPI por cantidad — valor en R$/unidad; solo se usa cuando no hay alícuota porcentual (CST 00, 50, 49, 99)

Body — `pis[]` y `cofins[]` (misma estructura)

Campo	Tipo	Descripción
cenario *	string	Escenario
tipo_pessoa *	string	`"fisica"` o `"juridica"`
situacao_tributaria *	string	CST PIS/COFINS
aliquota *	string	Alícuota
valor_unidade	string	PIS/COFINS por cantidad — valor en R$/unidad; v = cantidad × valor (CST 03 y demás formas por cantidad)

Body — `ibs_cbs[]` (Reforma Tributaria)

Campo	Tipo	Descripción
cenario *	string	Escenario
tipo_pessoa *	string	`"fisica"` o `"juridica"`
situacao_tributaria *	string	CST IBS/CBS
classificacao_tributaria *	string	Clasificación tributaria
p_ibs_uf	string	Alícuota del IBS estatal en % (opcional; vacío usa el valor por defecto de transición, 0,10 en 2026). Acepta punto o coma
p_ibs_mun	string	Alícuota del IBS municipal en % (opcional; por defecto 0 en 2026)
p_cbs	string	Alícuota de la CBS en % (opcional; por defecto 0,90 en 2026)
p_red_aliq	string	Porcentaje de reducción de alícuota (CST 011, 200, 515)
p_dif	string	Porcentaje de diferimiento (CST 510, 515)
p_red_bc	string	Porcentaje de reducción de la base de cálculo (CST 222)
proporcao	string	Proporción de la operación en % (CST 221)
aliquota_cbs_mono	string	CBS monofásica — alícuota en % sobre la base; prevalece sobre `valor_unidade_cbs` (CST 620)
aliquota_ibs_mono	string	IBS monofásico — alícuota en % sobre la base; prevalece sobre `valor_unidade_ibs` (CST 620)
valor_unidade_cbs	string	CBS monofásica — ad rem en R$/unidad; solo se usa cuando no hay alícuota porcentual (CST 620)
valor_unidade_ibs	string	IBS monofásico — ad rem en R$/unidad; solo se usa cuando no hay alícuota porcentual (CST 620)
valor_deducao_legal	string	Valor de la deducción legal de la base en R$ (CST 830)

Body — `is[]` (Impuesto Selectivo)

Campo	Tipo	Descripción
cenario *	string	Escenario
tipo_pessoa *	string	`"fisica"` o `"juridica"`
situacao_tributaria *	string	CST IS
aliquota *	string	Alícuota IS

* Campo obligatorio.

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los 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

Detalles de la categoría fiscal

Devuelve la configuración completa de una categoría fiscal: todos los escenarios de ICMS, IPI, PIS, COFINS, IBS/CBS, incluidas las matrices por UF (MVA, alícuotas, beneficios fiscales).

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa
sign	string	Firma MD5 (path incluye la query string)
timestamp	string	Unix timestamp en segundos

Query string

Parámetro	Tipo	Descripción
category_id *	string	ID de la categoría fiscal

* Campo obligatorio.

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los 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 categorías fiscales

Lista las categorías fiscales de la empresa autenticada con paginación. Devuelve category_id, descricao y el bloque ibs_cbs (Reforma Tributaria) de cada categoría — para los demás impuestos use /api/category/get_detail.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa
sign	string	Firma MD5 (path incluye la query string)
timestamp	string	Unix timestamp en segundos

Query string

Parámetro	Tipo	Descripción
page *	int	Número de página (≥ 1)
page_size *	int	Tamaño de página (1–50)

* Campo obligatorio.

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los 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 categoría fiscal

Edita una categoría fiscal existente. El cuerpo es idéntico al de /api/category/create, con la única diferencia de que category_id es obligatorio y debe corresponder a una categoría existente. El upsert reemplaza completamente las matrices icms, ipi, pis, cofins, ibs_cbs, is — envíe todos los escenarios actualizados (no hay merge por escenario).

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

La estructura completa del body está documentada en /api/category/create. Solo category_id tiene un tratamiento diferente aquí:

Campo	Tipo	Descripción
category_id *	string	ID de la categoría a editar (debe existir; en caso contrario devuelve error)
descricao *	string	Descripción
icms[] *	array	Escenarios ICMS (reemplaza completamente)
ipi[] *	array	Escenarios IPI
pis[] *	array	Escenarios PIS
cofins[] *	array	Escenarios COFINS
ibs_cbs[]	array	Escenarios IBS/CBS (opcional)
is[]	array	Escenarios IS (opcional)
disable_difal	boolean	Default: `false`
desconta_icms_pis_cofins	boolean	Descuenta el ICMS antes de calcular PIS/COFINS — tributa (importe − ICMS), estándar actual en Brasil; por defecto false (sin descuento, impuesto mayor)

* Campo obligatorio. Para los campos internos de cada array (icms[].codigo_cfop etc.), vea /api/category/create.

POST/api/category/delete

Eliminar categoría fiscal

Elimina una categoría fiscal de la empresa. Operación irreversible. Los productos vinculados a esta categoría seguirán referenciando el category_id eliminado, por lo que la emisión de NFe fallará — actualice los productos antes de eliminar.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
category_id *	string	ID de la categoría a eliminar

* Campo obligatorio.

Crear categoría fiscal

Headers obligatorios

Body — nivel superior

Body — icms[]

Body — ipi[]

Body — pis[] y cofins[] (misma estructura)

Body — ibs_cbs[] (Reforma Tributaria)

Body — is[] (Impuesto Selectivo)

Detalles de la categoría fiscal

Headers obligatorios

Query string

Listar categorías fiscales

Headers obligatorios

Query string

Editar categoría fiscal

Headers obligatorios

Body

Eliminar categoría fiscal

Headers obligatorios

Body

Body — `icms[]`

Body — `ipi[]`

Body — `pis[]` y `cofins[]` (misma estructura)

Body — `ibs_cbs[]` (Reforma Tributaria)

Body — `is[]` (Impuesto Selectivo)