NFS-e

能力概述与接入流程

鉴权与 NF-e 完全相同：请求头 token / timestamp / sign，见认证与签名。

与 NF-e 的三点结构差异

1. 访问密钥是 50 位，且由发行方生成。 NF-e 的 44 位密钥由开票方自己算，NFS-e 的 50 位密钥要等发行方受理后才有。所以发行失败的单据没有 chaveAcesso，只能用 identificacaoDps（本方生成的 45 位 DPS 标识）定位。

2. 服务发票由市镇管辖。 平台按开票方所在市镇路由到对应通道，路由结果在查询响应的 padraoMunicipal 里。当前已支持国家标准（Nacional）与圣保罗市自有系统（Paulistana），未支持的市镇在受理时就会被拒（10018010），不会先受理再异步失败。

3. 取消有窗口，窗口外不是「不能取消」而是「走市政分析」。 见取消 NFS-e。

前提

• 主体须已审批通过、证书可用，否则受理即拒（10018004）。
• 主体须有 NFS-e 档案，由注册主体的 emissaoNFSe 段建立或由运营在控制台维护。Simples 归属、Simples 计税口径、特殊税制与 DPS 序列号永远取档案，开票请求不能传也不能覆盖；没有档案时受理即拒（10018005）。服务码、CNAE、NBS 等服务级字段不在档案里，随每张票传。
• 请求里的 ambienteEmissao 必须与主体当前环境一致，否则受理即拒。注册后主体处于认证测试环境（Homologacao），切生产是运营动作、不开 API。
• 计税取值以请求为准：请求给了就用请求的值，没给的才由平台查计税基础数据，如 LC 116 服务清单、联邦扣缴分类与税率、IBPT 近似税负。联邦扣缴、自身 PIS/COFINS 税率或 ISS 计税地要查的数据尚未导入时受理即拒 10018065，消息列出可改传的请求字段。
• 接收方是法人（CNPJ）时涉及联邦源泉扣缴：可在 servico.retencoes 直传扣缴额，0 表示声明无扣缴；金额与 pisCofins.tipoRetencao 都不传时由平台按服务的官方扣缴分类与接收方的 cliente.orgaoPublico、cliente.optanteSimplesNacional 自行判定；只传 pisCofins.tipoRetencao 不传金额会被拒（10018001）。判定所需信息不齐会显式拒绝（10018023）并一次列出全部缺项，而不是按 0 计。

圣保罗通道的额外约束

圣保罗主体（padraoMunicipal 为 Paulistana）须有市政登记号 CCM（inscricaoMunicipal）：档案里登记了就直接用；没登记时平台在受理期自动按 CNPJ 向市政系统查询并回填档案，只有查不到才受理即拒（10018005）。

该通道不支持折扣字段，请把折扣折进服务金额或扣减额；也不支持替代开票（市政 RPS 布局没有该组），请先取消原票再开新票，传了受理即拒（10018001）。

另有两项自动能力，不需要调用任何新接口：收到的圣保罗票由平台直连市政系统同步进进项列表（origem=PrefeituraSP，ADN 转录到达后自动合并）；在市政门户取消的销项票自动同步为 Cancelada，照常发 nfse.canceled。

状态机

                 ┌──────────────► Negada（终态）
                 │
Pendente ────────┼──────────────► Autorizada ──┬──► Cancelada（终态）
                 │                             │
                 └──────────────► Falha        ├──► EmProcessoDeCancelamento ──┬──► Cancelada
                   （取号前失败，无单据）        │                              └──► Autorizada（分析被驳回）
                                               └──► Substituida（被替代票取代）

进项票的表态状态

进项票的 status 沿用上表的 Autorizada / Cancelada / Substituida；本主体对它的表态另记在 manifestacao 块，一张票每方只能表态一次。

（未表态，列表过滤值 Pendente）──┬──► Confirmada（本方确认，终态）
                                 ├──► Rejeitada（本方拒绝）──► RejeicaoAnulada（市镇作废拒绝，终态）
                                 └──► ConfirmacaoTacita（市镇默示确认，终态）

Webhook 回调

在登记 Webhook 的地址上收到，载荷为无包装的 JSON 对象。

注意： 订阅语义。应用从未登记过任何订阅行时，销项六个事件全推；一旦为应用登记了任何一条订阅（例如订阅进项事件），该应用就进入白名单模式，只推显式开启的事件。订阅进项事件时请把需要的销项事件一并开启，否则销项通知会停在「暂存待认领」。

{
  "tipo": "NFS-e",
  "empresaId": "1001",
  "nfseId": "PED-20260918-001",
  "nfseStatus": "Autorizada",
  "nfseMotivoStatus": null,
  "nfseLinkDanfse": "https://api.v2.tffiscal.com/openapi/files/danfse/…",
  "nfseLinkXml": "https://api.v2.tffiscal.com/openapi/files/xml/9001?token=…",
  "nfseNumero": "1287",
  "nfseSerie": "1",
  "nfseChaveAcesso": "3550308…",
  "nfseIdentificacaoDps": "DPS3550308…",
  "nfseDataEmissao": "2026-09-18T13:00:00Z",
  "nfseDataAutorizacao": "2026-09-18T13:00:03Z",
  "nfseNumeroProtocolo": null,
  "nfseAtualizadoEm": "2026-09-18T13:00:03Z"
}

nfseAtualizadoEm 是本次状态变更的时刻。投递不保证顺序：重试、多实例都可能让旧事件晚于新事件到达。请把它与本地已知时刻比较，旧的直接丢弃，不要按到达顺序覆盖状态。

失败回调里 nfseChaveAcesso 可能为空（发行方从未生成密钥），此时用 nfseIdentificacaoDps 对账。取号前失败的回调连 nfseIdentificacaoDps 都为空，只能靠 nfseId 对账。

错误模型

对外端点返回无包装的数组：

[{"codigo": "10018012", "mensagem": "Codigo de servico fora da lista oficial LC 116: 999999"}]

鉴权与授权错误（10009xxx）见认证与签名，完整错误码表见错误码。

联调清单

1. 注册主体（带 emissaoNFSe）→ 关联证书 → 登记 Webhook。
2. 用 Homologacao 开一张最小票（只填必填项），确认收到 nfse.authorized 且能下载 XML 与 DANFSe。
3. 用同一个 id 再提交一次，确认没有开出第二张票。
4. 故意传一个不存在的服务码，确认收到 10018012 的同步拒绝，而不是异步 Negada。
5. 对已授权的票调用取消，确认按窗口走到 Cancelada 或 EmProcessoDeCancelamento。
6. 查询一张发行失败的票，确认能用 identificacaoDps 而不是 chaveAcesso 对上账。
7. 对一张进项票调表态传 tipo=Confirmacao，任务成功后查详情确认 manifestacao.status=Confirmada；再对同一票传 tipo=Rejeicao，确认收到 10018042（每方只能表态一次）。