E-mail de notas

Visão geral e fluxo de integração

A autenticação é a mesma dos demais endpoints: cabeçalhos token / timestamp / sign, veja Autenticação. O e-mail só sai quando você chama o endpoint de envio; nada é enviado automaticamente na autorização.

Modelos e envio

• O modelo pertence ao integrador, não a uma empresa; qualquer empresa registrada usa qualquer modelo.
• Cada modelo tem um tipo de documento (tipoDocumento) e um idioma (idioma) fixos. Pode haver vários por tipo, por exemplo um por idioma.
• Cada tipo de documento tem no máximo um modelo padrão (padrao = true), independentemente do idioma. O envio sem templateId usa esse; sem padrão devolve 10021012. Para usar outro modelo, informe templateId no envio.
• Marcar um modelo como padrão tira o padrão anterior do mesmo tipo; um modelo desativado (ativo = false) não serve para o envio nem pode ser padrão.
• Salvar substitui o modelo inteiro: com templateId, reenvie todos os campos; campo opcional omitido volta ao valor padrão.
• No envio o modelo precisa estar ativo e ser do tipo da nota, senão 10021002.

Variáveis

Escreva {{nome}} no assunto ou no corpo; o nome começa com letra e aceita letras, dígitos, sublinhado e ponto, com espaços opcionais dentro das chaves. Ao salvar, cada nome é conferido contra a lista do tipo de documento; nome desconhecido devolve 10021003. Ao renderizar, variável sem valor vira texto vazio. No corpo o valor é escapado como HTML; no assunto, não.

Comuns aos quatro tipos:

Próprias de cada tipo:

Valores e datas seguem o idioma do modelo: pt / es usam 1.234,56 e dd/MM/yyyy HH:mm; en / zh usam 1,234.56 e yyyy-MM-dd HH:mm. A hora é sempre a de São Paulo. O campo variaveisDisponiveis de Consultar modelo é a lista completa do tipo.

HTML do corpo e imagens

O corpo é recusado, não limpo: qualquer item fora da lista devolve 10021004 ao salvar, com a posição. Tags 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 não pode conter url(, expression(, position: nem behavior:; href só aceita https:, mailto:, {{linkPdf}} ou {{linkXml}}; o corpo tem no máximo 64 KB.

Imagens só por endereço https. A plataforma não tem upload de imagens; hospede o logotipo num endereço público seu. Imagem http é marcada como conteúdo misto pelos clientes de e-mail e imagem inline data: não aparece em alguns webmails; as duas são recusadas ao salvar. Um exemplo completo com logotipo e botões está em Salvar modelo de e-mail.

Anexos e links de download

• enviarPdf = true anexa o comprovante em PDF (DANFE / DANFSe / DACTE / DACE) e enviarXml = true anexa o XML autorizado; os arquivos se chamam {tipo}-{chave}.pdf / .xml.
• Se o comprovante ou o XML ainda não estiver disponível, o e-mail não sai incompleto: fica em Aguardando (motivoEspera = pdf ou xml), reconferido a cada 30 segundos por até 120 minutos; depois vira Falha.
• Mesmo sem anexar, o corpo pode trazer os links {{linkPdf}} / {{linkXml}}; a validade segue a configuração de links de arquivo do integrador, 7 dias por padrão.

Remetente e destinatários

• O endereço do remetente é o da plataforma; não é possível usar um e-mail ou domínio próprio. O nome exibido é a razão social do emitente e o responder-para é o e-mail cadastrado da empresa, então respostas do cliente chegam à empresa.
• destinatarios aceita até 5 endereços; omitido, usa o e-mail do cliente informado na emissão, que só NF-e e NFS-e têm; CT-e e DC-e exigem destinatarios. Sem nenhum, 10021013.
• Endereços repetidos são unificados e o domínio vira minúsculo; o destinatarios da aceitação e da consulta é a lista efetiva já normalizada.

Estados

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

Aguardando só existe enquanto falta a chave (a chave de 50 dígitos da NFS-e de São Paulo volta depois pelo ambiente nacional), o PDF ou o XML, e não consome tentativas. Falha na saída é reenviada com espera crescente, até 5 tentativas; esgotadas, vira Falha. Outras causas de Falha: nota que deixou de estar autorizada, modelo desativado depois da aceitação, comprovante que não pode ser emitido.

Idempotência e 409

• id é a chave de idempotência, única dentro da empresa. Repetir o mesmo id devolve a aceitação original sem criar outro e-mail, mesmo com corpo diferente; o status da resposta é o estado atual.
• Enquanto o e-mail anterior da mesma nota (mesma empresa, tipoDocumento e documentoId) não chega ao estado terminal, um envio com outro id devolve HTTP 409 e 10021015, com emailId e status do e-mail em andamento na mensagem. Espere Enviado / Falha pelo callback ou pela consulta e reenvie com um id novo.

Eventos de webhook

Inclua email.sent e email.failed em eventos ao registrar o webhook; os dois só são entregues a quem os assina explicitamente. O payload é o envelope de evento, com os campos de data em 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 o serviço de envio aceitou a mensagem, não que ela chegou à caixa do destinatário. A descrição completa dos campos está em Webhooks.

Modelo de erros

Os endpoints devolvem um array simples:

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

Erros de autenticação e autorização (10009xxx) estão em Autenticação; a tabela completa em Códigos de erro.

Checklist de integração

1. Salve um modelo NFe com padrao = true e confira que variaveisDisponiveis na resposta tem 11 itens.
2. Escreva de propósito {{codigoVerificacao}} no corpo e confira 10021003; troque a imagem por um endereço http e confira 10021004.
3. Inclua email.sent e email.failed em eventos do webhook.
4. Envie uma NF-e autorizada (enviarPdf e enviarXml em true, sem destinatarios); confira aceitação Enfileirado, depois email.sent, e assunto e enviadoEm preenchidos na consulta.
5. Antes do estado terminal, envie a mesma nota com outro id e confira 409 com 10021015; repita com o mesmo id e confira o mesmo emailId.
6. Envie uma NFS-e de São Paulo e confira aceitação Aguardando com motivoEspera = chaveAcesso, passando a Enviado sozinha quando a chave chegar.