开票主体

注册开票主体

登记开票主体（请求体带 `id` 时为更新），返回后续所有端点使用的 `empresaId`。

POST/openapi/v2/empresas

需要 token、timestamp、sign 三个签名头，参见认证与签名。

提交卖家企业资料，响应返回 empresaId，即后续所有端点的路径变量。注册后主体进入平台审核队列：运营审批通过且证书关联成功后方可开票。emissaoNFeProduto 与 emissaoDCe 两个配置块各自可选、至少传一个：只开 NF-e 传前者，只开 DC-e 的主体可省略前者（不建 NF-e 号段），两个都传则两种单据同时开通；两个都缺返回 400 10001001，mensagem 点名两个块。请求体带 id（注册返回的 empresaId）即按更新处理，见下文对应小节。

参数

请求体

idstring更新时必填
注册时返回的 empresaId。注册时省略；更新时携带（必须属于当前应用，否则 404 10003000）。
cnpjstring必填
14 位纯数字。更新时不可变更：与主体不一致返回 400 10001001。
示例: 14422279000106
inscricaoMunicipalstring可选
市政注册号，最长 15 位。
inscricaoEstadualstring必填
州注册号 IE。文档为可选，本平台开票必须有 IE，缺失返回 10003006。
razaoSocialstring必填
企业法定名称，最长 60。
nomeFantasiastring可选
商号，最长 60。
optanteSimplesNacionalboolean必填
是否 Simples Nacional 纳税人。
meiboolean必填
是否 MEI。税制推导：mei=true → MEI；否则 optanteSimplesNacional=true → Simples；否则一般税制。
emailstring必填
联系邮箱。
telefoneComercialstring必填
商务电话，纯数字含区号。
enderecoobject必填
主体地址。
emissaoNFeProdutoobjectemissaoNFeProduto / emissaoDCe 至少一个
NF-e（模型 55）发行配置。更新时被忽略：NF-e 号段不经本接口维护。
emissaoDCeobjectemissaoNFeProduto / emissaoDCe 至少一个
DC-e（模型 99）发行配置。未传此块的主体不会开通 DC-e：注册仍成功，响应 dceHabilitado=false，发行时收到 DCe00004。更新时不带此块则不动 DC-e 档案。

响应

200

注册已受理并进入审核队列（或更新已生效）。两种情况响应形状相同。

empresaIdstring
主体标识，后续所有接口的路径变量，请持久保存。形态为数字字符串。
dceHabilitadoboolean
主体是否已开通 DC-e（未传 emissaoDCe 即为 false）。更新时回显主体现状。只做 NF-e 的集成商忽略即可。

错误

错误码	HTTP
10003002	400	CNPJ 已注册。该主体已存在，直接使用原 `empresaId`（或带 `id` 更新）。
10003000	404	更新：`id` 不存在或非本应用名下。
10003006	400	注册资料缺 IE。补 `inscricaoEstadual`。
GW001	400	城市 / 州解析不到 IBGE 码。核对 UF 与城市名。
10001001	400	请求字段校验失败（每字段一条），或注册 / 更新契约错误：两个配置块都缺、更新改 `cnpj` / 换市政、号段降号、换系列。

注册规则

注册接口把主体提交到平台审核队列；运营审批通过、且证书关联成功后（关联证书）主体方可开票。审批前开票会收到 10004004（NF-e）或 DCe00008（DC-e）。审批进度请与平台运营确认。
注册后主体处于认证测试环境（Homologacao）：联调请传 ambienteEmissao=Homologacao（NF-e）/ ambiente=Homologacao（DC-e）。切生产由运营操作、不开 API；切换前传 Producao 会收到 10004030（NF-e）或 DCe00004（DC-e）。参见环境。
emissaoNFeProduto 与 emissaoDCe 各自可选、至少传一个：只做 DC-e 的集成商不必伪造 NF-e 号段（不传 emissaoNFeProduto 即不建模型 55 号段）。两个都缺返回 400 10001001。
未传 emissaoDCe 的主体不会开通 DC-e：注册仍成功，但响应 dceHabilitado=false，发行时收到 DCe00004。请在注册当场核对该字段。
inscricaoEstadual 在本平台为必填（提交审核硬条件），NF-e 与 DC-e 相同。
同一 CNPJ 重复注册返回 10003002。

更新（请求体带 `id`）

同一接口、请求体带 id（注册返回的 empresaId）即按更新处理，用于补开 DC-e、抬高起始号或修正联系信息；其余字段仍按注册报文的必填规则校验，直接重传注册报文并加上 id 即可。

定位当前租户内的主体，找不到返回 404 10003000。
只更新：emissaoDCe（tipoEmitente / siteMarketplace 档案与模型 99 号段）、nomeFantasia / email / telefoneComercial、endereco 的 cep / logradouro / numero / complemento / bairro（空值不清除既有值）。
不更新：cnpj（与主体不一致返回 400 10001001）、razaoSocial / inscricaoEstadual / inscricaoMunicipal / 税制、环境；endereco.uf / endereco.cidade 解析到另一市政返回 400 10001001（换市政须经运营）；emissaoNFeProduto 在更新时被忽略（NF-e 号段不经本接口维护）。
模型 99 号段只升不降：同系列号段不存在（且没有其他启用系列）则按 sequencialDCe / serieDCe 新建；已存在时 sequencialDCe 只能把下一号抬高（等于当前下一号即无变化），低于当前下一号返回 400 10001001 并说明；换 serieDCe 而旧系列仍启用返回 400 10001001（切换系列须经运营，避免两条启用号段让发行撞 10019007）。抬高游标跳过的号不会被发放。
不带 emissaoDCe 的更新不动 DC-e 档案，dceHabilitado 回显主体现状。
更新不重新提交审核、不改变主体状态；响应同样为 { empresaId, dceHabilitado }。
运营侧也可维护上述配置；变更 sequencialDCe 只影响尚未取号的单据。