环境

网关基址

完整 URL = 基址 + 路径。签名中的 path 包含 /openapi 前缀（不含域名、不含查询串），见认证与签名。本文档全部示例均使用该基址。

主体环境（开票）

巴西电子税务凭证的开具面向 SEFAZ 的两套环境，平台把这一区分建模在主体上，而不是 API 域名上：

• 通过注册主体注册的每个主体都有一个当前环境。新注册主体默认为测试；切换到生产由 TF Fiscal 团队作为运营操作完成。
• 开票请求中的 ambienteEmissao 必须与主体当前环境一致。不一致时以 codigo 10004030 拒绝，这是防止测试票误开进生产的硬校验。
• 两个环境使用同一个 app_secret、同样的端点与同样的签名方案；只有主体状态与 ambienteEmissao 取值不同。
• 注册时提交的号段与系列即为开票所用；此后由平台维护序号。

验证与身份核验端点

NF-e 验证与身份核验端点没有环境开关：它们直接对接官方数据源。验证响应中的 ambienteEmissao（Producao / Homologacao）描述的是被提交的那张票，而不是调用方。

上生产的路径

1. 注册主体并关联证书。主体进入审批队列；审批前开票返回 10004004。
2. 在测试环境联调：用 ambienteEmissao=Homologacao 开票，接收授权回调，查询凭证并下载 linkDanfe / linkDownloadXml。逐项完成各凭证类型的联调清单，包括反向用例与一次作废。
3. 确认运行基础：服务器已做 NTP 校时（±300 秒时间戳窗口处处适用），Webhook URL 公网可达并返回 2xx，去重逻辑已就位。
4. 请运营将主体切换到生产，然后用 ambienteEmissao=Producao 开票。切换之前，Producao 请求返回 10004030。

注意： 平台产生的全部时间均为 UTC，与环境无关。

运行提示

• 主体处于测试环境时，开票时延取决于 SEFAZ 测试环境的可用性。若凭证停留在 AguardandoAutorizacao 超过数分钟，请携带 empresaId 与凭证 id 联系平台。
• 测试凭证的 Webhook 投递与生产遵循同样的契约、签名与重试节奏，见 Webhooks。