TF Fiscal
开发文档

发票邮件

发送发票邮件

受理把已授权的票以邮件发给买方；投递异步完成。

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

把一张已授权的票（NF-e、NFS-e、CT-e 或 DC-e）以邮件发出，正文来自模板，按需附上 PDF 与 XML。本接口是异步的：HTTP 200 返回 emailId 与受理状态；结果经 email.sent / email.failed 或查询接口获知。id 是幂等键；同一张票上一封邮件在途时再发返回 409。只有调用本接口才会发信，授权时不会自动发。

路径参数

empresaId*
string主体标识

* 必填字段

请求体

id*
string请求标识
tipoDocumento*
string发票类型
documentoId*
string单据标识
templateId
string模板标识
enviarPdf*
bool是否附 PDF
enviarXml*
bool是否附 XML
destinatarios
array收件邮箱

* 必填字段

200
受理回执。保存 emailId 用于查询；结果按回调或查询为准。
emailId
string邮件标识
id
string请求标识
status
string受理状态
tipoDocumento
string发票类型
documentoId
string单据标识
templateId
string实际使用的模板
destinatarios
array实际收件邮箱
anexos
array附件清单

HTTP 200 只是受理：邮件由平台任务随后组装并发出。发件人是平台地址（不能用你自己的域名）；显示名为主体的公司名，回复地址为主体注册的邮箱。结果经 email.sent / email.failed（需显式订阅，见注册 Webhook）或查询接口获知。

只发正文与 XML

NFS-e 指定模板并指定收件人；enviarPdf 为 false 就不生成 DANFSe。附件 XML 文件名为 NFSe-{chave}.xml。

json
{
  "id": "mail-nfse-000123",
  "tipoDocumento": "NFSe",
  "documentoId": "PED-20260918-001",
  "templateId": "2103150000000000002",
  "enviarPdf": false,
  "enviarXml": true,
  "destinatarios": ["financeiro@cliente.com.br"]
}
id*
string请求标识
tipoDocumento*
string发票类型
documentoId*
string单据标识
templateId
string模板标识
enviarPdf*
bool是否附 PDF
enviarXml*
bool是否附 XML
destinatarios
array收件邮箱

* 必填字段

PDF 加 XML 并取票上邮箱

不传 destinatarios 时平台用开票时给的买方邮箱；只有 NF-e 与 NFS-e 带它，CT-e 与 DC-e 必须传 destinatarios。不传 templateId 用该类型的默认模板。PDF 或 XML 尚未就绪时邮件停在 Aguardando，不会缺件发出。

json
{
  "id": "email-pedido-8842-1",
  "tipoDocumento": "NFe",
  "documentoId": "pedido-8842",
  "enviarPdf": true,
  "enviarXml": true
}
id*
string请求标识
tipoDocumento*
string发票类型
documentoId*
string单据标识
enviarPdf*
bool是否附 PDF
enviarXml*
bool是否附 XML

* 必填字段

圣保罗 NFS-e 等待密钥

圣保罗市政系统的 NFS-e 要稍后经全国环境才拿到 50 位密钥。密钥未到时发送以 Aguardando 受理，motivoEspera 为 chaveAcesso，每 30 秒重查一次，最长 120 分钟；超时转 Falha，motivoFalha 说明缺的是什么。下面是受理响应。

json
{
  "emailId": "2103160000000000002",
  "id": "mail-sp-000045",
  "status": "Aguardando",
  "tipoDocumento": "NFSe",
  "documentoId": "SP-20260928-045",
  "templateId": "2103150000000000002",
  "destinatarios": ["financeiro@cliente.com.br"],
  "anexos": ["pdf", "xml"]
}
status*
string受理状态

* 必填字段

同票在途：409

同一张票（同主体、同 tipoDocumento、同 documentoId）上一封邮件未到 Enviado 或 Falha 之前，换 id 再发会被 HTTP 409 与 10021015 拒绝；消息带在途邮件的 emailId 与状态。等回调或查询到终态后，用新的 id 重发。

json
[
  {
    "codigo": "10021015",
    "mensagem": "O e-mail anterior desta nota ainda não foi concluído: emailId=2103160000000000001 status=Enfileirado"
  }
]

幂等重放

同主体内用同一 id 重复调用返回原结果，不会再建一封邮件，请求体不同也一样；status 是当前状态。要再发同一张票，请在终态之后用新的 id。

json
{
  "emailId": "2103160000000000001",
  "id": "email-pedido-8842-1",
  "status": "Enviado",
  "tipoDocumento": "NFe",
  "documentoId": "pedido-8842",
  "templateId": "2103150000000000001",
  "destinatarios": ["comprador@exemplo.com"],
  "anexos": ["pdf", "xml"]
}
status*
string受理状态

* 必填字段

上一页查询邮件模板下一页查询发票邮件