TF Fiscal
开发文档

税种

税种:把 NF-e / NFC-e 商品行税务参数按场景分行存成税种,平台生成编号,开票时商品行只传编号;税种类型、场景表、选行顺序、选不到时的错误、CFOP 带出与覆盖、整组覆盖、保存规则、税制变更与状态、版本与幂等、错误码。

能力概述

税种是挂在开票主体下的一套商品行税务参数,例如「转售商品-SP」。和只存一套参数不同,税种的每个组都是若干行,一行对应一个场景:州内卖给企业一行、跨州卖给个人一行……开票时平台按本票的场景、客户类型、买方是否纳税人,从每个组选出适用的那一行。

步骤接口说明
1 创建POST .../classes-imposto平台生成编号并在响应返回;选定类型 NFe 或 NFCe;保存时按主体税制校验每一行
2 开票引用NF-e 开票 · NFC-e 开票商品行 classeImposto 填该编号,cfop 与 impostos 可不传;发票助手与内置 SDK 开票引用税种须联网,见税种与联网
维护列表 · 详情 · 更新 · 删除列表可按 tipo、situacao 筛选;更新为整份替换

路径都在 /openapi/v2/empresas/{empresaId}/ 下,鉴权与其他开放接口相同,见认证与签名。

税种编号由平台生成:TF 加 10 位数字,前 9 位随机、最后 1 位是校验位,例如 TF4440123455。编号全平台唯一,删除后也不复用。创建与整份替换的请求体都不传 codigo,传了返回 10005208;详情、整份替换、删除都按路径里的编号定位。应用要订阅「税种管理」「税种详情与更新」「税种删除」三项,否则返回 403。

税种类型

每个税种在创建时选定 tipo,之后不能改(10005216)。开票只认本类型:NF-e 只能引用 NFe 税种,NFC-e 只能引用 NFCe 税种,否则返回 10005215。

规则NFeNFCe
可用的组icms、ipi、pis、cofins、ibsCbs;不能有 issqnicms、issqn、pis、cofins、ibsCbs;不能有 ipi
可用的场景全部七个只有 SaidaDentroEstado 与 Padrao
行字段NF-e 开票同名组的全部字段只能用 NFC-e 开票有的字段:ICMS 行不能带 substituicaoTributaria、difal、partilha、percentualCreditoSimples、递延等;PIS / COFINS 行只有 situacaoTributaria 与 aliquota
违反时带 issqn 返回 10005218带 ipi 返回 10005218,场景不符返回 10005219,字段不支持返回 10005217 并点名路径

零售与批发税务差异大,同一业务两种票都开时,各建一个税种。

组与行

组每行的字段行数要求
icms场景维度 + cfop + NF-e 开票 itens[].impostos.icms 的字段与 issqn 合计至少 1 行
issqn场景维度 + cfop + NFC-e 开票 impostos.issqn 的全部字段;只用于 NFCe与 icms 合计至少 1 行
pis / cofins场景维度 + 开票同名组的字段各至少 1 行
ipi场景维度 + NF-e 开票 ipi 组的字段;只用于 NFe可不传
ibsCbs场景维度 + 开票同名组的字段可不传

场景维度有三个字段:

  • cenario 场景,必填,取值见下表。
  • tipoPessoa 客户类型:Fisica 个人、Juridica 企业、Estrangeiro 国外买方;不填即不区分。
  • naoContribuinte 买方是否非纳税人:true 只用于非 ICMS 纳税人买方,false 只用于纳税人或免登记买方;不填即不区分。

同一组内三者的组合不得重复(10005211),所以任何一张票在一个组里最多只有一行完全匹配。每组最多 50 行。

行里的 tipoPessoa 与 NF-e 开票请求的 cliente.tipoPessoa 是两个字段:后者仍取 F / J,描述买方;前者取 Fisica / Juridica / Estrangeiro,描述这一行适用于哪类客户,开票时由买方 CPF、CNPJ 或国外买方推导后与之比对。

CRT、Simples 归属、环境、序列号永远取主体档案,税种里没有这些字段。CEST、商品原产地 origem 属于商品行,照常在 itens[] 上传。

场景

