NF-e

开具 NF-e

受理即返回，异步向 SEFAZ 授权。

POST/openapi/v2/empresas/{empresaId}/nf-e

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

受理即返回 HTTP 200 无响应体，进入异步开票流程；结果经 Webhook 或查询接口获知。同一 id 重复提交复用原任务；若上一次开票已失败（Negada），同一 id 修正字段后重提会按新报文重新开票，无需换 id；上一次仍在处理或已授权时改动收件人等关键字段重提则拒 10004032。鉴权错误（10009xxx）见认证。

参数

路径参数

empresaIdstring必填
注册主体返回的主体标识。
示例: 1934811222334455

请求体

idstring必填
开票请求唯一标识（集成方生成，最长 64），同时是查询 / 作废的 nfeId 与幂等键。
示例: NFe-000014553
ambienteEmissaostring必填
Homologacao / Producao，须与主体当前环境一致，否则 10004030。
finalidadestring可选
Normal（缺省）/ Devolucao 退货票，见退货票小节。
notaReferenciadaobject退货票必填
被退货原票的引用。
pedidoobject必填
订单信息。
clienteobject必填
收件人（买方）。
itensarray必填
商品行。

响应

200

受理成功，无响应体。SEFAZ 返回前发票处于 AguardandoAutorizacao。

无响应体

错误

错误码	HTTP
GW001	400	收件人 IBGE 市政码不存在。核对 UF 与 IBGE 码。
10003000	404	`empresaId` 不存在或非本应用名下。
10004004	400	主体不可开票（未审批通过或证书未就绪）。等待审批 / 关联证书。
10004030	400	`ambienteEmissao` 与主体当前环境不一致。按主体环境提交或联系运营切换。
10004031	400	不支持的取值（`presencaConsumidor` / 未知支付类型 / `tipoPessoa` 与证件不符 / CPF 买方携带 `inscricaoEstadual` / `IntegradoAoSistemaDeGestao`）。按支持范围调整。
10004032	400	上一次仍在处理或已授权时，同一 `id` 改动了关键字段重提。请换新 `id`。
10004002	400	该 CNPJ 待处理开票任务超限。稍后重试。
10005000	400	税务引擎校验拒绝（税制错配、ST 用于非纳税人、税率越界等）。见税码矩阵下的铁律。
10004020	400	CST 20/30/40/41/50/51/70/90 缺少 `codigoBeneficioFiscal`。
10004021	400	退货票：行缺 `notaReferenciada.numeroItem` 或单据缺 `notaReferenciada.chaveAcesso`。
10004022	400	非退货票携带行级引用。
10004023	400	原票不存在或不属本主体。
10004024	400	原票未授权。
10004025	400	原票行不存在。
10004026	400	数量超原票行（引用同一原票行的多行合计）。
10004034	400	CNPJ 买方未传 `cliente.inscricaoEstadual`。补买方 IE（ICMS 纳税人）。
10004043	400	契约字段缺失（减基比例 / ST MVA 与税率 / 递延比例 / 按量单位税额 / IPI 税码 / pCredSN 请求与档案皆无 / ST 商品缺 `cest`），mensagem 点名字段路径。按矩阵补字段。
10004044	400	字段不适用于该税码（非 ST 税码带 `substituicaoTributaria`、非抵免税码带 `percentualCreditoSimples`、CST 02/15/53/61 之外带 `monofasico`）。去掉该组。
10004045	400	CNPJ 买方的 `cliente.inscricaoEstadual` 不符合买方所在州的校验位规则（否则取号后被 SEFAZ 209 拒绝并烧号）。核对买方 IE 与州。
10004046	400	税码与主体税制不匹配（CRT 1/4 须三位 CSOSN，CRT 2/3 须两位 CST）。
10004047	400	非纳税人买方使用了只对纳税人合法的税码（10/30/70、101/201/202/203）或携带 pCredSN。改用 102 / 500 或不带抵免的 900。
10001001	400	请求字段校验失败（每字段一条）。按 `mensagem` 修正。

支付类型（`formas[].tipo`）

取值	含义
Dinheiro	现金
Cheque	支票
CartaoDeCredito	信用卡
CartaoDeDebito	借记卡
CreditoLoja	店铺信用
ValeAlimentacao	食品券
ValeRefeicao	餐券
ValePresente	礼品券
ValeCombustivel	燃油券
BoletoBancario	银行票据
DepositoBancario	银行存款
PagamentoInstantaneoPix	Pix
TransferenciaBancaria	银行转账
ProgramaDeFidelidade	忠诚计划
SemPagamento	无支付
Outros	其他

税码组

所有税参字段均可选（nullable），只传税码的请求行为不变。所有税参按「请求直传 > 主体档案 > 平台税率表（CRT=3）> 拒绝并点名字段路径」解析（itens[n].impostos...，n 从 1 起）。百分比按 18 表示 18 %，金额单位 BRL。平台不会推导减基比例、ST MVA、递延比例与按量单位税额：税码需要时必须直传。

