E-mail de facturas

Visión general y flujo de integración

La autenticación es la misma que en los demás endpoints: cabeceras token / timestamp / sign, vea Autenticación. El correo solo sale cuando usted llama al endpoint de envío; nada se envía automáticamente en la autorización.

Plantillas y envío

• La plantilla pertenece al integrador, no a una empresa; cualquier empresa registrada usa cualquier plantilla.
• Cada plantilla tiene un tipo de documento (tipoDocumento) y un idioma (idioma) fijos. Puede haber varias por tipo, por ejemplo una por idioma.
• Cada tipo de documento tiene como máximo una plantilla predeterminada (padrao = true), sin importar el idioma. El envío sin templateId usa esa; sin predeterminada devuelve 10021012. Para usar otra plantilla, informe templateId en el envío.
• Marcar una plantilla como predeterminada quita la predeterminada anterior del mismo tipo; una plantilla desactivada (ativo = false) no sirve para el envío ni puede ser predeterminada.
• Guardar sustituye la plantilla entera: con templateId, reenvíe todos los campos; un campo opcional omitido vuelve a su valor por defecto.
• En el envío la plantilla debe estar activa y ser del tipo del documento, si no 10021002.

Variables

Escriba {{nome}} en el asunto o el cuerpo; el nombre empieza con letra y acepta letras, dígitos, guion bajo y punto, con espacios opcionales dentro de las llaves. Al guardar, cada nombre se comprueba contra la lista del tipo de documento; un nombre desconocido devuelve 10021003. Al renderizar, una variable sin valor queda como texto vacío. En el cuerpo el valor se escapa como HTML; en el asunto no.

Comunes a los cuatro tipos:

Propias de cada tipo:

Importes y fechas siguen el idioma de la plantilla: pt / es usan 1.234,56 y dd/MM/yyyy HH:mm; en / zh usan 1,234.56 y yyyy-MM-dd HH:mm. La hora es siempre la de São Paulo. El campo variaveisDisponiveis de Consultar plantilla es la lista completa del tipo.

HTML del cuerpo e imágenes

El cuerpo se rechaza, no se limpia: cualquier elemento fuera de la lista devuelve 10021004 al guardar, con su posición. Etiquetas permitidas: p, div, span, br, hr, h1 a h6, strong, b, em, i, u, s, ul, ol, li, blockquote, table, thead, tbody, tr, th, td, a, img; atributos permitidos: style, href, src, alt, width, height, align, colspan, rowspan. style no puede contener url(, expression(, position: ni behavior:; href solo acepta https:, mailto:, {{linkPdf}} o {{linkXml}}; el cuerpo tiene como máximo 64 KB.

Imágenes solo por dirección https. La plataforma no tiene subida de imágenes; aloje el logotipo en una dirección pública propia. Una imagen http se marca como contenido mixto en los clientes de correo y una imagen inline data: no se muestra en algunos webmails; ambas se rechazan al guardar. Un ejemplo completo con logotipo y botones está en Guardar plantilla de correo.

Adjuntos y enlaces de descarga

• enviarPdf = true adjunta el comprobante en PDF (DANFE / DANFSe / DACTE / DACE) y enviarXml = true adjunta el XML autorizado; los archivos se llaman {tipo}-{chave}.pdf / .xml.
• Si el comprobante o el XML aún no está disponible, el correo no sale incompleto: queda en Aguardando (motivoEspera = pdf o xml), comprobado de nuevo cada 30 segundos hasta 120 minutos; después pasa a Falha.
• Aunque no adjunte nada, el cuerpo puede llevar los enlaces {{linkPdf}} / {{linkXml}}; su validez sigue la configuración de enlaces de archivo del integrador, 7 días por defecto.

Remitente y destinatarios

• La dirección del remitente es la de la plataforma; no puede usarse un correo o dominio propio. El nombre mostrado es la razón social del emisor y el responder-a es el correo registrado de la empresa, así que las respuestas del cliente llegan a la empresa.
• destinatarios acepta hasta 5 direcciones; omitido, usa el correo del cliente informado en la emisión, que solo tienen NF-e y NFS-e; CT-e y DC-e exigen destinatarios. Sin ninguno, 10021013.
• Las direcciones repetidas se unifican y el dominio pasa a minúsculas; el destinatarios de la aceptación y de la consulta es la lista efectiva ya normalizada.

Estados

Aguardando ──► Enfileirado ──► Enviando ──┬──► Enviado (terminal)
                                          └──► Falha (terminal)

Aguardando solo existe mientras falta la clave (la clave de 50 dígitos de la NFS-e de São Paulo vuelve después por el ambiente nacional), el PDF o el XML, y no consume intentos. Un fallo al salir se reintenta con espera creciente, hasta 5 intentos; agotados, pasa a Falha. Otras causas de Falha: documento que dejó de estar autorizado, plantilla desactivada tras la aceptación, comprobante que no puede emitirse.

Idempotencia y 409

• id es la clave de idempotencia, única dentro de la empresa. Repetir el mismo id devuelve la aceptación original sin crear otro correo, aunque el cuerpo sea distinto; el status de la respuesta es el estado actual.
• Mientras el correo anterior del mismo documento (misma empresa, tipoDocumento y documentoId) no llegue al estado terminal, un envío con otro id devuelve HTTP 409 y 10021015, con el emailId y el estado del correo en curso en el mensaje. Espere Enviado / Falha por el callback o la consulta y reenvíe con un id nuevo.

Eventos de webhook

Incluya email.sent y email.failed en eventos al registrar el webhook; ambos solo se entregan a las aplicaciones que los suscriben explícitamente. El payload es el sobre de evento, con los campos de data en snake_case:

{
  "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.sent significa que el servicio de envío aceptó el mensaje, no que llegó a la bandeja del destinatario. La descripción completa de los campos está en Webhooks.

Modelo de errores

Los endpoints devuelven un array plano:

[{"codigo": "10021013", "mensagem": "Sem destinatário: destinatarios não informado e o documento não tem e-mail do cliente"}]

Los errores de autenticación y autorización (10009xxx) están en Autenticación; la tabla completa en Códigos de error.

Checklist de integración

1. Guarde una plantilla NFe con padrao = true y compruebe que variaveisDisponiveis en la respuesta tiene 11 ítems.
2. Escriba a propósito {{codigoVerificacao}} en el cuerpo y compruebe 10021003; cambie la imagen por una dirección http y compruebe 10021004.
3. Incluya email.sent y email.failed en los eventos del webhook.
4. Envíe una NF-e autorizada (enviarPdf y enviarXml en true, sin destinatarios); compruebe la aceptación Enfileirado, después email.sent, y assunto y enviadoEm rellenados en la consulta.
5. Antes del estado terminal, envíe el mismo documento con otro id y compruebe 409 con 10021015; repita con el mismo id y compruebe el mismo emailId.
6. Envíe una NFS-e de São Paulo y compruebe la aceptación Aguardando con motivoEspera = chaveAcesso, pasando a Enviado por sí sola cuando llegue la clave.