cenario含义本票何时属于该场景会匹配到的客户类型cfop 首位
SaidaDentroEstado州内出库销售等出库票,买方与开票主体同州;NFC-e 固定为此场景Fisica、Juridica5
SaidaForaEstado跨州出库出库票,买方在别的州Fisica、Juridica6
SaidaExterior出口出库票,买方在国外Estrangeiro7
EntradaDentroEstado州内入库退货票,对方与开票主体同州Fisica、Juridica1
EntradaForaEstado跨州入库退货票,对方在别的州Fisica、Juridica2
EntradaExterior国外入库退货票,对方在国外Estrangeiro3
Padrao通用任何票;只在本场景没有可用行时才用。ICMS 不适用任意不限

cfop 首位与场景不符返回 10005212。ISSQN 行的 cfop 固定 5933(Padrao 行也一样),ICMS 行不能用 5933,违反返回 10005214。PIS、COFINS 这类各场景都一样的组,写一行 Padrao 即可。

开票时如何选行

平台先从票面推导三个值:

维度NF-e 的推导NFC-e
场景退货票为入库,其余为出库;买方与开票主体同州为州内,别的州为跨州,国外买方(cliente.idEstrangeiro、endereco.uf 为 EX)为国外固定 SaidaDentroEstado
客户类型买方传 CPF 为 Fisica,CNPJ 为 Juridica,国外买方为 Estrangeiro同左;未识别买方按 Fisica
是否非纳税人买方 ICMS 身份为 NaoContribuinte(含不传时平台推导的结果)为 true固定 true

然后每个组按下面的顺序取第一条命中的行:

顺序命中的行
1场景相同,tipoPessoa 与 naoContribuinte 都填了且都与本票一致
2场景相同,tipoPessoa 一致,naoContribuinte 不填
3场景相同,tipoPessoa 不填,naoContribuinte 一致
4场景相同,两者都不填
5Padrao 行,按 1 到 4 同样的顺序;ICMS 没有这一步

填了却与本票不同的维度一律不命中。例如一行写了 "tipoPessoa": "Juridica",卖给个人时这行不会被选中,哪怕它是唯一的州内行。

选不到行时

组选不到时
ICMS(服务行为 ISSQN)、PIS、COFINS拒绝开票,返回 10005209;消息写明税种、组、场景、客户类型与是否非纳税人
IPI、IBS/CBS本行不带该组

处理办法是给税种补一行,或在请求里直传该组。

CFOP 由税种带出

商品行没传 cfop 时,取选中 ICMS 行的 cfop;取 ISSQN 行时用它的 5933。传了 cfop 以请求为准。所以同一个商品在州内、跨州开票时,商品行可以完全不变,CFOP 由场景带出 5102 或 6102。

请求直传与整组覆盖

商品行的 impostos 里传了哪一组,就整组用请求的,税种不再为该组选行;没传的组照常从税种选行。组内字段不逐项拼接:税种选出的 ICMS 行是 CST 20 带减基比例,请求把 ICMS 换成 CST 00,结果就是请求的 CST 00 整组,不会残留减基比例。

json
{
"codigo": "SKU-1",
"classeImposto": "TF4440123455",
"cfop": "6102",
"impostos": { "icms": { "situacaoTributaria": "00", "aliquota": 12 } }
}

上例 ICMS 用请求的 00 / 12%,PIS、COFINS、IBS/CBS 由税种选行。直传了 icms(或 issqn)就没有可带出 CFOP 的行,cfop 必须在请求里传,否则返回 10001002。

ICMS 与 ISSQN 两组联动,每个商品行只取其中一组:

情况取用
请求的 impostos 传了 icms 或 issqn用请求的那一组,税种的 ICMS、ISSQN 行都不取
请求传了 cfop 5933(NFC-e 服务行)税种的 ISSQN 行
请求传了其他 cfop税种的 ICMS 行
请求没传 cfop税种 icms 组有行就只在 ICMS 行里选,选不到返回 10005209;icms 组为空时才取 ISSQN 行。NF-e 只有 ICMS

取值顺序:请求直传 > 税种 > 主体档案 > 平台税率表(只对 CRT 3 生效)> 拒绝开票并点名字段。ICMS 行不填 aliquota 与 FCP 时按平台税率表。税负比例 percentualCargaTributaria 不在税种里:只能在请求的 impostos 里直传,不传按 IBPT 表算。

按州配置、减免与推定抵免

