TF Fiscal
开发文档

开票主体

TF Fiscal 开票主体的生命周期、一个主体如何同时服务 NF-e / CT-e / DC-e / NFS-e、税收制度与计税制度、DC-e 与 NFS-e 的开通方式与相关错误码。

什么是开票主体

开票主体(empresa)是被代为开具单据的法律实体:电商平台的卖家、承运人,或为自己开票的集成商。每个主体由注册开票主体返回的 empresaId 标识,它是所有发行、查询、取消端点的路径变量。

步骤端点说明
1 注册主体POST /openapi/v2/empresas返回 empresaId、dceHabilitado 与 nfseHabilitado;请求体带 id 即更新既有主体
2 关联证书POST /openapi/v1/empresas/{empresaId}/certificadoDigitalA1 证书(.pfx / .p12)与密码;multipart 或 JSON + Base64
3 登记回调POST /openapi/v1/webhooks每个应用一个回调地址,所有单据类型共用
4 跟踪审核GET /openapi/v2/empresas、GET /openapi/v2/empresas/{empresaId}列出名下主体、按 empresaId 查审核状态、驳回原因、开通的单据类型与证书摘要;不计费
一步到位POST /openapi/v2/empresas/cadastro-automatico只传 CNPJ、A1 证书与密码,平台自动建档并挂好证书,代替上面第 1、2 步;缺的字段带 id 调注册主体补齐,进度用查询主体跟踪

生命周期

  1. 注册:注册接口调用成功后,主体进入平台审核队列。同一 CNPJ 重复注册返回 10003002;直接使用原 empresaId,或带 id 更新。
  2. 证书:关联 A1 证书。证书须属于主体 CNPJ(10003010)、在有效期内(10003011)且与当前生效证书不同(10003012);密码不符返回 10003008。上传成功即替换旧证书。
  3. 审批:平台为集成商开启自动审核时,先把注册资料与巴西企业名录比对,一致即自动通过;比对不一致、名录服务暂不可用或查无记录时转运营人工审批,未开启自动审核的一律人工审批。运营审批通过、且证书关联成功后主体方可开票。审批前开票,NF-e 返回 10004004(DC-e 为 10019004,CT-e 为 10017004)。审批进度用主体列表或查询主体查看,status 为 Ativa 即通过,Rejeitada 时 motivoStatus 为驳回原因。
  4. 环境:每个主体有一个当前环境,认证测试 Homologacao 或生产 Producao。新注册主体默认认证测试;切生产由平台运营操作、不开 API。每个发行请求里的环境值(NF-e 与 CT-e 为 ambienteEmissao,DC-e 为 ambiente)必须与主体当前环境一致,不一致返回 10004030(NF-e)、10017010(CT-e)或 10019010(DC-e)。参见环境。

注意: 更新(请求体带 id)不重新提交审核,也不改变主体状态与环境。例外是自动注册留下的草稿与已驳回主体:主体还没有州注册号时更新会写入 inscricaoEstadual,草稿资料补齐后自动进入审核;已驳回主体只有本次更新补齐了此前缺的字段,才转人工重新审核。

一个主体,四种单据

同一 empresaId、同一证书、同一回调地址服务所有单据类型。不同之处在于各类型所需的号段:

单据类型模型号段配置方式环境字段不可开票错误码
NF-e55注册或带 id 更新时的 emissaoNFeProduto.ambienteProducao(sequencialNFe / serieNFe)ambienteEmissao10004004
CT-e57由平台侧配置;注册报文没有 CT-e 配置块。未配置号段,或存在多个启用号段且请求未指定时,发行返回 10017007ambienteEmissao10017004
DC-e99注册时或带 id 更新时的 emissaoDCe.ambienteProducao(tipoEmitente、sequencialDCe / serieDCe、siteMarketplace)ambiente10019004
NFS-e—注册时或带 id 更新时的 emissaoNFSe(序列、起始票号与税制身份),也可由运营维护ambienteEmissao10018004
  • emissaoNFeProduto、emissaoDCe 与 emissaoNFSe 各自可选、至少传一个。只开 NF-e 传第一个,只开 DC-e 或只开 NFS-e 的主体可省略它(不建模型 55 号段),传多个则对应单据同时开通。三个都缺返回 400 10001001。
  • 注册时提交的系列与下一号即开票使用的号段,此后平台自动连续取号。
  • 带 id 更新并传 emissaoNFeProduto:该系列没有号段就新建,有就把下一张号改成 sequencialNFe,同时停用主体其他 NF-e 系列;不传则号段不动。下一张号往前改会重号被 SEFAZ 拒绝,往后改会跳号且跳过的号不自动作废,均由调用方负责。详见注册开票主体的「设定 NF-e 号段」。
  • 同一 CNPJ 可以在不同集成商下各自注册,系列由各集成商自行设置,平台不跨集成商查重。同一 CNPJ 在多个集成商处开票时须各自使用不重叠的系列,否则号码相撞,SEFAZ 会拒绝。
  • CT-e 发行还要求该 CNPJ 在其州税务局有 CT-e 发行资质;资质缺失时 SEFAZ 返回 230 - IE do emitente não cadastrada,平台无法代为解决。

