Webhooks
注册 Webhook
注册或更新接收开票结果等事件的回调 URL。
/openapi/v1/webhookstoken、timestamp、sign 三个签名头,参见认证与签名。每个应用只有一份回调配置:webHookId 即应用标识,再次调用会覆盖配置。它与控制台里编辑的是同一份配置:在这里注册还是在控制台保存,效果完全一致,后保存的覆盖先保存的;回调格式只由事件类型决定。连续投递失败触发熔断后,再次调用注册接口即可恢复投递。投递模型、验签与重试策略见 Webhooks。
请求体
id*更新时必填。 | string | Webhook 标识 |
uri* | string | 回调地址 |
contentType* | string | 回调正文格式 |
token* | string | 校验令牌 |
eventos | array | 订阅事件 |
* 必填字段
webHookId | string | Webhook 标识 |
平台向 uri 发起 POST,JSON 请求体(Content-Type: application/json; charset=utf-8)。10 秒内返回 HTTP 2xx 视为投递成功;其他响应按 1 分钟、5 分钟、30 分钟、2 小时、6 小时重试。连续失败 10 次会停用该 Webhook,再次调用本注册接口即恢复投递并清零计数。Node.js 与 Java 的验签示例见 Webhooks。
每次投递的请求头
按事件 id 去重,对原始请求体字节验签。
{"Content-Type": "application/json; charset=utf-8","X-Tffiscal-Event": "invoice.authorized","X-Tffiscal-Event-Id": "1950000000000001","X-Tffiscal-Delivery-Id": "1950000000000002","X-Tffiscal-Timestamp": "1758200000","X-Tffiscal-Signature": "9f2c...e1","token": "dGt6eXp5ZGRra2tzc3Nra2hoaGFha2tha2FhamFoaGFoNzc3Nz","x-token": "dGt6eXp5ZGRra2tzc3Nra2hoaGFha2tha2FhamFoaGFoNzc3Nz"}
X-Tffiscal-Event* | string | 事件编码 |
X-Tffiscal-Event-Id* | string | 事件 id |
X-Tffiscal-Delivery-Id* | string | 投递 id |
X-Tffiscal-Timestamp* | string | 签名时间戳 |
X-Tffiscal-Signature* | string | 签名 |
token*设置了令牌时。 | string | 校验令牌 |
x-token*设置了令牌时。 | string | 令牌副本 |
* 必填字段
载荷有两种格式。结果对象是无包装的 JSON 对象,首字段为 tipo(NF-e / NFC-e / CT-e / DC-e / NFS-e),各单据的授权、驳回、取消事件用它;它没有 event_id,请按请求头去重。统一事件体(version / event_id / event_type / occurred_at / data)用于 invoice.canceled、invoice.cce.registered、invoice.verify.completed、cte.event.registered、nfce.device.*、nfse.inbound.* 各事件、email.sent / email.failed 与 tax_class.incompatible。无值的字段以 null 出现。
NF-e 结果对象
事件 invoice.authorized 与 invoice.rejected。驳回时链接、授权时间与协议号为空。
{"tipo": "NF-e","empresaId": "1934811222334455","nfeId": "NFe-000014553","nfeStatus": "Autorizada","nfeMotivoStatus": null,"nfeLinkDanfe": "https://api.v2.tffiscal.com/openapi/files/danfe/35241204893402000113650010000117691017244265?token=...","nfeLinkXml": "https://api.v2.tffiscal.com/openapi/files/xml/8801?token=...","nfeNumero": "11769","nfeSerie": "10","nfeChaveAcesso": "35241204893402000113650010000117691017244265","nfeDataEmissao": "2024-12-04T17:44:26Z","nfeDataAutorizacao": "2024-12-04T17:44:26Z","nfeNumeroProtocolo": "135240002599237","nfeDigestValue": null}
tipo* | string | 单据类型 |
empresaId* | string | 主体标识 |
nfeId* | string | 单据 id |
nfeStatus* | string | 结果状态 |
nfeMotivoStatus | string | 驳回原因 |
nfeLinkDanfe | string | DANFE 下载链接 |
nfeLinkXml | string | 授权 XML 下载链接 |
nfeNumero | string | 票号 |
nfeSerie | string | 系列号 |
nfeChaveAcesso | string | 访问密钥 |
nfeDataEmissao* | string | 开票时间 |
nfeDataAutorizacao | string | 授权时间 |
nfeNumeroProtocolo | string | 授权协议号 |
nfeDigestValue | string | 签名摘要 |
* 必填字段
NFC-e 结果对象
nfce.authorized、nfce.rejected、nfce.canceled、nfce.cancel_rejected、nfce.contingency_issued 五个事件。字段名与 NF-e 相同,tipo 为 NFC-e,没有 nfeDigestValue,另带 nfeQrCode;无值字段为 null。
{"tipo": "NFC-e","empresaId": "1934811222334455","nfeId": "PDV01-000123","nfeStatus": "Autorizada","nfeMotivoStatus": null,"nfeLinkDanfe": "https://api.v2.tffiscal.com/openapi/files/danfce/35261111222333000181650010000001231123456780?token=...","nfeLinkXml": "https://api.v2.tffiscal.com/openapi/files/xml/12?token=...","nfeNumero": "123","nfeSerie": "1","nfeChaveAcesso": "35261111222333000181650010000001231123456780","nfeDataEmissao": "2026-11-10T14:00:00Z","nfeDataAutorizacao": "2026-11-10T14:00:02Z","nfeNumeroProtocolo": "135260000000123","nfeQrCode": "https://www.homologacao.nfce.fazenda.sp.gov.br/qrcode?p=35261111222333000181650010000001231123456780|3|2"}
tipo* | string | 单据类型 |
empresaId* | string | 主体标识 |
nfeId* | string | NFC-e 标识 |
nfeStatus* | string | 结果状态 |
nfeMotivoStatus | string | 原因 |
nfeLinkDanfe | string | 小票 PDF 下载链接 |
nfeLinkXml | string | XML 下载链接 |
nfeNumero | string | 票号 |
nfeSerie | string | 系列号 |
nfeChaveAcesso | string | 访问密钥 |
nfeDataEmissao | string | 开票时间 |
nfeDataAutorizacao | string | 授权时间 |
nfeNumeroProtocolo | string | 协议号 |
nfeQrCode | string | 二维码内容 |
* 必填字段
NFS-e 结果对象
事件 nfse.authorized、nfse.rejected、nfse.canceled、nfse.cancel_requested、nfse.cancel_denied 与 nfse.substituted;各自的 nfseStatus 见枚举。
{"tipo": "NFS-e","empresaId": "1001","nfseId": "PED-20260918-001","nfseStatus": "Autorizada","nfseMotivoStatus": null,"nfseLinkDanfse": "https://api.v2.tffiscal.com/openapi/files/danfse/35503082406730610001340000000000000000000000000077?token=...","nfseLinkXml": "https://api.v2.tffiscal.com/openapi/files/xml/9001?token=...","nfseNumero": "1287","nfseSerie": "1","nfseChaveAcesso": "35503082406730610001340000000000000000000000000077","nfseIdentificacaoDps": "DPS355030824067306100013400001000000000000042","nfseDataEmissao": "2026-09-18T13:00:00Z","nfseDataAutorizacao": "2026-09-18T13:00:03Z","nfseNumeroProtocolo": null,"nfseAtualizadoEm": "2026-09-18T13:00:03Z"}
tipo* | string | 单据类型 |
empresaId* | string | 主体标识 |
nfseId* | string | 单据 id |
nfseStatus* | string | 结果状态 |
nfseMotivoStatus | string | 结论说明 |
nfseLinkDanfse | string | DANFSe 下载链接 |
nfseLinkXml | string | 官方 XML 下载链接 |
nfseNumero | string | 票号 |
nfseSerie | string | 系列号 |
nfseChaveAcesso | string | 访问密钥 |
nfseIdentificacaoDps | string | DPS 标识 |
nfseDataEmissao* | string | 开票时间 |
nfseDataAutorizacao | string | 授权时间 |
nfseNumeroProtocolo | string | 发行方协议号 |
nfseAtualizadoEm* | string | 本次状态变更时刻 |
nfseChaveSubstituta*仅 nfse.substituted。 | string | 替代票密钥 |
* 必填字段
CT-e 结果对象
事件 cte.authorized、cte.rejected 与 cte.canceled。平台侧终局失败不发回调,请用 CT-e 查询接口。
{"tipo": "CT-e","empresaId": "1934811222334455","cteId": "CTe-000000321","cteStatus": "Autorizada","cteMotivoStatus": null,"cteLinkDacte": "https://api.v2.tffiscal.com/openapi/files/dacte/35260940673061000134570010000003211000000325?token=...","cteLinkXml": "https://api.v2.tffiscal.com/openapi/files/xml/7701?token=...","cteNumero": "321","cteSerie": "1","cteChaveAcesso": "35260940673061000134570010000003211000000325","cteDataEmissao": "2026-09-06T12:00:00Z","cteDataAutorizacao": "2026-09-06T12:00:04Z","cteNumeroProtocolo": "135260000000321","cteDigestValue": "tasG40Ic6Zh7PIBiLEEH7Hb940Y="}
tipo* | string | 单据类型 |
empresaId* | string | 主体标识 |
cteId* | string | 单据 id |
cteStatus* | string | 结果状态 |
cteMotivoStatus | string | 驳回原因 |
cteLinkDacte | string | DACTE 下载链接 |
cteLinkXml | string | 授权 XML 下载链接 |
cteNumero | string | 单据号 |
cteSerie | string | 系列号 |
cteChaveAcesso | string | 访问密钥 |
cteDataEmissao* | string | 发行时间 |
cteDataAutorizacao | string | 授权时间 |
cteNumeroProtocolo | string | 授权协议号 |
cteDigestValue | string | 授权 XML 的签名摘要 |
* 必填字段
DC-e 结果对象
事件 dce.authorized、dce.rejected、dce.canceled 与 dce.cancel_rejected。编号前失败同样以 dce.rejected 到达,单据字段为 null。
{"tipo": "DC-e","empresaId": "1934811222334455","dceId": "DCe-000012333","dceStatus": "Autorizada","dceMotivoStatus": null,"dceLinkDace": "https://api.v2.tffiscal.com/openapi/files/dace/41260940673061000134990010000000011101234565?token=...","dceLinkXml": "https://api.v2.tffiscal.com/openapi/files/xml/7?token=...","dceNumero": "1","dceSerie": "1","dceChaveAcesso": "41260940673061000134990010000000011101234565","dceDataEmissao": "2026-09-06T12:00:00Z","dceDataAutorizacao": "2026-09-06T12:00:03Z","dceNumeroProtocolo": "141260000000001","dceDigestValue": "tasG40Ic6Zh7PIBiLEEH7Hb940Y="}
tipo* | string | 单据类型 |
empresaId* | string | 主体标识 |
dceId* | string | 单据 id |
dceStatus* | string | 结果状态 |
dceMotivoStatus | string | 结论说明 |
dceLinkDace | string | DACE 下载链接 |
dceLinkXml | string | 授权 XML 下载链接 |
dceNumero | string | 单据号 |
dceSerie | string | 系列号 |
dceChaveAcesso | string | 访问密钥 |
dceDataEmissao* | string | 发行时间 |
dceDataAutorizacao | string | 授权时间 |
dceNumeroProtocolo | string | 协议号 |
dceDigestValue | string | 授权 XML 的签名摘要 |
* 必填字段
统一事件体
以 invoice.canceled 为例:data 含 invoice_id、chave、protocolo。cte.event.registered 的 data 含 event_code、n_seq、protocolo;invoice.cce.registered含 invoice_id、chave、n_seq。
{"version": "1.0","event_id": "1950000000000001","event_type": "invoice.canceled","occurred_at": "2026-09-06T13:00:00Z","data": {"invoice_id": "1934811222330001","chave": "35241204893402000113650010000117691017244265","protocolo": "135260000000099"}}
version* | string | 统一事件体的版本 |
event_id* | string | 事件 id |
event_type* | string | 事件编码 |
occurred_at* | string | 事件时间 |
data* | object | 事件数据 |
* 必填字段
进项 NFS-e 的 data
nfse.inbound.received、nfse.inbound.canceled、nfse.inbound.substituted 需显式订阅。三者都带 inbound_id、chave、prestador_doc;示例为到达事件。
{"version": "1.0","event_id": "1950000000000003","event_type": "nfse.inbound.received","occurred_at": "2026-09-21T12:15:41Z","data": {"inbound_id": "1950000000000777","chave": "35095022112223330001810000100000000000007710001232","prestador_doc": "40673061000134","n_nfse": "77","valor_servico": "1000.00","competencia": "2026-09-01"}}
inbound_id* | string | 进项票平台 id |
chave* | string | 访问密钥 |
prestador_doc* | string | 开票方证件号 |
n_nfse*仅 nfse.inbound.received。 | string | 票号 |
valor_servico*仅 nfse.inbound.received。 | string | 服务金额 |
competencia*仅 nfse.inbound.received。 | string | 服务归属月 |
evento*仅 nfse.inbound.canceled。 | string | 取消事件官方码 |
chave_substituta*仅 nfse.inbound.substituted。 | string | 替代票密钥 |
* 必填字段
表态结果的 data
nfse.inbound.manifested 表示表态已登记;nfse.inbound.manifest_failed 表示任务失败,请在默示确认期限前重新表态。两者都需显式订阅;示例为成功事件。
{"version": "1.0","event_id": "1950000000000004","event_type": "nfse.inbound.manifested","occurred_at": "2026-09-21T14:00:05Z","data": {"inbound_id": "1950000000000777","chave": "35095022112223330001810000100000000000007710001232","tipo": "Rejeicao","evento": "203206","codigo_motivo": "3","motivo": "Servico nao prestado ao tomador","protocolo": "3550308000000000000000000000000000000000000000000001"}}
inbound_id*仅 nfse.inbound.manifested。 | string | 进项票平台 id |
chave* | string | 访问密钥 |
tipo* | string | 表态类型 |
evento*仅 nfse.inbound.manifested。 | string | 登记的事件官方码 |
codigo_motivo*仅 nfse.inbound.manifested。 | string | 拒绝原因码 |
motivo* | string | 原因说明 |
protocolo*仅 nfse.inbound.manifested。 | string | 发行方登记号 |
codigo*仅 nfse.inbound.manifest_failed。 | string | 失败码 |
* 必填字段
验证结论的 data
invoice.verify.completed 是 NF-e 验证最终结论的唯一推送通道,按密钥查询可作兜底。同一 chave 可能先后产生多条事件(强制重验、超过复用时限后的重复提交、后台复核),以 occurred_at 最新的一条为准;复用已有结论时不推送新事件,见 NF-e 验证。
{"version": "1.0","event_id": "1950000000000005","event_type": "invoice.verify.completed","occurred_at": "2026-07-23T17:16:23Z","data": {"chaveAcesso": "35260764962869000108550990001366171195929648","validationStatus": "VALIDATED","status": "Autorizada","cStat": "100","xMotivo": "Autorizado o uso da NF-e","protocolo": { "numero": "135262955451772", "digestValue": "oAEE...HwY=" },"dataAutorizacao": "2026-07-23T14:30:09Z","eventos": [],"verifiedAt": "2026-07-23T17:16:23Z"}}
chaveAcesso* | string | 被验证发票密钥 |
validationStatus* | string | 最终结论 |
status* | string | SEFAZ 税务状态 |
cStat | string | SEFAZ 返回码 |
xMotivo | string | SEFAZ 返回说明 |
protocolo | object | 官方协议 |
dataAutorizacao | string | SEFAZ 授权时间 |
eventos* | array | 已登记税务事件 |
verifiedAt* | string | 核验完成时间 |
reason*仅 REJECTED / VALIDATION_ERROR。 | string | 结论说明 |
* 必填字段
SEFAZ 不受理查询时的结论
SEFAZ 不受理这张票的查询(如 cStat 526,开具时间过久)时,data 的 validationStatus 为 VALIDATION_ERROR、status 为 Desconhecida,reason 以 SEFAZ does not answer this chave 开头。这不是对发票的判定;结论一直复用,重复提交不会改变。
{"chaveAcesso": "31241064962869000108550990001366171195929642","validationStatus": "VALIDATION_ERROR","status": "Desconhecida","cStat": "526","xMotivo": "Rejeição: Consulta a uma Chave de Acesso muito antiga","protocolo": null,"dataAutorizacao": null,"eventos": [],"verifiedAt": "2026-07-23T17:16:23Z","reason": "SEFAZ does not answer this chave (cStat=526: Rejeicao: Consulta a uma Chave de Acesso muito antiga), not retryable"}
发票邮件结果的 data
email.sent 表示发信服务已接收;email.failed 表示邮件终态失败(等待超时、重试用尽、票已不再授权)。两者都需显式订阅,收到任一即可对同一张票再次发送;示例为成功事件。见发票邮件。
{"version": "1.0","event_id": "1950000000000006","event_type": "email.sent","occurred_at": "2026-09-28T12:00:31Z","data": {"email_id": "2103160000000000001","id": "email-pedido-8842-1","tipo_documento": "NFe","documento_id": "pedido-8842","chave": "35241204893402000113650010000117691017244265","destinatarios": ["comprador@exemplo.com"],"status": "Enviado","motivo_falha": null}}
email_id* | string | 邮件标识 |
id* | string | 请求标识 |
tipo_documento* | string | 发票类型 |
documento_id* | string | 单据标识 |
chave | string | 访问密钥 |
destinatarios* | array | 实际收件邮箱 |
status* | string | 结果状态 |
motivo_falha | string | 失败原因 |
* 必填字段
税种需更新的 data
主体 CRT、计税制度或档案 percentualCreditoSimples 变化导致税种不符时推送 tax_class.incompatible。只在从 Compativel 变为 IncompativelComRegime 时推一次,只投递给在 eventos 里列出它的应用。按新税制整份替换税种后即可继续引用。
{"version": "1.0","event_id": "1950000000000101","event_type": "tax_class.incompatible","occurred_at": "2026-11-16T18:20:05Z","data": {"empresa_id": "2095175851237711874","codigo": "TF4440123455","tipo": "NFe","versao": 3,"situacao": "IncompativelComRegime","motivos": [{"grupo": "icms","linha": 0,"campo": "situacaoTributaria","codigoErro": "10004046","crt": 1,"regimeTributario": 1,"mensagem": "..."}]}}
empresa_id* | string | 主体标识 |
codigo* | string | 税种编号 |
tipo* | string | 税种类型 |
versao* | int | 税种当前版本 |
situacao* | string | 税种状态 |
motivos* | array | 不符原因 |
* 必填字段
eventos[]事件编码
不传只订 invoice.authorized 与 invoice.rejected。NFC-e 不在缺省订阅里,要收 NFC-e 回调必须显式列出 nfce.* 事件。nfse.inbound.*、email.* 与 tax_class.incompatible 只投递给在此列出它们的应用。
| 取值 | 含义 |
|---|---|
| invoice.authorized | NF-e 被 SEFAZ 授权;结果对象,nfeStatus = Autorizada |
| invoice.rejected | NF-e 被 SEFAZ 驳回;nfeStatus = Negada,原因在 nfeMotivoStatus |
| invoice.canceled | NF-e 取消在 SEFAZ 登记完成;统一事件体,data 含 invoice_id、chave、protocolo |
| invoice.cce.registered | NF-e 更正函已在 SEFAZ 登记;统一事件体,含 invoice_id、chave、n_seq,需显式订阅 |
| invoice.verify.completed | NF-e 验证得出最终结论;统一事件体,data 含 validationStatus |
| cte.authorized | CT-e 授权通过;cteStatus = Autorizada |
| cte.rejected | CT-e 被 SEFAZ 驳回;cteStatus = Negada |
| cte.canceled | CT-e 取消登记完成;cteStatus = Cancelada |
| cte.event.registered | CT-e 其他事件登记成功(更正函、送达凭证、服务异议);统一事件体,data 含 event_code、n_seq、protocolo |
| dce.authorized | DC-e 授权通过;dceStatus = Autorizada |
| dce.rejected | DC-e 被 SEFAZ 驳回或发行终局失败;dceStatus = Negada |
| dce.canceled | DC-e 取消登记成功;dceStatus = Cancelada |
| dce.cancel_rejected | DC-e 取消被 SEFAZ 拒绝或取消任务终局失败;dceStatus = CancelamentoNegado,单据仍已授权 |
| nfce.authorized | NFC-e 授权通过,含离线票补传后授权;结果对象,tipo = NFC-e,nfeStatus = Autorizada |
| nfce.rejected | NFC-e 被 SEFAZ 驳回或平台侧失败,含离线票补传被拒;nfeStatus = Negada |
| nfce.canceled | NFC-e 取消登记成功,含替代取消;nfeStatus = Cancelada |
| nfce.cancel_rejected | NFC-e 取消被 SEFAZ 拒绝;nfeStatus = CancelamentoNegado,票仍已授权 |
| nfce.contingency_issued | NFC-e 已离线开出:SEFAZ 不可用时由平台开出,或门店断网时在收银机开出、已补传到平台;nfeStatus = ContingenciaPendente,送 SEFAZ 后再推 nfce.authorized 或 nfce.rejected |
| nfce.device.activated | NFC-e 离线开票设备配对成功;统一事件体,data 为设备对象 |
| nfce.device.deactivated | NFC-e 离线开票设备被停用或被平台吊销;data.situacao 区分 |
| nfce.device.upload_overdue | 设备最早一张待补传离线票接近州补传时限;每台设备每天至多一次 |
| nfse.authorized | NFS-e 发行成功;nfseStatus = Autorizada |
| nfse.rejected | NFS-e 被发行方驳回或平台侧失败;nfseStatus = Negada |
| nfse.canceled | NFS-e 取消完成,含分析准予;nfseStatus = Cancelada |
| nfse.cancel_requested | NFS-e 取消分析申请已受理;nfseStatus = EmProcessoDeCancelamento |
| nfse.cancel_denied | NFS-e 取消未成功,票仍已授权:同步拒绝、重试耗尽或分析驳回;nfseStatus = Autorizada |
| nfse.substituted | NFS-e 被替代票取代;nfseStatus = Substituida,多一个 nfseChaveSubstituta |
| nfse.inbound.received | 进项 NFS-e 到达,本主体为接收方或中介方;统一事件体,需显式订阅 |
| nfse.inbound.canceled | 进项 NFS-e 被取消;统一事件体,需显式订阅 |
| nfse.inbound.substituted | 进项 NFS-e 被替代;统一事件体,需显式订阅 |
| nfse.inbound.manifested | 本主体表态登记成功,确认与拒绝都推;统一事件体,需显式订阅 |
| nfse.inbound.manifest_failed | 本主体表态登记失败;请在默示确认前重试;统一事件体,需显式订阅 |
| email.sent | 发票邮件已交发信服务;统一事件体,data.status = Enviado,需显式订阅 |
| tax_class.incompatible | 税种与主体新税制不符,需要更新;统一事件体,含 codigo、tipo、motivos,需显式订阅 |
| email.failed | 发票邮件终态失败;统一事件体,data.status = Falha,原因在 data.motivo_falha,需显式订阅 |
contentType回调正文格式
不区分大小写,首尾空格忽略。
| 取值 | 含义 |
|---|---|
| application/json | UTF-8 JSON 正文;唯一接受的取值,其他返回 10009033 |
X-Tffiscal-Event事件编码请求头
同样适用于统一事件体的 event_type。除上方事件编码表的全部编码外,只多这一个取值。
| 取值 | 含义 |
|---|---|
| webhook.verify | 控制台保存地址时的测试投递;不能在 eventos 中订阅 |
tipo结果对象的单据类型
| 取值 | 含义 |
|---|---|
| NF-e | 事件 invoice.authorized 与 invoice.rejected;字段 nfe* |
| NFC-e | 事件 nfce.*;字段与 NF-e 相同,均为 nfe*,另带 nfeQrCode |
| NFS-e | 六个销项 nfse.* 事件;字段 nfse* |
| CT-e | 事件 cte.authorized、cte.rejected、cte.canceled;字段 cte* |
| DC-e | 四个 dce.* 事件;字段 dce* |
nfeStatusNF-e 与 NFC-e 结果状态
NF-e 只会出现 Autorizada 与 Negada;其余三个仅 NFC-e,此时 tipo = NFC-e。NF-e 取消以统一事件体 invoice.canceled 推送。
| 取值 | 含义 |
|---|---|
| Autorizada | SEFAZ 已授权(invoice.authorized、nfce.authorized);NFC-e 含离线票补传后授权 |
| Negada | SEFAZ 驳回或取号前平台侧失败(invoice.rejected、nfce.rejected);原因在 nfeMotivoStatus |
| Cancelada | 仅 NFC-e:取消已登记,含替代取消(nfce.canceled) |
| CancelamentoNegado | 仅 NFC-e:SEFAZ 拒绝取消,票仍有效(nfce.cancel_rejected);原因在 nfeMotivoStatus |
| ContingenciaPendente | 仅 NFC-e:SEFAZ 不可用时离线开出;小票可当场交付,补传后再推 Autorizada 或 Negada(nfce.contingency_issued) |
nfseStatusNFS-e 结果状态
| 取值 | 含义 |
|---|---|
| Autorizada | 发行成功(nfse.authorized)或取消被拒(nfse.cancel_denied) |
| Negada | 驳回或平台侧失败(nfse.rejected) |
| Cancelada | 已取消(nfse.canceled) |
| EmProcessoDeCancelamento | 取消分析申请中(nfse.cancel_requested) |
| Substituida | 已被替代(nfse.substituted) |
cteStatusCT-e 结果状态
| 取值 | 含义 |
|---|---|
| Autorizada | 已授权(cte.authorized) |
| Negada | SEFAZ 驳回(cte.rejected) |
| Cancelada | 已取消(cte.canceled) |
dceStatusDC-e 结果状态
| 取值 | 含义 |
|---|---|
| Autorizada | 已授权(dce.authorized) |
| Negada | 驳回或发行终局失败(dce.rejected) |
| Cancelada | 已取消(dce.canceled) |
| CancelamentoNegado | 取消被拒,单据仍已授权(dce.cancel_rejected) |
data.event_codeCT-e 事件代码
只出现在 cte.event.registered 的事件体里。CT-e 取消走 cte.canceled,EPEC 应急登记不发回调。
| 取值 | 含义 |
|---|---|
| 110110 | 信函更正 |
| 110180 | 交付凭证 |
| 110181 | 撤销交付凭证 |
| 110190 | 交付失败 |
| 110191 | 撤销交付失败 |
| 610110 | 服务不符,登记在他人开具的 CT-e 上 |
| 610111 | 撤销服务不符 |
data.validationStatus验证结论
| 取值 | 含义 |
|---|---|
| VALIDATED | 发票有效,可放行 |
| REJECTED | SEFAZ 判定发票无效,reason 说明原因 |
| VALIDATION_ERROR | 验证未能完成,不是对发票的判定。status 为 null 是核验通道故障,稍后带 forceRevalidate: true 重新提交;status 为 Desconhecida 是 SEFAZ 不受理该票的查询(如 cStat 526),重复提交不会改变结论 |
data.status被验证发票的 SEFAZ 税务状态
仅 invoice.verify.completed;结论为 VALIDATION_ERROR 时为 null。
| 取值 | 含义 |
|---|---|
| Autorizada | 已授权且有效 |
| Cancelada | 已被开票方取消 |
| Denegada | SEFAZ 拒绝使用 |
| Inutilizada | 号码已作废 |
| NaoEncontrada | SEFAZ 查无此密钥 |
| Desconhecida | 无法判定,例如未触达 SEFAZ |
version统一事件体版本
| 取值 | 含义 |
|---|---|
| 1.0 | 当前唯一版本;新增字段不改版本号 |
data.event_codeCT-e 已登记事件码
仅 cte.event.registered。取消走 cte.canceled,不在此列。
| 取值 | 含义 |
|---|---|
| 110110 | 更正函 |
| 110180 | 送达凭证 |
| 110181 | 撤销送达凭证 |
| 110190 | 投递失败 |
| 110191 | 撤销投递失败 |
| 610110 | 服务异议,由承担方登记 |
| 610111 | 撤销服务异议 |
data.evento进项 NFS-e 取消事件码
仅 nfse.inbound.canceled。替代取消走 nfse.inbound.substituted。
| 取值 | 含义 |
|---|---|
| 101101 | 开票方取消 |
| 105104 | 分析后准予取消 |
| 305101 | 市镇依职权取消 |
data.evento已登记表态事件码
仅 nfse.inbound.manifested;按本主体在票上的角色确定。
| 取值 | 含义 |
|---|---|
| 203202 | 接收方确认 |
| 203206 | 接收方拒绝 |
| 204203 | 中介方确认 |
| 204207 | 中介方拒绝 |
data.tipo表态类型
nfse.inbound.manifested 与 nfse.inbound.manifest_failed 都有。
| 取值 | 含义 |
|---|---|
| Confirmacao | 确认该票 |
| Rejeicao | 拒绝该票 |
data.tipo_documento邮件的发票类型
email.sent 与 email.failed 都有。
| 取值 | 含义 |
|---|---|
| NFe | NF-e 商品发票 |
| NFSe | NFS-e 服务发票 |
| CTe | CT-e 运输发票 |
| DCe | DC-e 内容申报 |
data.status发票邮件结果
| 取值 | 含义 |
|---|---|
| Enviado | 已交发信服务(email.sent);该票可再次发送 |
| Falha | 终态失败(email.failed);motivo_falha 说明原因,该票可再次发送 |
| 错误码 | HTTP | |
|---|---|---|
| 10009033 | 400 | 注册无效:id 不属于当前应用、contentType 不是 application/json 或 eventos 含未知编码;消息指明是哪一项。 |
| 10001001 | 400 | 字段校验失败:uri 或 token 为空或超长,token 含可见 ASCII 以外的字符(空格、重音字母、换行等),eventos 含空白项或超过 64 项。 |