ICMS 行除了开票同名字段(含减免原因 motivoDesoneracao、ST 减免原因 motivoDesoneracaoSt、是否扣减 deduzDesonerado、减基优惠码 codigoBeneficioFiscalReducaoBase、推定抵免 creditosPresumidos),还可以按州配置:

字段按哪个州选开票时
icms[].beneficiosFiscaisPorEstado开票方所在州有该州的行就替代行内 codigoBeneficioFiscal,没有就用行内值
icms[].creditosPresumidosPorEstado开票方所在州有该州的行(每州最多 4 组)就替代行内 creditosPresumidos,没有就用行内值
icmsPorEstado(税种顶层,仅 NFe)买方所在州有该州的行就用它的 aliquota、substituicaoTributaria.aliquota、substituicaoTributaria.mva 替代选中 ICMS 行的对应值;没配的项沿用行内值,行内也没有按平台税率表

优惠码与推定抵免代码出自开票方所在州的码表,所以按开票方所在州选;ST 税率与 MVA 随目的州,所以按买方所在州选。按州 ICMS 税率只套用到 CST 00、10、20、30、51、70、90 与 CSOSN 201、202、203、900 的行,按州 ST 参数只套用到 CST 10、30、70、90 与 CSOSN 201、202、203、900 的行。请求直传 icms 组时整组用请求的,按州配置都不生效。

减免金额、ST 减免金额、推定抵免金额是按票的金额,税种里不能配(10005231),不传时平台按税码计算,规则见 NF-e 开票。平台算不出金额的组合,税种保存时即拒 10005235:ST 减免原因 motivoDesoneracaoSt 须同时配 ST 减基比例 substituicaoTributaria.percentualReducaoBase,平台按「不减基的 ST − 减基后的 ST」算减免金额;CST 90 的减免原因须配 percentualReducaoBase。减免不来自减基的,只能在开票请求里直传原因和金额,不引用税种。

json
{
"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 } ]
}

ST 族税码的行原本必须带 ST 的 mva 与 aliquota;icmsPorEstado 配了这两项时行内可以不带,开票时买方所在州没配、行内也没有才拒(10004043)。

保存规则

  • 按主体税制校验:CRT 1 / 4 的主体只能用三位 CSOSN,CRT 2 / 3 只能用两位 CST,不符返回 10004046。CSOSN 101 / 201 行内没有 percentualCreditoSimples 且主体档案也没有时返回 10004043。CRT 3 主体的 PIS / COFINS 01、02 行不填 aliquota,而主体计税制度又没有可回落的法定税率时返回 10005008。
  • 纳税人专用税码:显式写了 naoContribuinte 为 true 或 tipoPessoa 为 Fisica 的 ICMS 行,不能用 CST / CSOSN 10、30、70、101、201、202、203,也不能带 percentualCreditoSimples,否则返回 10004047。规则与开票时相同。
  • CFOP 与组:ISSQN 行只能用 5933,ICMS 行不能用 5933(10005214)。
  • 整份替换:更新接口传的是整份税种,不带 codigo,tipo 须与现值一致,没传的组或行就没有了。
  • 未知字段拒绝:任意层级出现不存在的字段返回 10005210,消息点名路径,如 icms[0].aliquotaX。这条只对税种接口生效,开票接口不变。
  • 类型严格:数值用 JSON 数字("aliquota": 18,不能写成 "18"),布尔用 true / false,传成字符串返回 10005213 并点名路径。
  • 数值原样保存:18.00 存进去,详情读回仍是 18.00。
  • 行数上限:每组最多 50 行,超出返回 10001001。

每一行还要过开票时同名组的全部校验,保存时校验与错误码见创建税种。各字段的全部取值、每个税码保存时要带的字段,见该页的「枚举」区块与「其余字段的取值格式」。

税制变更与状态

税种响应与列表项都带 situacao:

situacao含义开票引用
Compativel按主体当前税制校验通过正常
IncompativelComRegime主体税制变了,税种按新税制已不通过;原因在 motivosIncompatibilidade返回 10005220

主体的 CRT、PIS/COFINS 计税制度或档案 percentualCreditoSimples 变化时,平台用保存时同一套校验重算该主体全部税种,自动标记不符或恢复相符。标记与恢复都不改 versao。从相符变为不符时推送 webhook tax_class.incompatible(需显式订阅,见 Webhook);已经不符的税种再次变化只更新原因,不重复推送。