税收制度

税收制度(官方称 Código de Regime Tributário,简称 CRT)决定开票时用哪套税码、怎么计税。平台内部按官方 1 到 4 保存,开放接口不收也不返回这个代码,而是用 optanteSimplesNacional 与 mei 两个布尔值表达。

CRT官方名称说明详情接口的 optanteSimplesNacional / mei
1Simples NacionalSimples Nacional 的微型与小型企业(ME / EPP)true / false
2Simples Nacional – excesso de sublimite de receita bruta加入 Simples Nacional,但营业收入超出州与市政的分项限额true / false
3Regime Normal一般税制,未加入 Simples Nacional 的企业false / false
4Simples Nacional - Microempreendedor individual - MEI个体微型企业true / true

税码族跟着税收制度走:CRT 1 / 4 的 NF-e、NFC-e 商品行用三位 CSOSN,CRT 2 / 3 用两位 CST,不符返回 10004046,见 NF-e。税收制度也决定 NFS-e 档案里 regimeApuracaoSn 是否必填,见下文。inscricaoEstadual 是开具 NF-e / CT-e / DC-e 的必填项,缺失返回 10003006;只做 NFS-e 的主体不要求州注册号。

注册时两个布尔值怎么换算

meioptanteSimplesNacional写入的 CRT
falsefalse3 Regime Normal
falsetrue1 Simples Nacional
truetrue4 MEI
truefalse4 MEI:mei 优先,不拒绝,也不看 optanteSimplesNacional

MEI 一定加入了 Simples Nacional,建议按 true / true 传。两个布尔值组合不出 CRT 2,见下文「超出分项限额」。

写入之后怎么改

  • 注册主体带 id 的更新不改税收制度。唯一例外是自动注册留下的税制待确认主体:这时按请求里的两个布尔值写入一次。
  • 控制台主体详情里的「税务补录」可以随时改 CRT(1 到 4 都能选),不论主体处于什么状态,也会清除税制待确认标记。改后最迟一分钟对开票生效,引用的税种按新税制重新校验。
  • 查询主体按当前 CRT 回显两个布尔值;税制待确认时两者都为 null。

超出分项限额(CRT 2)

开放接口表达不了 CRT 2,平台也不会自动推出它。这类主体按下面的方式处理:

  1. 注册时按 Simples Nacional 传:optanteSimplesNacional=true、mei=false,平台先写入 CRT 1。
  2. 在控制台「税务补录」里把税制改为 Simples Nacional(超限额),即 CRT 2。
  3. 之后查询主体回 true / false;再用带 id 的更新重传 true / false 也不会改回 CRT 1。

改为 CRT 2 后,商品行的 ICMS 要用两位 CST。

Lucro Presumido、Lucro Real 与 Lucro Arbitrado

这三项不是税收制度,而是联邦所得税的计算方式;在发票上它们都属于 CRT 3 Regime Normal。开放接口不收也不返回这一项,CNPJ 查询、主体接口、自动注册都没有对应字段。它在开票时只影响 PIS / COFINS CST 01 的税率,平台称为计税制度:

计税制度适用PISCOFINS
累积制Lucro Presumido、Lucro Arbitrado0,65 %3,00 %
非累积制Lucro Real1,65 %7,60 %

计税制度在控制台「税务补录」里配置:Lucro Presumido(累计制)或 Lucro Real(非累计制),Lucro Arbitrado 选累计制。通过接口注册的 CRT 3 主体一开始没有计税制度。NFS-e 也按计税制度取 PIS / COFINS 税率,但规则不同,见 NFS-e;下面只讲 NF-e 与 NFC-e。

CRT 3 主体开 NF-e、NFC-e(含离线开票)时,PIS、COFINS CST 01 的税率按下表取:

请求或引用的税种里主体配置了计税制度主体未配置计税制度
带了 aliquota须等于上表的法定税率,否则拒绝,10005008照用请求值
没带 aliquota平台补法定税率拒绝,10005007

