开票主体
注册开票主体
登记开票主体(请求体带 `id` 时为更新),返回后续所有端点使用的 `empresaId`。
/openapi/v2/empresastoken、timestamp、sign 三个签名头,参见认证与签名。提交卖家企业资料,响应返回 empresaId,即后续所有端点的路径变量。emissaoNFeProduto、emissaoNFeConsumidor、emissaoDCe 与 emissaoNFSe 四个配置块各自可选、至少传一个:开哪种票传哪块;全都缺返回 400 10001001。请求体带 id 即按更新处理,见下文对应小节。
请求体
id*更新时必填。 | string | 主体标识 |
cnpj* | string | 主体 CNPJ |
inscricaoMunicipal | string | 市政登记号 |
inscricaoEstadual*开 NF-e / NFC-e / DC-e 必填。 | string | 州注册号 IE |
razaoSocial* | string | 法定名称 |
nomeFantasia | string | 商号 |
optanteSimplesNacional* | bool | 是否 Simples |
mei* | bool | 是否 MEI |
email* | string | 联系邮箱 |
telefoneComercial* | string | 商务电话 |
* | object | 主体地址 |
*emissaoNFeProduto / emissaoNFeConsumidor / emissaoDCe / emissaoNFSe 至少传一个。 | object | NF-e 开票配置 |
*emissaoNFeProduto / emissaoNFeConsumidor / emissaoDCe / emissaoNFSe 至少传一个。 | object | NFC-e 开票配置 |
*emissaoNFeProduto / emissaoNFeConsumidor / emissaoDCe / emissaoNFSe 至少传一个。 | object | DC-e 发行配置 |
*emissaoNFeProduto / emissaoNFeConsumidor / emissaoDCe / emissaoNFSe 至少传一个。 | object | NFS-e 发行配置 |
* 必填字段
empresaId | string | 主体标识 |
dceHabilitado | bool | 是否开通 DC-e |
nfseHabilitado | bool | 是否开通 NFS-e |
nfceHabilitado | bool | 是否开通 NFC-e |
开哪种票就传哪个配置块。主体资料每个场景都一样,下面只列变化的部分。
只开 NF-e
最常见的情形。inscricaoEstadual 必填。
{"cnpj": "14422279000106","inscricaoEstadual": "999999","razaoSocial": "Empresa teste LTDA","optanteSimplesNacional": true,"mei": false,"email": "empresa-teste@exemplo.com.br","telefoneComercial": "6122222222","endereco": { "pais": "Brasil", "uf": "MG", "cidade": "Belo Horizonte", "logradouro": "Rua Teste", "numero": "999", "bairro": "Bairro Teste", "cep": "85100000" },"emissaoNFeProduto": { "ambienteProducao": { "sequencialNFe": 1, "serieNFe": "10" } }}
inscricaoEstadual* | string | 州注册号 IE |
* | object | NF-e 开票配置 |
* 必填字段
同时开 NF-e 与 NFC-e
既做门店零售、也给企业开票的商家。NFC-e 系列号与 NF-e 系列号分开。inscricaoEstadual 必填。
{"cnpj": "14422279000106","inscricaoEstadual": "999999","razaoSocial": "Empresa teste LTDA","optanteSimplesNacional": true,"mei": false,"email": "empresa-teste@exemplo.com.br","telefoneComercial": "6122222222","endereco": { "pais": "Brasil", "uf": "MG", "cidade": "Belo Horizonte", "logradouro": "Rua Teste", "numero": "999", "bairro": "Bairro Teste", "cep": "85100000" },"emissaoNFeProduto": { "ambienteProducao": { "sequencialNFe": 1, "serieNFe": "10" } },"emissaoNFeConsumidor": { "ambienteProducao": { "sequencialNFe": 1, "serieNFe": "1" } }}
inscricaoEstadual* | string | 州注册号 IE |
* | object | NFC-e 开票配置 |
* 必填字段
只开 NFS-e
没有州注册号的服务企业。inscricaoMunicipal 是市政登记号;圣保罗即 CCM。
{"cnpj": "14422279000106","inscricaoMunicipal": "999999","razaoSocial": "Servicos teste LTDA","optanteSimplesNacional": true,"mei": false,"email": "servicos-teste@exemplo.com.br","telefoneComercial": "1133334444","endereco": { "pais": "Brasil", "uf": "SP", "cidade": "Sao Paulo", "logradouro": "Av. Paulista", "numero": "1000", "bairro": "Bela Vista", "cep": "01310100" },"emissaoNFSe": { "serieDps": "1", "sequencialDps": 1, "regimeApuracaoSn": 1 }}
inscricaoMunicipal | string | 市政登记号 |
* | object | NFS-e 发行配置 |
* 必填字段
同时开 NF-e 与 DC-e 的平台
代第三方发 DC-e 的电商平台。siteMarketplace 必填;Carrier 可登记但不能发行。
{"cnpj": "14422279000106","inscricaoEstadual": "999999","razaoSocial": "Empresa teste LTDA","optanteSimplesNacional": true,"mei": false,"email": "empresa-teste@exemplo.com.br","telefoneComercial": "6122222222","endereco": { "pais": "Brasil", "uf": "MG", "cidade": "Belo Horizonte", "logradouro": "Rua Teste", "numero": "999", "bairro": "Bairro Teste", "cep": "85100000" },"emissaoNFeProduto": { "ambienteProducao": { "sequencialNFe": 1, "serieNFe": "10" } },"emissaoDCe": { "ambienteProducao": { "tipoEmitente": "Marketplace", "sequencialDCe": 1, "serieDCe": "1", "siteMarketplace": "https://loja.exemplo.com.br" } }}
* | object | DC-e 发行配置 |
* 必填字段
同一接口、请求体带 id 即为更新:直接重传注册报文并加上 id,其余字段仍按注册规则校验。不更新 cnpj、razaoSocial、inscricaoEstadual、inscricaoMunicipal、税制(在控制台「税务补录」里改)与环境。不传 emissaoNFeProduto 则 NF-e 号段不动;传了见下文「设定 NF-e 号段」。换市政(uf / cidade)返回 400 10001001,须经运营。更新不重新提交审核、不改主体状态;响应与注册相同。
自动注册的主体。 自动注册建出的主体也用本更新补全:草稿或已驳回主体还没有州注册号时,写入请求里的 inscricaoEstadual;税制待确认时,按 mei 与 optanteSimplesNacional 写入税制(没有待确认标记时税制仍不更新);草稿更新后资料齐全自动进入审核;已驳回主体只有本次更新补齐了此前缺的字段,才转人工重新审核(对本账号下所有草稿与已驳回主体都生效,包括在控制台建的草稿)。缺什么看查询主体的 camposPendentes。
设定 NF-e 号段
适用于还没有 NF-e 号段的主体(例如自动注册建出的),或要换系列、改下一张号的主体。该 serieNFe 还没有号段时新建,下一张号为 sequencialNFe;已有时把下一张号改成 sequencialNFe,已停用的系列重新启用。主体其他 NF-e 系列一律停用,开票只用这一个系列。
sequencialNFe 可以往前改也可以往后改,后果由调用方负责:往前改会把用过的号再发一次,SEFAZ 按重号拒绝;往后改会跳过中间的号,跳过的号不会被自动作废,需要作废请自行处理。此前开票未获授权、号码小于 sequencialNFe 的票号仍会先被用掉。超过 999999999 返回 400 10001001。
{"id": "1934811222334455","cnpj": "14422279000106","inscricaoEstadual": "999999","razaoSocial": "Empresa teste LTDA","optanteSimplesNacional": true,"mei": false,"email": "empresa-teste@exemplo.com.br","telefoneComercial": "6122222222","endereco": { "pais": "Brasil", "uf": "MG", "cidade": "Belo Horizonte", "logradouro": "Rua Teste", "numero": "999", "bairro": "Bairro Teste", "cep": "85100000" },"emissaoNFeProduto": { "ambienteProducao": { "sequencialNFe": 1501, "serieNFe": "10" } }}
id* | string | 主体标识 |
* | object | NF-e 开票配置 |
* 必填字段
补开 DC-e
注册时没传 emissaoDCe 的主体。尚无启用的 DC-e 号段时,按 sequencialDCe / serieDCe 新建。
{"id": "1934811222334455","cnpj": "14422279000106","inscricaoEstadual": "999999","razaoSocial": "Empresa teste LTDA","optanteSimplesNacional": true,"mei": false,"email": "empresa-teste@exemplo.com.br","telefoneComercial": "6122222222","endereco": { "pais": "Brasil", "uf": "MG", "cidade": "Belo Horizonte", "logradouro": "Rua Teste", "numero": "999", "bairro": "Bairro Teste", "cep": "85100000" },"emissaoDCe": { "ambienteProducao": { "tipoEmitente": "OwnIssuer", "sequencialDCe": 1, "serieDCe": "1" } }}
id* | string | 主体标识 |
* | object | DC-e 发行配置 |
* 必填字段
抬高 DC-e 起始号
同一系列,sequencialDCe 大于当前下一号。等于当前不变;小于返回 400 10001001。跳过的号不会再发。旧系列仍启用时换 serieDCe 同样返回 400 10001001。
{"id": "1934811222334455","cnpj": "14422279000106","inscricaoEstadual": "999999","razaoSocial": "Empresa teste LTDA","optanteSimplesNacional": true,"mei": false,"email": "empresa-teste@exemplo.com.br","telefoneComercial": "6122222222","endereco": { "pais": "Brasil", "uf": "MG", "cidade": "Belo Horizonte", "logradouro": "Rua Teste", "numero": "999", "bairro": "Bairro Teste", "cep": "85100000" },"emissaoDCe": { "ambienteProducao": { "tipoEmitente": "OwnIssuer", "sequencialDCe": 500, "serieDCe": "1" } }}
id* | string | 主体标识 |
* | object | DC-e 发行配置 |
* 必填字段
修正联系信息与地址
只更新 nomeFantasia、email、telefoneComercial 和同一市政内的地址字段。空值不会清掉已存的值。
{"id": "1934811222334455","cnpj": "14422279000106","inscricaoEstadual": "999999","razaoSocial": "Empresa teste LTDA","nomeFantasia": "Loja Teste","optanteSimplesNacional": true,"mei": false,"email": "financeiro@exemplo.com.br","telefoneComercial": "3133334444","endereco": { "pais": "Brasil", "uf": "MG", "cidade": "Belo Horizonte", "logradouro": "Rua Nova", "numero": "10", "complemento": "Sala 2", "bairro": "Centro", "cep": "30110000" }}
id* | string | 主体标识 |
nomeFantasia | string | 商号 |
email | string | 联系邮箱 |
telefoneComercial | string | 商务电话 |
* | object | 主体地址 |
* 必填字段
新建或覆盖 NFS-e 档案
传 emissaoNFSe 即整份覆盖档案,没传的项回到缺省。已建的号段不会改:sequencialDps 只在号段尚不存在时生效。
{"id": "1934811222334455","cnpj": "14422279000106","inscricaoEstadual": "999999","razaoSocial": "Empresa teste LTDA","optanteSimplesNacional": true,"mei": false,"email": "empresa-teste@exemplo.com.br","telefoneComercial": "6122222222","endereco": { "pais": "Brasil", "uf": "MG", "cidade": "Belo Horizonte", "logradouro": "Rua Teste", "numero": "999", "bairro": "Bairro Teste", "cep": "85100000" },"emissaoNFSe": { "serieDps": "1", "sequencialDps": 120, "regimeApuracaoSn": 1, "regimeEspecialTributacao": 0 }}
id* | string | 主体标识 |
* | object | NFS-e 发行配置 |
* 必填字段
mei + optanteSimplesNacional主体税制
没有单独字段:由这两个布尔值组合得出,按 CRT 保存。mei=true 优先。组合不出 CRT 2(超出分项限额),它在控制台设置;Lucro Presumido、Real、Arbitrado 都是 CRT 3。见开票主体的「税收制度」。
| 取值 | 含义 |
|---|---|
| mei=true | CRT 4,MEI 个体微型企业;忽略 optanteSimplesNacional;不需要传 emissaoNFSe.regimeApuracaoSn |
| mei=false, optanteSimplesNacional=true | CRT 1,Simples 纳税人 ME/EPP;超出分项限额的主体也这样传;带 emissaoNFSe 时必须传 regimeApuracaoSn |
| mei=false, optanteSimplesNacional=false | CRT 3,Regime Normal 一般税制,Lucro Presumido、Real、Arbitrado 都在此;不能传 emissaoNFSe.regimeApuracaoSn |
endereco.uf主体所在州
| 取值 | 含义 |
|---|---|
| AC | Acre |
| AL | Alagoas |
| AP | Amapá |
| AM | Amazonas |
| BA | Bahia |
| CE | Ceará |
| DF | Distrito Federal |
| ES | Espírito Santo |
| GO | Goiás |
| MA | Maranhão |
| MT | Mato Grosso |
| MS | Mato Grosso do Sul |
| MG | Minas Gerais |
| PA | Pará |
| PB | Paraíba |
| PR | Paraná |
| PE | Pernambuco |
| PI | Piauí |
| RJ | Rio de Janeiro |
| RN | Rio Grande do Norte |
| RS | Rio Grande do Sul |
| RO | Rondônia |
| RR | Roraima |
| SC | Santa Catarina |
| SP | São Paulo |
| SE | Sergipe |
| TO | Tocantins |
emissaoDCe.ambienteProducao.tipoEmitenteDC-e 发行方类型
不区分大小写。
| 取值 | 含义 |
|---|---|
| Marketplace | 代第三方发行的电商平台;须传 siteMarketplace |
| OwnIssuer | 企业自发 |
| EmissorProprio | 同 OwnIssuer |
| Carrier | 承运商;可登记,发行被 10019013 拒 |
| Transportadora | 同 Carrier |
emissaoNFSe.regimeApuracaoSnSimples 计税口径
只对 ME/EPP:optanteSimplesNacional=true 且 mei=false。
| 取值 | 含义 |
|---|---|
| 1 | 联邦税与市政 ISS 均按 Simples 计 |
| 2 | 联邦税按 Simples 计,ISS 按市政固定额 |
| 3 | 联邦税按 Simples 计,ISS 按市政常规税率 |
emissaoNFSe.regimeEspecialTributacao特殊税制
不传即 0。
| 取值 | 含义 |
|---|---|
| 0 | 无 |
| 1 | 合作社行为 |
| 2 | 核定征收 |
| 3 | 市政微型企业 |
| 4 | 公证登记 |
| 5 | 自由职业者 |
| 6 | 专业人士合伙 |
| 错误码 | HTTP | |
|---|---|---|
| 10003002 | 400 | CNPJ 已注册。该主体已存在,直接使用原 empresaId 或带 id 更新。 |
| 10003000 | 404 | 更新:id 不存在或非本应用名下。 |
| 10003006 | 400 | 缺必填资料:开 NF-e / DC-e 的主体缺 inscricaoEstadual,或 tipoEmitente=Marketplace 缺 siteMarketplace。消息点名字段。 |
| 10003004 | 400 | 城市与州解析不到 IBGE 码。核对 endereco.uf 与 endereco.cidade。 |
| 10001001 | 400 | 请求字段校验失败(每字段一条),或契约错误:没有配置块、tipoEmitente 不合法、更新改 cnpj 或换市政、sequencialDCe 低于当前、换系列。按 mensagem 修正。 |
