NF-e
代卖家开具 NF-e：端点顺序、状态口径、前置条件、幂等规则、支持范围、联调清单与排障。
概述
NF-e 端点代已注册主体开具商品发票（NF-e）：开票受理即返回并异步向 SEFAZ 授权，结果经 Webhook 或查询获知；已授权票可作废，也可登记更正函（CC-e）。
端点
开票前，主体须先通过注册主体完成注册，通过关联证书关联证书，并建议通过注册 Webhook登记回调地址。注册返回的 empresaId 是下列全部端点的路径变量。
| 步骤 | 端点 | 说明 |
|---|---|---|
| 1 开具 NF-e | POST /openapi/v2/empresas/{empresaId}/nf-e | 受理即返回，异步向 SEFAZ 授权 |
| 2 查询 NF-e | GET /openapi/v2/empresas/{empresaId}/nf-e/{nfeId} | 状态、票面、DANFE / XML 下载链接 |
| 3 作废 NF-e | DELETE /openapi/v2/empresas/{empresaId}/nf-e/{nfeId} | 授权后 24 小时内 |
| 4 登记更正函 | POST /openapi/v2/empresas/{empresaId}/nf-e/{nfeId}/carta-correcao | 授权后 720 小时内，同票最多 20 封，同步返回协议号 |
| 5 更正函列表 | GET /openapi/v2/empresas/{empresaId}/nf-e/{nfeId}/carta-correcao | 每封带回执 XML 与 DACCE 下载地址 |
所有请求都携带认证中描述的三个签名头；参与签名的 path 包含 /openapi 前缀与路径变量（empresaId / nfeId）。
状态口径
status | 含义 |
|---|---|
AguardandoAutorizacao | 受理后至 SEFAZ 返回前 |
Autorizada | SEFAZ 已授权；linkDanfe / linkDownloadXml 可用 |
Negada | 被拒；motivoStatus 给出 SEFAZ 返回码与描述（如 778 - Rejeicao: NCM inexistente），修正后重新提交 |
Cancelada | 作废成功后 |
授权与驳回结果也会投递到回调地址，载荷格式见 Webhooks。
主体状态与开票前提
注册接口把主体提交到平台审核队列；运营审批通过、且证书关联成功后主体方可开票。审批前开票会收到错误码 10004004（主体不可开票）。审批进度请与平台运营确认。
每个主体有一个当前环境（认证测试 Homologacao / 生产 Producao），新注册主体默认认证测试；切生产由平台运营操作。开票请求里的 ambienteEmissao 必须与主体当前环境一致，不一致返回 10004030，这是防止测试票误开进生产的硬校验。参见环境。
幂等与重发
开票受理即返回 HTTP 200 无响应体，进入异步开票流程；结果经 Webhook 或查询接口获知。同一 id 重复提交复用原任务；若上一次开票已失败（Negada），同一 id 修正字段后重提会按新报文重新开票，无需换 id。上一次仍在处理或已授权时改动收件人等关键字段重提则拒 10004032。
支持范围
| 项 | 支持情况 |
|---|---|
| 开票目的 | 正常票与退货票（finalidade=Normal / Devolucao）；补充 / 调整票暂不支持 |
| 收件人 | CPF 买方；CNPJ 买方须携带 inscricaoEstadual（ICMS 纳税人） |
| 消费者在场方式 | 仅 OperacaoPelaInternet |
| 支付方式 | 一笔或多笔，各笔 valor 之和须等于发票总额；卡组织信息不写入报文 |
| 运费 | 固定无运输（modFrete=9） |
| 税率 | 税码 + 可选税率参数直传；CRT=3 未传从价税率由平台按税率表补，CSOSN 101/201 的 pCredSN 可用主体档案兜底 |
| DANFE 链接 | 查询响应中提供，授权回调中以 nfeLinkDanfe 提供；PDF 在首次下载时渲染 |
| 更正函（CC-e） | 登记与列表，同步返回协议号，含 DACCE 凭证；仍不推送 invoice.cce.registered 回调 |
digestValue / 收件人电话 / 补充说明 | 当前不提供 |
联调清单
- 注册主体 → 200 +
empresaId；同 CNPJ 再注册 → 400 +10003002。 - 关联证书 → 200 无内容；错密码 → 400 +
CER0005。 - 登记 Webhook → 200 +
webHookId。 - 审批通过后，用
ambienteEmissao=Homologacao开票 → 200 无内容；随后查询 →AguardandoAutorizacao变Autorizada，linkDanfe/linkDownloadXml可下载。 - 收到授权回调：请求头
token与注册值一致，载荷nfeStatus=Autorizada。 - 反向用例：
ambienteEmissao=Producao→ 400 +10004030；presencaConsumidor=OperacaoPresencial→ 400 +10004031。 - 作废刚授权的票 → 200；再查询 →
Cancelada；作废不存在的 id → 404 +NFe0001。 - 失败路径：错误
sign→ 401 +10009003；未订阅端点 → 403 +10009005。
排障
签名不匹配（401，10009003）？
见认证的排障章节。
开票一直 AguardandoAutorizacao？
主体环境为认证测试时依赖 SEFAZ 认证环境可用性；持续超过数分钟请带 empresaId 与 nfeId 联系平台。
开票返回 10004004？
主体尚未审批通过或证书未关联 / 已过期。先完成注册接口后的审批与证书关联。
回调收不到？
确认 uri 为公网可达的 https/http 地址且返回 2xx；平台按退避重试并在连续失败后熔断，重新调用注册 Webhook即恢复。