NFS-e
取消 NFS-e
异步取消：窗口内登记取消事件，超窗口自动转税务分析申请。
/openapi/v2/empresas/{empresaId}/nfse/{nfseId}/cancelartoken、timestamp、sign 三个签名头，参见认证与签名。对 Autorizada 的票发起取消。本接口是异步的：HTTP 200 只回受理回执，结果经 nfse.canceled / nfse.cancel_requested / nfse.cancel_denied 回调或查询接口获知。平台按市镇窗口自行决定是登记取消事件还是转税务分析申请。请求体可以不传。
路径参数
empresaId* | string | 主体标识 |
nfseId* | string | 单据 id |
* 必填字段
请求体
codigoMotivo | string | 取消原因码 |
motivo | string | 取消事由 |
* 必填字段
nfseTaskId | int | 平台任务 id |
status | int | 任务状态 |
reused | bool | 是否复用原任务 |
createTime | string | 受理时刻 |
两种情形的请求体完全一样，走哪条路由平台按市镇取消窗口决定，窗口从授权时刻起算。只有 Autorizada 的票可以取消。
窗口内：登记取消事件
平台登记官方事件 101101。成功：票转 Cancelada，推送 nfse.canceled，查询里多一条 Cancelamento 事件。发行方同步拒绝：票仍为 Autorizada，推送 nfse.cancel_denied。
{"codigoMotivo": "1","motivo": "Erro no valor informado pelo cliente"}
codigoMotivo | string | 取消原因码 |
motivo | string | 取消事由 |
* 必填字段
超窗口：转税务分析申请
平台自动改提分析申请 101103。票转 EmProcessoDeCancelamento，推送 nfse.cancel_requested，查询里多一条 PedidoAnalise 事件。由市镇裁决：准予则票转 Cancelada，事件 AnaliseDeferida，推送 nfse.canceled；驳回则票回到 Autorizada，事件 AnaliseIndeferida，推送 nfse.cancel_denied。发起时不要把票当作已取消入账。
{"codigoMotivo": "2","motivo": "Servico nao prestado ao tomador"}
codigoMotivo | string | 取消原因码 |
motivo | string | 取消事由 |
* 必填字段
圣保罗通道
圣保罗市政系统没有取消窗口也没有分析申请：取消直接登记到市政系统，结果是 Cancelada 并推送 nfse.canceled，或被拒并推送 nfse.cancel_denied。
本接口的 HTTP 200 只是受理回执。结果经下面的回调（NFS-e 结果对象，见注册 Webhook）或查询接口获知，查询的 motivoStatus 带发行方结论。取消报文不符合官方格式时任务失败并记 10018064，不登记事件；请核对 motivo 长度与字符集。
取消成功：nfse.canceled
取消事件登记成功或分析准予。
{"tipo": "NFS-e","empresaId": "1001","nfseId": "PED-20260918-001","nfseStatus": "Cancelada","nfseMotivoStatus": null,"nfseChaveAcesso": "35503082406730610001340000000000000000000000000077","nfseDataAutorizacao": "2026-09-19T10:00:00Z","nfseNumeroProtocolo": "3550308000000000000000000000000000000000000000000001","nfseAtualizadoEm": "2026-09-19T10:00:00Z"}
nfseStatus* | string | 事件后的单据状态 |
nfseMotivoStatus | string | 结论说明 |
nfseNumeroProtocolo | string | 事件登记号 |
nfseAtualizadoEm* | string | 本次变更时刻 |
* 必填字段
分析申请已受理：nfse.cancel_requested
等市镇裁决，此前票仍然有效。
{"tipo": "NFS-e","empresaId": "1001","nfseId": "PED-20260918-001","nfseStatus": "EmProcessoDeCancelamento","nfseMotivoStatus": null,"nfseChaveAcesso": "35503082406730610001340000000000000000000000000077","nfseNumeroProtocolo": "3550308000000000000000000000000000000000000000000002","nfseAtualizadoEm": "2026-09-19T10:00:00Z"}
nfseStatus* | string | 事件后的单据状态 |
nfseMotivoStatus | string | 结论说明 |
nfseNumeroProtocolo | string | 事件登记号 |
nfseAtualizadoEm* | string | 本次变更时刻 |
* 必填字段
取消被拒：nfse.cancel_denied
发行方同步拒绝、出站重试耗尽或分析被驳回。票仍为 Autorizada。
{"tipo": "NFS-e","empresaId": "1001","nfseId": "PED-20260918-001","nfseStatus": "Autorizada","nfseMotivoStatus": "105105 - Pedido de analise de cancelamento indeferido","nfseChaveAcesso": "35503082406730610001340000000000000000000000000077","nfseNumeroProtocolo": "3550308000000000000000000000000000000000000000000003","nfseAtualizadoEm": "2026-09-20T09:00:00Z"}
nfseStatus* | string | 事件后的单据状态 |
nfseMotivoStatus | string | 结论说明 |
nfseNumeroProtocolo | string | 事件登记号 |
nfseAtualizadoEm* | string | 本次变更时刻 |
* 必填字段
Pendente ─┬─► Negada├─► Falha└─► Autorizada ─┬─► Cancelada├─► EmProcessoDeCancelamento ─┬─► Cancelada│ └─► Autorizada└─► Substituida
Negada、Falha、Cancelada、Substituida 是终态。各状态含义见查询 NFS-e的枚举。
codigoMotivo取消原因码
不传按 9。
| 取值 | 含义 |
|---|---|
| 1 | 开票错误 |
| 2 | 服务未提供 |
| 9 | 其他 |
status任务状态
| 取值 | 含义 |
|---|---|
| 0 | 待处理 |
| 1 | 处理中 |
| 2 | 成功 |
| 3 | 失败 |
nfseStatus取消相关回调里的状态
只列取消相关三个回调会带的取值；完整清单见注册 Webhook。
| 取值 | 含义 |
|---|---|
| Cancelada | 已取消（nfse.canceled） |
| EmProcessoDeCancelamento | 分析申请已受理，等市镇裁决（nfse.cancel_requested） |
| Autorizada | 取消被拒，票仍然有效（nfse.cancel_denied） |
| 错误码 | HTTP | |
|---|---|---|
| 10018002 | 404 | 单据不存在：nfseId 不属于本主体。核对 nfseId 与 empresaId。 |
| 10018003 | 404 | 单据不存在：nfseId 不属于本主体。核对 nfseId 与 empresaId。 |
| 10018001 | 400 | codigoMotivo 不在 1 / 2 / 9 之内。 |
| 10001001 | 400 | motivo 或 codigoMotivo 超过最大长度。 |
| 10018040 | 400 | 取消分析申请已在处理中。等市镇裁决。 |
| 10018041 | 400 | 该票已被替代，不可再操作。 |
| 10018042 | 400 | 当前状态不允许取消：单据还在受理队列（查询为 Pendente）、已驳回、已失败或已取消。核对票状态，这不是 404。 |