TF Fiscal
开发文档

发票邮件

查询发票邮件

按受理返回的 emailId 查状态、等待或失败原因，以及实际发了什么。

GET/openapi/v2/empresas/{empresaId}/emails/{emailId}
需要 token、timestamp、sign 三个签名头，参见认证与签名。

查询一封经发送邮件受理的邮件。它是回调的兜底：email.sent 与 email.failed 带同样的结论，但需显式订阅。其他主体的 emailId 返回 10021020。

路径参数

empresaId*
string主体标识
emailId*
string邮件标识

* 必填字段

200
邮件存在。当前状态下无值的字段为 null。
emailId
string邮件标识
id
string请求标识
tipoDocumento
string发票类型
documentoId
string单据标识
numero
int票号
chaveAcesso
string访问密钥
codigoVerificacao
string校验码
templateId
string实际使用的模板
status
string投递状态
motivoEspera
string等待原因
motivoFalha
string失败原因
destinatarios
array实际收件邮箱
anexos
array附件清单
assunto
string渲染后的主题
criadoEm
string受理时间
enviadoEm
string交发信服务时刻
atualizadoEm
string最后更新时间

单据字段（numero、chaveAcesso、codigoVerificacao）取自受理时刻并在发送时刷新；assunto 与 enviadoEm 只在发送后有值；motivoEspera 只在 Aguardando、motivoFalha 只在 Falha 有值。Enviado 与 Falha 是终态：到了终态同一张票才能再次发送。

Aguardando：等密钥

圣保罗 NFS-e 的 50 位密钥尚未回填：chaveAcesso 为 null，codigoVerificacao 已有，motivoEspera 为 chaveAcesso。平台每 30 秒重查一次，最长 120 分钟；你这边不用做什么。

json
{
  "emailId": "2103160000000000002",
  "id": "mail-sp-000045",
  "tipoDocumento": "NFSe",
  "documentoId": "SP-20260928-045",
  "numero": 45,
  "chaveAcesso": null,
  "codigoVerificacao": "ABCD1234",
  "templateId": "2103150000000000002",
  "status": "Aguardando",
  "motivoEspera": "chaveAcesso",
  "motivoFalha": null,
  "destinatarios": ["financeiro@cliente.com.br"],
  "anexos": ["pdf", "xml"],
  "assunto": null,
  "criadoEm": "2026-09-28T12:00:00Z",
  "enviadoEm": null,
  "atualizadoEm": "2026-09-28T12:03:00Z"
}
status*
string投递状态
motivoEspera*
string等待原因

* 必填字段

Aguardando：等 PDF 或 XML

你要求了附件而文件尚未就绪：渲染服务不可用时 motivoEspera 为 pdf，授权 XML 尚未归档时为 xml。同样每 30 秒重查，最长 120 分钟。

json
{
  "emailId": "2103160000000000003",
  "id": "email-pedido-8843-1",
  "tipoDocumento": "NFe",
  "documentoId": "pedido-8843",
  "numero": 11770,
  "chaveAcesso": "35241204893402000113650010000117701017244270",
  "codigoVerificacao": null,
  "templateId": "2103150000000000001",
  "status": "Aguardando",
  "motivoEspera": "pdf",
  "motivoFalha": null,
  "destinatarios": ["comprador@exemplo.com"],
  "anexos": ["pdf"],
  "assunto": null,
  "criadoEm": "2026-09-28T12:10:00Z",
  "enviadoEm": null,
  "atualizadoEm": "2026-09-28T12:10:30Z"
}
status*
string投递状态
motivoEspera*
string等待原因

* 必填字段

Enviado：已发送

发信服务已接收：assunto 为最终主题，enviadoEm 为交付时刻。同时推送 email.sent。是否进入收件人邮箱取决于对方的邮件服务商。

json
{
  "emailId": "2103160000000000001",
  "id": "email-pedido-8842-1",
  "tipoDocumento": "NFe",
  "documentoId": "pedido-8842",
  "numero": 11769,
  "chaveAcesso": "35241204893402000113650010000117691017244265",
  "codigoVerificacao": null,
  "templateId": "2103150000000000001",
  "status": "Enviado",
  "motivoEspera": null,
  "motivoFalha": null,
  "destinatarios": ["comprador@exemplo.com"],
  "anexos": ["pdf", "xml"],
  "assunto": "Nota fiscal 11769 - Loja Exemplo LTDA",
  "criadoEm": "2026-09-28T12:00:00Z",
  "enviadoEm": "2026-09-28T12:00:31Z",
  "atualizadoEm": "2026-09-28T12:00:31Z"
}
status*
string投递状态
assunto*
string渲染后的主题
enviadoEm*
string交发信服务时刻

* 必填字段

Falha：失败

终态。原因：等待超时（motivoFalha 点名 chaveAcesso、pdf 或 xml）、发信重试用尽、票已不再是授权态、受理后模板被停用、凭证不可出具。同时推送 email.failed，带 motivo_falha。修正原因后用新的 id 重发。

json
{
  "emailId": "2103160000000000002",
  "id": "mail-sp-000045",
  "tipoDocumento": "NFSe",
  "documentoId": "SP-20260928-045",
  "numero": 45,
  "chaveAcesso": null,
  "codigoVerificacao": "ABCD1234",
  "templateId": "2103150000000000002",
  "status": "Falha",
  "motivoEspera": null,
  "motivoFalha": "Tempo esgotado aguardando: chaveAcesso",
  "destinatarios": ["financeiro@cliente.com.br"],
  "anexos": ["pdf", "xml"],
  "assunto": null,
  "criadoEm": "2026-09-28T12:00:00Z",
  "enviadoEm": null,
  "atualizadoEm": "2026-09-28T14:00:30Z"
}
status*
string投递状态
motivoFalha*
string失败原因

* 必填字段

上一页发送发票邮件下一页Webhooks