开票主体
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}/certificadoDigital | A1 证书(.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 调注册主体补齐,进度用查询主体跟踪 |
生命周期
- 注册:注册接口调用成功后,主体进入平台审核队列。同一 CNPJ 重复注册返回
10003002;直接使用原empresaId,或带id更新。 - 证书:关联 A1 证书。证书须属于主体 CNPJ(
10003010)、在有效期内(10003011)且与当前生效证书不同(10003012);密码不符返回10003008。上传成功即替换旧证书。 - 审批:平台为集成商开启自动审核时,先把注册资料与巴西企业名录比对,一致即自动通过;比对不一致、名录服务暂不可用或查无记录时转运营人工审批,未开启自动审核的一律人工审批。运营审批通过、且证书关联成功后主体方可开票。审批前开票,NF-e 返回
10004004(DC-e 为10019004,CT-e 为10017004)。审批进度用主体列表或查询主体查看,status为Ativa即通过,Rejeitada时motivoStatus为驳回原因。 - 环境:每个主体有一个当前环境,认证测试
Homologacao或生产Producao。新注册主体默认认证测试;切生产由平台运营操作、不开 API。每个发行请求里的环境值(NF-e 与 CT-e 为ambienteEmissao,DC-e 为ambiente)必须与主体当前环境一致,不一致返回10004030(NF-e)、10017010(CT-e)或10019010(DC-e)。参见环境。
注意: 更新(请求体带
id)不重新提交审核,也不改变主体状态与环境。例外是自动注册留下的草稿与已驳回主体:主体还没有州注册号时更新会写入inscricaoEstadual,草稿资料补齐后自动进入审核;已驳回主体只有本次更新补齐了此前缺的字段,才转人工重新审核。
一个主体,四种单据
同一 empresaId、同一证书、同一回调地址服务所有单据类型。不同之处在于各类型所需的号段:
| 单据类型 | 模型 | 号段配置方式 | 环境字段 | 不可开票错误码 |
|---|---|---|---|---|
| NF-e | 55 | 注册或带 id 更新时的 emissaoNFeProduto.ambienteProducao(sequencialNFe / serieNFe) | ambienteEmissao | 10004004 |
| CT-e | 57 | 由平台侧配置;注册报文没有 CT-e 配置块。未配置号段,或存在多个启用号段且请求未指定时,发行返回 10017007 | ambienteEmissao | 10017004 |
| DC-e | 99 | 注册时或带 id 更新时的 emissaoDCe.ambienteProducao(tipoEmitente、sequencialDCe / serieDCe、siteMarketplace) | ambiente | 10019004 |
| NFS-e | — | 注册时或带 id 更新时的 emissaoNFSe(序列、起始票号与税制身份),也可由运营维护 | ambienteEmissao | 10018004 |
emissaoNFeProduto、emissaoDCe与emissaoNFSe各自可选、至少传一个。只开 NF-e 传第一个,只开 DC-e 或只开 NFS-e 的主体可省略它(不建模型 55 号段),传多个则对应单据同时开通。三个都缺返回 40010001001。- 注册时提交的系列与下一号即开票使用的号段,此后平台自动连续取号。
- 带
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 |
|---|---|---|---|
| 1 | Simples Nacional | Simples Nacional 的微型与小型企业(ME / EPP) | true / false |
| 2 | Simples Nacional – excesso de sublimite de receita bruta | 加入 Simples Nacional,但营业收入超出州与市政的分项限额 | true / false |
| 3 | Regime Normal | 一般税制,未加入 Simples Nacional 的企业 | false / false |
| 4 | Simples 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 的主体不要求州注册号。
注册时两个布尔值怎么换算
mei | optanteSimplesNacional | 写入的 CRT |
|---|---|---|
false | false | 3 Regime Normal |
false | true | 1 Simples Nacional |
true | true | 4 MEI |
true | false | 4 MEI:mei 优先,不拒绝,也不看 optanteSimplesNacional |
MEI 一定加入了 Simples Nacional,建议按 true / true 传。两个布尔值组合不出 CRT 2,见下文「超出分项限额」。
写入之后怎么改
- 注册主体带
id的更新不改税收制度。唯一例外是自动注册留下的税制待确认主体:这时按请求里的两个布尔值写入一次。 - 控制台主体详情里的「税务补录」可以随时改 CRT(1 到 4 都能选),不论主体处于什么状态,也会清除税制待确认标记。改后最迟一分钟对开票生效,引用的税种按新税制重新校验。
- 查询主体按当前 CRT 回显两个布尔值;税制待确认时两者都为
null。
超出分项限额(CRT 2)
开放接口表达不了 CRT 2,平台也不会自动推出它。这类主体按下面的方式处理:
- 注册时按 Simples Nacional 传:
optanteSimplesNacional=true、mei=false,平台先写入 CRT 1。 - 在控制台「税务补录」里把税制改为 Simples Nacional(超限额),即 CRT 2。
- 之后查询主体回
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 的税率,平台称为计税制度:
| 计税制度 | 适用 | PIS | COFINS |
|---|---|---|---|
| 累积制 | Lucro Presumido、Lucro Arbitrado | 0,65 % | 3,00 % |
| 非累积制 | Lucro Real | 1,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 配置块开通:
"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只能抬高下一号,不能降低(40010001001);旧系列仍启用时换serieDCe会被拒绝(40010001001,须经运营)。
开通 NFS-e
NFS-e 由 emissaoNFSe 配置块开通。带上本块主体才能开 NFS-e,票号序列也在此建立。这里只放不会一张票一个样的东西——服务码、CNAE、NBS、ISS 税率、代扣与 IBS/CBS 都跟着卖的是什么服务走,放在每张票的 servico 块里传。
"emissaoNFSe": {"serieDps": "1","sequencialDps": 1,"regimeApuracaoSn": 1,"regimeEspecialTributacao": 0}
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
serieDps | string(1-5 位数字) | 否 | 开票用的 DPS / RPS 序列号。每张票都用本项,发行请求不接受单独的序列号。本项不传则为 1 |
sequencialDps | integer | 否 | 下一张要开的票号,从 1 起。从别家迁移过来时传已用过的最大号加一,票号才能接着原来的继续。本项不传则为 1。号段一旦建立,更新时不再改动 |
regimeApuracaoSn | integer | ME/EPP 必填 | Simples Nacional 怎么计算税:1 联邦与市政均按 SN / 2 联邦按 SN、市政固定额 / 3 联邦按 SN、市政常规。Simples 归属由顶层 optanteSimplesNacional / mei 推导。非 Simples 主体传了本项即拒 |
regimeEspecialTributacao | integer | 否 | 有没有特殊税务待遇: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 | 场景 | 处置 |
|---|---|---|---|
10003002 | 400 | CNPJ 已注册 | 该主体已存在,直接使用原 empresaId 或带 id 更新 |
10003000 | 404 | empresaId 不存在或非本应用名下 | 核对 empresaId |
10003006 | 400 | 注册资料缺 IE | 补 inscricaoEstadual |
10003010 / 10003011 / 10003012 | 400 | 证书 CNPJ 与主体不一致 / 已过期 / 与现有证书重复 | 换正确证书 |
10003035 | 400 | Base64 非法或证书超过 1MB(JSON 形态) | 修正编码或文件 |
10003008 | 400 | 证书密码不符 | 核对密码 |
10003004 | 400 | 注册:城市 / 州解析不到 IBGE 码 | 核对 UF 与城市名 |
10004004 | 400 | 主体不可开票(未审批通过或证书未就绪) | 等待审批 / 关联证书 |
10004030 | 400 | ambienteEmissao 与主体当前环境不一致 | 按主体环境提交或联系运营切换 |
10001001 | 400 | 字段校验失败,或注册 / 更新契约错误(三个配置块都缺、更新改 cnpj / 换市政、DC-e 号段降号、换系列、emissaoNFSe 结构约束不满足) | 按 mensagem 修正 |
完整清单见错误码。