组	适用税码
`icms`（自身字段）	全部；`aliquota` 用于 CST 00/10/20/51/70，`percentualReducaoBase` 用于 20/70，`percentualDiferimento` 用于 51，`percentualCreditoSimples` 用于 CSOSN 101/201，`codigoBeneficioFiscal` 用于 20/30/40/41/50/51/70/90
`icms.substituicaoTributaria`	CST 10/30/70、CSOSN 201/202/203（必需）；CST 90 / CSOSN 900（可选）；其他税码拒绝
`icms.retencaoAnterior`	CST 60、CSOSN 500
`icms.difal`	州际卖给非纳税人；未传时自动计算
`pis` / `cofins`	`aliquota` 用于 CST 01/02 与 50–75/98；`valorUnitarioTributo` 用于 CST 03
`ipi`	整组可选；传了本组即须带 `situacaoTributaria`

税码 × 必需参数矩阵

ICMS 税码	`aliquota`	`percentualReducaoBase`	`substituicaoTributaria.mva` + `.aliquota`	`percentualCreditoSimples`	`percentualDiferimento`
00	自动（CRT=3）	-	-	-	-
10	自动	-	必需	-	-
20	自动	必需	-	-	-
30	-	-	必需	-	-
40 / 41 / 50	-	-	-	-	-
51	自动	可选	-	-	必需
60	-	-	-	-	-
70	自动	必需	必需	-	-
90	按传参决定输出组	可选	可选	-	-
101	-	-	-	必需（或主体档案）	-
102 / 103 / 300 / 400	-	-	-	-	-
201	-	-	必需	必需	-
202 / 203	-	-	必需	-	-
500	-	-	-	-	-
900	按传参决定输出组	可选	可选	可选	-

PIS/COFINS 税码	`aliquota`	`valorUnitarioTributo`
01	自动（CRT=3 按制度）/ 其余必需	-
02	必需	-
03	-	必需
04–09	-	-
49 / 99	缺省 0	-
50–75 / 98（进项，退货票）	必需	-

铁律（由税务引擎校验，违反返回 10005000）：

卖方 CRT 1/4 必须用三位 CSOSN，CRT 2/3 必须用两位 CST，错配受理即拒 10004046；
非纳税人买方（个人 / 无 IE）不得使用 CSOSN 101 与代收 ST 族税码，也不得携带 percentualCreditoSimples，受理即拒 10004047；MEI 卖方（CRT 4）不得用 101；
ST 族税码（10/30/70、201/202/203）对非纳税人买方一律拒绝（SEFAZ cStat 600）：ST 是替下游转售环节预征，消费者是链条终点。B2C 销售 ST 商品应使用 CST 60 / CSOSN 500（前道已代收），跨州走 DIFAL；
州优惠码 cBenef：CST 20/30/40/41/50/51/70/90 必须携带 codigoBeneficioFiscal，缺失受理即拒 10004020。SEFAZ-SP 对同一集合校验 930（CST 90 不带码同样被拒），且不接受 SEM CBENEF（拒 946）；
非 ST 税码不得携带 substituicaoTributaria（10004044）；
ST 族税码（10/30/60/70、201/202/203/500）的商品必须传 cest，缺失受理即拒 10004043（itens[n].cest）；
CST 90 / CSOSN 900 为组合式：自身计税组、ST 组、抵免组至少提供一组。

收件人（`cliente`）

cliente.inscricaoEstadual 为买方州注册号 IE（NF-e dest/IE）。CNPJ 买方必需：决定 indIEDest=1；无 IE 的 CNPJ 买方在取号前拒 10004034（否则取号后被 SEFAZ 232 拒绝并烧号）。CPF 买方不得携带（拒 10004031）。可含格式符，平台归一化为数字。示例："123.456.789.012"。

B2B（买方为 ICMS 纳税人）场景由此打通：CSOSN 101 / 201、CST 10 / 30 / 70 等只对纳税人买方合法的税码需要本字段。

退货票

字段	类型	说明
`finalidade`	string	`"Normal"`（缺省）/ `"Devolucao"`。示例：`"Devolucao"`
`notaReferenciada.chaveAcesso`	string	被退货原票的 44 位访问密钥。`finalidade=Devolucao` 时必需
`itens[].notaReferenciada.numeroItem`	integer	对应原票的商品行号（`nItem`，从 1 起）。退货票每行必需

规则：退货行缺引用 → 10004021；非退货票带引用 → 10004022；原票不存在或不属本主体 → 10004023；原票未授权 → 10004024；原票行不存在 → 10004025；数量超原票行（引用同一原票行的多行合计）→ 10004026。使用进项 CFOP（1xxx / 2xxx）与进项 PIS/COFINS 税码（50–75 / 98，aliquota 必需）；原票的税参按行镜像。

json

