NF-e 税种

创建一个绑定到已认证公司的新税务类别（税务模板）。每个类别聚合 ICMS、IPI、PIS、COFINS 场景，并可选包含 IBS/CBS 和 IS。要编辑现有类别，请使用 /api/category/edit。

必需请求头

请求头	类型	说明
token	string	公司令牌
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

Body — 顶层

字段	类型	说明
descricao *	string	类别说明
category_id	string	自定义 ID。省略时自动生成为 "TF" + 递增数字
disable_difal	boolean	禁用此类别的 DIFAL 计算。默认值：false
desconta_icms_pis_cofins	boolean	算 PIS/COFINS 前先减去 ICMS，按（金额 − ICMS）计税（巴西现行标准）；默认 false 不减，税额会偏高
icms[] *	array	ICMS 场景（结构见下）
ipi[] *	array	IPI 场景（结构见下）
pis[] *	array	PIS 场景（结构见下）
cofins[] *	array	COFINS 场景（结构见下）
ibs_cbs[]	array	IBS/CBS 场景 — 税制改革（结构见下）
is[]	array	IS 场景 — 选择税（结构见下）

Body — icms[]

字段	类型	说明
tipo_tributacao *	string	ICMS 课税类型
cenario *	string	场景（例如："saida_dentro_estado"、"saida_fora_estado"、"padrao"）
tipo_pessoa *	string	"fisica" 或 "juridica"
codigo_cfop *	string	CFOP
situacao_tributaria *	string	ICMS 的 CST/CSOSN
nao_contribuinte	boolean	非纳税客户
aliquota_importacao	string	进口税率
aliquota_credito	decimal	信用税率（Simples Nacional 用百分比）
aliquota_diferimento	decimal	递延百分比（get_detail 不返回该字段）
aliquota_diferimentoFcp	string	FCP 递延（注意：字段使用 camelCase diferimentoFcp；get_detail 不返回该字段）
aliquota_reducao	decimal	ICMS 基础减免百分比
aliquota_reducaoSt	decimal	ICMS-ST 基础减免百分比（注意：reducaoSt camelCase）
motivo_desoneracao	string	ICMS 免税理由代码
motivo_desoneracaoSt	string	ICMS-ST 免税理由代码（注意：camelCase）
ad_rem_icms	decimal	ICMS 单一环节 — 从量税率（雷亚尔/单位）（CST 02、15、53）
ad_rem_icms_ret	decimal	ICMS 单一环节 — 代扣从量税（雷亚尔/单位）（CST 15、61）
p_dif_mono	decimal	ICMS 单一环节 — 递延百分比（CST 53）
q_bc_mono	decimal	ICMS 单一环节 — 计税数量（升/千克）；0 则使用项目数量（CST 02、15、53）
valor_desoneracao	decimal	ICMS 免征金额（雷亚尔）— 输出 vICMSDeson（CST 40、41、50、90）
v_bc_st_ret	decimal	上一环节已代扣 ICMS-ST 的计税基础（由调用方提供，不由系统计算 — CST 60、CSOSN 500）
p_st	decimal	最终消费者承担的税率（%）（由调用方提供，不由系统计算 — CST 60、CSOSN 500）
v_icms_st_ret	decimal	上一环节已代扣的 ICMS-ST 金额（由调用方提供，不由系统计算 — CST 60、CSOSN 500）
v_icms_substituto	decimal	替代纳税人自身的 ICMS 金额（由调用方提供，不由系统计算 — CST 60、CSOSN 500）
v_bc_fcp_st_ret	decimal	按 ST 代扣 FCP 的计税基础（由调用方提供，不由系统计算 — CST 60、CSOSN 500）
p_fcp_st_ret	decimal	按 ST 代扣的 FCP 税率（%）（由调用方提供，不由系统计算 — CST 60、CSOSN 500）
v_fcp_st_ret	decimal	按 ST 代扣的 FCP 金额（由调用方提供，不由系统计算 — CST 60、CSOSN 500）
按州税率 — 可选
aliquota_mva[]	array	按 UF 的 MVA — 项：{ estado, aliquota }
aliquota_icms[]	array	按 UF 的 ICMS 税率 — 项：{ estado, aliquota }
aliquota_icms_st[]	array	按 UF 的 ICMS-ST 税率 — 项：{ estado, aliquota }
aliquota_fcp[]	array	按 UF 的 FCP 税率 — 项：{ estado, aliquota }
aliquota_fcp_st[]	array	按 UF 的 FCP-ST 税率 — 项：{ estado, aliquota }
beneficio_fiscal[]	array	按 UF 的税收优惠代码 — 项：{ estado, codigo }

Body — ipi[]