保存税种时也做同一项核对:主体配置了计税制度,CST 01 行的 aliquota 与法定税率不符即返回 10005008。CST 01 以外的税码不按计税制度补率;CRT 1、2、4 的主体平台也不补率。

开通 DC-e

DC-e(模型 99)由 emissaoDCe 配置块开通:

json
"emissaoDCe": {
"ambienteProducao": {
"tipoEmitente": "Marketplace",
"sequencialDCe": 1,
"serieDCe": "1",
"siteMarketplace": "https://loja.exemplo.com.br"
}
}
  • tipoEmitente 为 Marketplace(电商平台代非纳税人卖家 / 个人发件)或 OwnIssuer(企业自发)。Carrier 可登记但发行被 10019013 拒绝。Marketplace 必须传 siteMarketplace。
  • 未传 emissaoDCe 的主体不会开通 DC-e:注册仍成功,响应 dceHabilitado=false,发行时收到 10019012。请在注册当场核对该字段。
  • 事后补开 DC-e:带 id 重传注册报文并加上 emissaoDCe 块。模型 99 号段只升不降:sequencialDCe 只能抬高下一号,不能降低(400 10001001);旧系列仍启用时换 serieDCe 会被拒绝(400 10001001,须经运营)。

开通 NFS-e

NFS-e 由 emissaoNFSe 配置块开通。带上本块主体才能开 NFS-e,票号序列也在此建立。这里只放不会一张票一个样的东西——服务码、CNAE、NBS、ISS 税率、代扣与 IBS/CBS 都跟着卖的是什么服务走,放在每张票的 servico 块里传。

json
"emissaoNFSe": {
"serieDps": "1",
"sequencialDps": 1,
"regimeApuracaoSn": 1,
"regimeEspecialTributacao": 0
}
字段类型必填说明
serieDpsstring(1-5 位数字)否开票用的 DPS / RPS 序列号。每张票都用本项,发行请求不接受单独的序列号。本项不传则为 1
sequencialDpsinteger否下一张要开的票号,从 1 起。从别家迁移过来时传已用过的最大号加一,票号才能接着原来的继续。本项不传则为 1。号段一旦建立,更新时不再改动
regimeApuracaoSnintegerME/EPP 必填Simples Nacional 怎么计算税:1 联邦与市政均按 SN / 2 联邦按 SN、市政固定额 / 3 联邦按 SN、市政常规。Simples 归属由顶层 optanteSimplesNacional / mei 推导。非 Simples 主体传了本项即拒
regimeEspecialTributacaointeger否有没有特殊税务待遇:0 无 / 1 合作社行为 / 2 核定征收 / 3 市政微型企业 / 4 公证登记 / 5 自由职业者 / 6 专业人士合伙。本项不传则为 0
  • 注册响应新增 nfseHabilitado:{ "empresaId": "…", "dceHabilitado": false, "nfseHabilitado": true }。未传本块即 false,发行时收到 10018005。
  • 更新(请求体带 id)带本块时整份覆盖档案:未传的可选项即回默认值;不带本块则档案不动,nfseHabilitado 回显主体现状。强制指定市政标准是运营动作,不经本块。
  • 结构约束在受理期即拒(400 10001001):ME/EPP 缺 regimeApuracaoSn、非 Simples 带 regimeApuracaoSn。
  • 只做 NFS-e 的主体可以不传 emissaoNFeProduto(不建模型 55 号段),也不要求州注册号 inscricaoEstadual。
  • 圣保罗主体的市政登记号 CCM 取顶层 inscricaoMunicipal,不在本块重复。

相关错误码

错误码HTTP场景处置
10003002400CNPJ 已注册该主体已存在,直接使用原 empresaId 或带 id 更新
10003000404empresaId 不存在或非本应用名下核对 empresaId
10003006400注册资料缺 IE补 inscricaoEstadual
10003010 / 10003011 / 10003012400证书 CNPJ 与主体不一致 / 已过期 / 与现有证书重复换正确证书
10003035400Base64 非法或证书超过 1MB(JSON 形态)修正编码或文件
10003008400证书密码不符核对密码
10003004400注册:城市 / 州解析不到 IBGE 码核对 UF 与城市名
10004004400主体不可开票(未审批通过或证书未就绪)等待审批 / 关联证书
10004030400ambienteEmissao 与主体当前环境不一致按主体环境提交或联系运营切换
10001001400字段校验失败,或注册 / 更新契约错误(三个配置块都缺、更新改 cnpj / 换市政、DC-e 号段降号、换系列、emissaoNFSe 结构约束不满足)按 mensagem 修正

完整清单见错误码。