{
  "id": "DEV-000014553",
  "ambienteEmissao": "Producao",
  "finalidade": "Devolucao",
  "notaReferenciada": { "chaveAcesso": "35241204893402000113650010000117691017244265" },
  "pedido": { "presencaConsumidor": "OperacaoPelaInternet", "pagamento": { "formas": [ { "tipo": "SemPagamento", "valor": 0 } ] } },
  "cliente": { "tipoPessoa": "F", "nome": "Demo Client", "cpfCnpj": "88533234775", "endereco": { "uf": "PR", "cidade": "4106902", "logradouro": "Rua Presidente Wilson", "numero": "911", "bairro": "Uberaba", "cep": "81570440" } },
  "itens": [
    {
      "cfop": "2202", "codigo": "000068", "descricao": "Pendrive Kingston 16GB", "ncm": "85235190",
      "quantidade": 1, "unidadeMedida": "UN", "valorUnitario": 28.47,
      "notaReferenciada": { "numeroItem": 1 },
      "impostos": {
        "icms": { "situacaoTributaria": "102" },
        "pis": { "situacaoTributaria": "70", "aliquota": 0 },
        "cofins": { "situacaoTributaria": "70", "aliquota": 0 }
      }
    }
  ]
}

完整示例：一般税制卖方（CRT=3），CST 20 减基 + PIS/COFINS 01

json

{
  "id": "NFe-000014554",
  "ambienteEmissao": "Producao",
  "pedido": { "presencaConsumidor": "OperacaoPelaInternet", "pagamento": { "formas": [ { "tipo": "PagamentoInstantaneoPix", "valor": 100.00 } ] } },
  "cliente": {
    "tipoPessoa": "J", "nome": "Revenda Demo LTDA", "cpfCnpj": "11222333000181", "inscricaoEstadual": "123456789012",
    "endereco": { "uf": "SP", "cidade": "3550308", "logradouro": "Av. Paulista", "numero": "1000", "bairro": "Bela Vista", "cep": "01310100" }
  },
  "itens": [
    {
      "cfop": "5102", "codigo": "SKU-100", "descricao": "Produto demo", "ncm": "85235190", "origem": 0,
      "quantidade": 2, "unidadeMedida": "UN", "valorUnitario": 50.00, "valorDesconto": 0,
      "impostos": {
        "icms": { "situacaoTributaria": "20", "aliquota": 18, "percentualReducaoBase": 33.33, "codigoBeneficioFiscal": "SP800001" },
        "pis": { "situacaoTributaria": "01", "aliquota": 1.65 },
        "cofins": { "situacaoTributaria": "01", "aliquota": 7.6 }
      }
    }
  ]
}

特殊税码组

可选；燃油、能源、特定州际操作与 2026 税改 IBS/CBS 覆盖。

组	适用	字段
`icms.monofasico`	ICMS CST 02 / 15 / 53 / 61 必需，其他税码不得携带（`10004044`）	`quantidadeBaseCalculo`、`aliquotaAdRem`（02/15/53 必需）、`quantidadeBaseCalculoRetencao`、`aliquotaAdRemRetencao`（15 必需）、`percentualReducaoAdRem` + `motivoReducaoAdRem`（成对，事由 1/9）、`quantidadeBaseCalculoRetida`、`aliquotaAdRemRetida`（61 必需）；53 的递延比例用 `icms.percentualDiferimento`
`icms.partilha`	CST 10 / 90 州际分成票，不与 FCP 并用	`percentualBaseCalculoOperacaoPropria`（pBCOp %）+ `ufSubstituicaoTributaria`（UFST），成对
`icms.substituicaoTributariaDestino`	CST 41 / 60 州际转拨，与 `retencaoAnterior` 同传	`baseCalculo`（vBCSTDest）+ `valor`（vICMSSTDest），成对
`icms.tributacaoEfetiva`	CST 60，部分州要求	`percentualReducaoBase`（pRedBCEfet）、`aliquota`（pICMSEfet，提供即输出效果组）
`pis.substituicaoTributaria` / `cofins.substituicaoTributaria`	代收 PIS/COFINS（PISST / COFINSST 组）	从价 `baseCalculo` + `aliquota` 或按量 `quantidadeBaseCalculo` + `valorUnitarioTributo`（二选一）；`somarAoTotal` 是否计入票面总额
`impostos.percentualCargaTributaria`	任意	近似税负比例 vTotTrib（%），未传按 IBPT 表计算
`impostos.ibsCbs`	2026 税改 IBS/CBS 覆盖；不传即按主体税制缺省（CST 000 / 分类码 000001）	`situacaoTributaria`（三位）、`classificacaoTributaria`（六位）、`percentualDiferimento`（510/515 必需）、`tributacaoRegular{situacaoTributaria, classificacaoTributaria}`、`transferenciaCredito{valorIbs, valorCbs}`（800）、`monofasico{...}`（620）、`zonaFrancaManaus{periodoApuracao, tipo, valor}`（810）、`ajuste{periodoApuracao, valorIbs, valorCbs}`（811）、`creditoPresumido{codigo, percentualIbs, percentualCbs, suspensivo, deduzir}`；一张票内要么全部行都传要么都不传

这些组的成对性、适用税码与按 CST 的 ad rem 必填由税务引擎校验，违反返回 10005000 并附内部字段名。