字段	类型	说明
cenario *	string	场景
tipo_pessoa *	string	"fisica" 或 "juridica"
situacao_tributaria *	string	IPI 的 CST
codigo_enquadramento *	string	法律分类代码
aliquota *	string	IPI 税率
valor_unidade	string	IPI 按数量计税 — 单价（雷亚尔/单位）；仅在没有百分比税率时使用（CST 00、50、49、99）

Body — pis[] 和 cofins[]（相同结构）

字段	类型	说明
cenario *	string	场景
tipo_pessoa *	string	"fisica" 或 "juridica"
situacao_tributaria *	string	PIS/COFINS 的 CST
aliquota *	string	税率
valor_unidade	string	PIS/COFINS 按数量计税 — 单价（雷亚尔/单位）；v = 数量 × 单价（CST 03 及其他按数量计税方式）

Body — ibs_cbs[]（税制改革）

字段	类型	说明
cenario *	string	场景
tipo_pessoa *	string	"fisica" 或 "juridica"
situacao_tributaria *	string	IBS/CBS 的 CST
classificacao_tributaria *	string	税务分类
p_ibs_uf	string	IBS州税率（%）（可选；留空则使用过渡期默认值0.10（2026年））。支持点或逗号
p_ibs_mun	string	IBS市级税率（%）（可选；2026年默认0）
p_cbs	string	CBS税率（%）（可选；2026年默认0.90）
p_red_aliq	string	税率减免百分比（CST 011、200、515）
p_dif	string	递延百分比（CST 510、515）
p_red_bc	string	计税基础减免百分比（CST 222）
proporcao	string	操作比例（%）（CST 221）
aliquota_cbs_mono	string	CBS 单一环节 — 按计税基础的百分比税率；优先于 valor_unidade_cbs（CST 620）
aliquota_ibs_mono	string	IBS 单一环节 — 按计税基础的百分比税率；优先于 valor_unidade_ibs（CST 620）
valor_unidade_cbs	string	CBS 单一环节 — 从量金额（雷亚尔/单位）；仅在没有百分比税率时使用（CST 620）
valor_unidade_ibs	string	IBS 单一环节 — 从量金额（雷亚尔/单位）；仅在没有百分比税率时使用（CST 620）
valor_deducao_legal	string	计税基础的法定扣除额（雷亚尔）（CST 830）

Body — is[]（选择税）

字段	类型	说明
cenario *	string	场景
tipo_pessoa *	string	"fisica" 或 "juridica"
situacao_tributaria *	string	IS 的 CST
aliquota *	string	IS 税率

* 必填字段。

返回税务类别的完整配置：所有 ICMS、IPI、PIS、COFINS、IBS/CBS 场景，包括按 UF 的数组（MVA、税率、税收优惠）。

必需请求头

请求头	类型	说明
token	string	公司令牌
sign	string	MD5 签名（path 包含查询字符串）
timestamp	string	秒级 Unix 时间戳

查询字符串

参数	类型	说明
category_id *	string	税务类别 ID

* 必填字段。

分页列出已认证公司的税务类别。每项返回 category_id、descricao 以及每个类别的 ibs_cbs 块（税制改革）— 其他税种请使用 /api/category/get_detail 获取完整配置。

必需请求头

请求头	类型	说明
token	string	公司令牌
sign	string	MD5 签名（path 包含查询字符串）
timestamp	string	秒级 Unix 时间戳

查询字符串

参数	类型	说明
page *	int	页码（≥ 1）
page_size *	int	每页大小（1–50）

* 必填字段。

编辑现有的税务类别。请求体与 /api/category/create 相同，唯一区别是 category_id 必填且必须与现有类别匹配。Upsert 完全替换 icms、ipi、pis、cofins、ibs_cbs、is 数组 — 请发送所有更新后的场景（不会按场景合并）。

必需请求头

请求头	类型	说明
token	string	公司令牌
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

Body

完整的 body 结构记录在 /api/category/create。此处仅 category_id 处理不同：

字段	类型	说明
category_id *	string	要编辑的类别 ID（必须存在，否则返回错误）
descricao *	string	说明
icms[] *	array	ICMS 场景（完全替换）
ipi[] *	array	IPI 场景
pis[] *	array	PIS 场景
cofins[] *	array	COFINS 场景
ibs_cbs[]	array	IBS/CBS 场景（可选）
is[]	array	IS 场景（可选）
disable_difal	boolean	默认值：false
desconta_icms_pis_cofins	boolean	算 PIS/COFINS 前先减去 ICMS，按（金额 − ICMS）计税（巴西现行标准）；默认 false 不减，税额会偏高

* 必填字段。每个数组的内部字段（icms[].codigo_cfop 等），请参见 /api/category/create。

从公司中删除税务类别。不可逆的操作。绑定到此类别的产品仍会引用已删除的 category_id，因此 NFe 开票将失败 — 删除前请先更新产品。

必需请求头

请求头	类型	说明
token	string	公司令牌
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

Body

字段	类型	说明
category_id *	string	要删除的类别 ID

* 必填字段。