税种
税种:把 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。
| 规则 | NFe | NFCe |
|---|---|---|
| 可用的组 | icms、ipi、pis、cofins、ibsCbs;不能有 issqn | icms、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、Juridica | 5 |
SaidaForaEstado | 跨州出库 | 出库票,买方在别的州 | Fisica、Juridica | 6 |
SaidaExterior | 出口 | 出库票,买方在国外 | Estrangeiro | 7 |
EntradaDentroEstado | 州内入库 | 退货票,对方与开票主体同州 | Fisica、Juridica | 1 |
EntradaForaEstado | 跨州入库 | 退货票,对方在别的州 | Fisica、Juridica | 2 |
EntradaExterior | 国外入库 | 退货票,对方在国外 | Estrangeiro | 3 |
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 | 场景相同,两者都不填 |
| 5 | Padrao 行,按 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 整组,不会残留减基比例。
{"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。减免不来自减基的,只能在开票请求里直传原因和金额,不引用税种。
{"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 / COFINS01、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。
{"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,商品行只传创建时拿到的编号:
{ "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 | 含义 |
|---|---|---|
| 10005200 | 404 | 税种不存在或已删除 |
| 10005202 | 400 | 开票引用的税种不存在、已删除或属于别的主体 |
| 10005203 | 400 | 税码不受支持 |
| 10005204 | 400 | 分类码不属于所填 CST |
| 10005205 | 400 | 引用的税种含 NFC-e 不支持的字段 |
| 10005206 | 409 | 税种被并发修改 |
| 10005208 | 400 | 请求体带了 codigo,编号由平台生成 |
| 10005209 | 400 | 本行需要的组没有适用于本票的行 |
| 10005210 | 400 | 请求体含不存在的字段 |
| 10005211 | 400 | 同一组场景维度组合重复 |
| 10005212 | 400 | CFOP 首位与场景不符 |
| 10005213 | 400 | 数值或布尔传成了字符串 |
| 10005214 | 400 | CFOP 与组不符:ISSQN 行只能用 5933,ICMS 行不能用 5933 |
| 10005215 | 400 | 引用的税种类型与单据不符 |
| 10005216 | 400 | 税种类型不能修改 |
| 10005217 | 400 | NFCe 税种带了 NFC-e 不支持的字段 |
| 10005218 | 400 | 该类型的税种不能有这个组 |
| 10005219 | 400 | NFCe 税种的行场景不是 SaidaDentroEstado 或 Padrao |
| 10005220 | 400 | 引用的税种与主体当前税制不符 |
| 10005230 | 400 | 减免原因不在该税码可用的取值内 |
| 10005231 | 400 | 税种里带了按票金额 |
| 10005232 | 400 | icmsPorEstado 配了 ICMS 行用不上的值 |
| 10005233 | 400 | 按州配置里州重复 |
| 10005234 | 400 | 同一州推定抵免超过 4 组 |
| 10005235 | 400 | 减免金额推不出,须在开票时直传 |
另有通用错误码:10001001 字段校验失败、10001002 直传 icms 或 issqn 时缺 cfop、10004043 缺少税码要求的字段、10004044 字段不适用于该税码、10004046 税码与主体税制不符、10004047 非纳税人行用了纳税人专用税码、10005008 缺 PIS/COFINS 法定税率、10003000 主体不存在。