motivosIncompatibilidade 每项:

字段说明
grupo出错的组,如 icms;无法定位时不出现
linha组内行号,从 0 起;无法定位时不出现
campo行内字段,如 situacaoTributaria;无法定位时不出现
codigoErro保存时会返回的错误码,如 10004046
crt重算时主体的 CRT
regimeTributario重算时主体的计税制度:1 Simples Nacional、2 Lucro Presumido、3 Lucro Real;未登记时不出现
mensagem说明,按请求语言,与保存报错文案相同

处理办法:按新税制整份替换(更新税种),校验通过即恢复 Compativel,versao 加 1。列表可用 situacao=IncompativelComRegime 找出全部要改的税种。

示例

一般税制(CRT 3)的 SP 主体:ICMS 按州内 / 跨州 × 个人 / 企业四行,PIS、COFINS、IBS/CBS 各一行 Padrao。

json
{
"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" }]
}

开一张卖给 RJ 企业的 NF-e,商品行只传创建时拿到的编号:

json
{ "codigo": "000068", "descricao": "Pendrive 16GB", "ncm": "85235190", "quantidade": 1, "unidadeMedida": "UN", "valorUnitario": 28.47, "classeImposto": "TF4440123455" }

场景推导为 SaidaForaEstado、Juridica,ICMS 命中第三行:CFOP 6102、CST 00、税率 12%;PIS、COFINS、IBS/CBS 取 Padrao 行。

Simples 主体(CRT 1 / 4)用 CSOSN,例子见创建税种的「示例:Simples 主体」。

NFC-e 用的税种

NFC-e 只引用 NFCe 税种。它的行在保存时就按 NFC-e 开票的规则校验(见「税种类型」),所以开票时不会再因字段不支持被拒。NFC-e 固定按 SaidaDentroEstado、非纳税人选行:Padrao 之外的 ICMS 行都写 SaidaDentroEstado,买方一律按非纳税人,所以带 "naoContribuinte": false 的行永远不会命中。

版本与历史票

  • 创建为版本 1;之后任何修改都加 1,只改 descricao 也加;整份替换内容完全相同时不变。
  • 受理时展开结果写进单据,查询接口商品行回显 classeImposto 与 versaoClasseImposto。未引用税种的行不出现这两个字段。
  • 之后改税种或删税种,已受理的票不受影响。
  • 同一 id 原样重提时,平台按展开税种之前的原始请求判断是否同一请求,命中直接返回原任务,不再读取税种:税种此后改版、删除、改到没有适用行都不影响。NF-e 与 NFC-e 相同。请求体不同时仍按既有规则拒绝。

错误码

错误码HTTP含义
10005200404税种不存在或已删除
10005202400开票引用的税种不存在、已删除或属于别的主体
10005203400税码不受支持
10005204400分类码不属于所填 CST
10005205400引用的税种含 NFC-e 不支持的字段
10005206409税种被并发修改
10005208400请求体带了 codigo,编号由平台生成
10005209400本行需要的组没有适用于本票的行
10005210400请求体含不存在的字段
10005211400同一组场景维度组合重复
10005212400CFOP 首位与场景不符
10005213400数值或布尔传成了字符串
10005214400CFOP 与组不符:ISSQN 行只能用 5933,ICMS 行不能用 5933
10005215400引用的税种类型与单据不符
10005216400税种类型不能修改
10005217400NFCe 税种带了 NFC-e 不支持的字段
10005218400该类型的税种不能有这个组
10005219400NFCe 税种的行场景不是 SaidaDentroEstado 或 Padrao
10005220400引用的税种与主体当前税制不符
10005230400减免原因不在该税码可用的取值内
10005231400税种里带了按票金额
10005232400icmsPorEstado 配了 ICMS 行用不上的值
10005233400按州配置里州重复
10005234400同一州推定抵免超过 4 组
10005235400减免金额推不出,须在开票时直传

另有通用错误码:10001001 字段校验失败、10001002 直传 icms 或 issqn 时缺 cfop、10004043 缺少税码要求的字段、10004044 字段不适用于该税码、10004046 税码与主体税制不符、10004047 非纳税人行用了纳税人专用税码、10005008 缺 PIS/COFINS 法定税率、10003000 主体不存在。