E-mail de notas

Salvar modelo de e-mail

Cria um modelo de e-mail do integrador ou sobrescreve um existente; valida variáveis e HTML ao salvar.

POST/openapi/v2/emails/templates

Requer os cabeçalhos de assinatura token, timestamp e sign, veja Autenticação.

Modelos são do integrador, não de uma empresa: qualquer empresa registrada usa qualquer modelo. Sem templateId cria; com templateId substitui o modelo inteiro. O assunto e o corpo aceitam {{variáveis}} preenchidas no envio com os dados da nota; a lista de nomes depende do tipoDocumento e está na enumeração no fim da página. Como os modelos se relacionam com o envio está em E-mail de notas.

Corpo da requisição

`templateId*` obrigatório para sobrescrever	string	Identificador do modelo
`tipoDocumento*`	string	Tipo de documento
`idioma*`	string	Idioma do modelo
`nome*`	string	Nome do modelo
`assunto*`	string	Modelo do assunto
`corpoHtml*`	string	Modelo do corpo
`padrao`	bool	Modelo padrão
`ativo`	bool	Ativo

* Campo obrigatório

200

Modelo salvo, devolvido por inteiro com a lista de variáveis permitidas para o tipo.

`templateId`	string	Identificador do modelo
`tipoDocumento`	string	Tipo de documento
`idioma`	string	Idioma do modelo
`nome`	string	Nome do modelo
`assunto`	string	Modelo do assunto
`corpoHtml`	string	Modelo do corpo
`padrao`	bool	Modelo padrão
`ativo`	bool	Ativo
`variaveisDisponiveis`	array	Variáveis permitidas
`criadoEm`	string	Criação
`atualizadoEm`	string	Última atualização

Um modelo pertence ao integrador e vale para todas as empresas. Pode haver vários por tipo de documento, por exemplo um por idioma; o que tiver padrao = true é usado quando o envio não informa templateId. Salvar já valida: variável fora da lista devolve 10021003, HTML fora da lista devolve 10021004, e a mensagem diz o quê.

Modelo mínimo

NF-e em português: assunto com número e emitente, corpo com saudação, resumo e link do PDF. Sem padrao e sem ativo: fica ativo e não é o padrão.

json

{
  "tipoDocumento": "NFe",
  "idioma": "pt",
  "nome": "NF-e simples",
  "assunto": "Nota fiscal {{numero}} - {{emitente.nome}}",
  "corpoHtml": "<p>Olá {{cliente.nome}},</p><p>Segue a nota fiscal {{numero}} emitida por {{emitente.nome}} em {{dataEmissao}}, no valor de R$ {{valorTotal}}.</p><p><a href='{{linkPdf}}'>Baixar DANFE (PDF)</a></p>"
}

`tipoDocumento*`	string	Tipo de documento
`idioma*`	string	Idioma do modelo
`nome*`	string	Nome do modelo
`assunto*`	string	Modelo do assunto
`corpoHtml*`	string	Modelo do corpo

* Campo obrigatório

Modelo com logotipo e botões

NFS-e em português marcada como padrão: cabeçalho com imagem https, tabela com as variáveis próprias da NFS-e e dois botões que apontam para {{linkPdf}} e {{linkXml}}. A imagem só pode ser um endereço https público; não há upload.

json

{
  "tipoDocumento": "NFSe",
  "idioma": "pt",
  "nome": "NFS-e com logotipo",
  "assunto": "Nota Fiscal de Serviço nº {{numero}} - {{emitente.nome}}",
  "corpoHtml": "<div style='background:#f3f4f6;padding:24px 0;font-family:Arial,Helvetica,sans-serif;color:#1f2937'><div style='max-width:640px;margin:0 auto;background:#ffffff;border-radius:12px;overflow:hidden;border:1px solid #e5e7eb'><div style='padding:20px 28px;border-bottom:1px solid #e5e7eb'><img src='https://v2.tffiscal.com/logo.png' alt='TF Fiscal' width='160' style='display:block;height:auto;border:0'></div><div style='padding:24px 28px'><h2 style='margin:0 0 16px;color:#1a56db;font-size:20px'>Nota Fiscal de Serviço nº {{numero}}</h2><p>Olá <strong>{{cliente.nome}}</strong>,</p><p>Segue a nota fiscal de serviço emitida por <strong>{{emitente.nome}}</strong> (CNPJ {{emitente.cnpj}}) em {{dataEmissao}}.</p><table style='border-collapse:collapse;width:100%;font-size:14px'><tbody><tr><td style='padding:8px;border:1px solid #e5e7eb;background:#f9fafb;width:40%'>Número / Série</td><td style='padding:8px;border:1px solid #e5e7eb'>{{numero}} / {{serie}}</td></tr><tr><td style='padding:8px;border:1px solid #e5e7eb;background:#f9fafb'>Serviço</td><td style='padding:8px;border:1px solid #e5e7eb'>{{descricaoServico}}</td></tr><tr><td style='padding:8px;border:1px solid #e5e7eb;background:#f9fafb'>Valor total</td><td style='padding:8px;border:1px solid #e5e7eb'>R$ {{valorTotal}}</td></tr><tr><td style='padding:8px;border:1px solid #e5e7eb;background:#f9fafb'>ISS</td><td style='padding:8px;border:1px solid #e5e7eb'>R$ {{valorIss}}</td></tr><tr><td style='padding:8px;border:1px solid #e5e7eb;background:#f9fafb'>Município</td><td style='padding:8px;border:1px solid #e5e7eb'>{{municipio}}</td></tr><tr><td style='padding:8px;border:1px solid #e5e7eb;background:#f9fafb'>Chave de acesso</td><td style='padding:8px;border:1px solid #e5e7eb;font-family:monospace;font-size:12px'>{{chaveAcesso}}</td></tr></tbody></table><p style='margin-top:20px'><a href='{{linkPdf}}' style='display:inline-block;padding:10px 18px;background:#1a56db;color:#ffffff;text-decoration:none;border-radius:6px;font-weight:bold'>Baixar DANFSe (PDF)</a>&nbsp;&nbsp;<a href='{{linkXml}}' style='display:inline-block;padding:10px 18px;border:1px solid #1a56db;color:#1a56db;text-decoration:none;border-radius:6px;font-weight:bold'>Baixar XML</a></p></div><div style='padding:16px 28px;background:#f9fafb;color:#6b7280;font-size:12px;border-top:1px solid #e5e7eb'>E-mail automático enviado pela plataforma TF Fiscal. Em caso de dúvidas, responda a este e-mail.</div></div></div>",
  "padrao": true
}

`tipoDocumento*`	string	Tipo de documento
`idioma*`	string	Idioma do modelo
`nome*`	string	Nome do modelo
`assunto*`	string	Modelo do assunto
`corpoHtml*`	string	Modelo do corpo
`padrao`	bool	Modelo padrão

* Campo obrigatório

Variáveis próprias do tipo

CT-e em inglês usando remetente.nome, destinatario.nome e valorFrete. Esses nomes só existem no CTe; num modelo NFe seriam recusados com 10021003. Com idioma = en, valores saem como 1,234.56 e datas como yyyy-MM-dd HH:mm.

json

{
  "tipoDocumento": "CTe",
  "idioma": "en",
  "nome": "CT-e english",
  "assunto": "Transport document {{numero}} from {{emitente.nome}}",
  "corpoHtml": "<p>Hello {{cliente.nome}},</p><p>Transport document {{numero}} issued by {{emitente.nome}} on {{dataEmissao}}.</p><ul><li>Sender: {{remetente.nome}}</li><li>Recipient: {{destinatario.nome}}</li><li>Freight: R$ {{valorFrete}}</li></ul><p><a href='{{linkPdf}}'>Download DACTE (PDF)</a> | <a href='{{linkXml}}'>Download XML</a></p>"
}

`tipoDocumento*`	string	Tipo de documento
`idioma*`	string	Idioma do modelo
`nome*`	string	Nome do modelo
`assunto*`	string	Modelo do assunto
`corpoHtml*`	string	Modelo do corpo

* Campo obrigatório

Sobrescrever e desativar um modelo

Com templateId, o corpo substitui o modelo inteiro: reenvie todos os campos. Campo opcional omitido volta ao valor padrão, então um modelo padrão sobrescrito sem padrao = true deixa de ser o padrão. Aqui ele também é desativado com ativo = false; um modelo desativado nunca fica como padrão.

json

{
  "templateId": "2103150000000000001",
  "tipoDocumento": "NFe",
  "idioma": "pt",
  "nome": "NF-e simples (antigo)",
  "assunto": "Nota fiscal {{numero}} - {{emitente.nome}}",
  "corpoHtml": "<p>Olá {{cliente.nome}},</p><p>Segue a nota fiscal {{numero}} emitida por {{emitente.nome}} em {{dataEmissao}}, no valor de R$ {{valorTotal}}.</p><p><a href='{{linkPdf}}'>Baixar DANFE (PDF)</a></p>",
  "ativo": false
}

`templateId*`	string	Identificador do modelo
`tipoDocumento*`	string	Tipo de documento
`idioma*`	string	Idioma do modelo
`nome*`	string	Nome do modelo
`assunto*`	string	Modelo do assunto
`corpoHtml*`	string	Modelo do corpo
`ativo`	bool	Ativo

* Campo obrigatório

`tipoDocumento`Tipo de documento

Valores	Significado
NFe	NF-e, nota fiscal de mercadorias
NFSe	NFS-e, nota fiscal de serviços
CTe	CT-e, conhecimento de transporte
DCe	DC-e, declaração de conteúdo

`idioma`Idioma do modelo

O idioma define o formato de valores e datas nas variáveis; a hora é sempre a de São Paulo.

Valores	Significado
pt	Português; valores `1.234,56`, datas `dd/MM/yyyy HH:mm`
en	Inglês; valores `1,234.56`, datas `yyyy-MM-dd HH:mm`
zh	Chinês; valores `1,234.56`, datas `yyyy-MM-dd HH:mm`
es	Espanhol; valores `1.234,56`, datas `dd/MM/yyyy HH:mm`

`corpoHtml`Variáveis comuns aos quatro tipos

Escreva {{nome}}; espaços dentro das chaves são aceitos. Sem valor, a variável vira texto vazio. No corpo o valor é escapado como HTML; no assunto não.

Valores	Significado
numero	Número do documento
serie	Série
chaveAcesso	Chave de acesso, 44 ou 50 dígitos
dataEmissao	Data de emissão, no fuso de São Paulo e no formato do idioma
valorTotal	Valor total, formatado pelo idioma: total da NF-e, valor do serviço da NFS-e, valor total da prestação do CT-e, valor declarado da DC-e
emitente.nome	Razão social do emitente
emitente.cnpj	CNPJ do emitente
cliente.nome	Nome do destinatário da nota: comprador da NF-e, tomador da NFS-e e do CT-e, destinatário da DC-e
cliente.documento	Documento do destinatário, CPF ou CNPJ
linkPdf	Link de download do PDF; validade conforme a configuração do integrador, 7 dias por padrão
linkXml	Link de download do XML autorizado; vazio se o XML ainda não foi arquivado

`corpoHtml`Variáveis só da NFSe

Em outro tipo de documento a variável é recusada ao salvar com 10021003.

Valores	Significado
codigoVerificacao	Código de verificação da NFS-e
municipio	Nome do município do emitente
descricaoServico	Descrição do serviço
valorIss	Valor do ISS, formatado pelo idioma

`corpoHtml`Variáveis só do CTe

Em outro tipo de documento a variável é recusada ao salvar com 10021003.

Valores	Significado
remetente.nome	Nome do remetente da carga
destinatario.nome	Nome do destinatário da carga
valorFrete	Valor total da prestação, formatado pelo idioma

`corpoHtml`Variáveis só da DCe

Em outro tipo de documento a variável é recusada ao salvar com 10021003.

Valores	Significado
marketplace.site	Site do marketplace, do cadastro de DC-e do emitente

Código	HTTP
10001001	400	Falha de validação de campos: obrigatório em branco, acima do tamanho, `tipoDocumento` ou `idioma` fora dos valores aceitos; uma entrada por campo.
10021001	404	Modelo de e-mail não encontrado: o `templateId` não existe ou não é deste integrador.
10021003	400	O modelo usa variáveis fora da lista permitida; a mensagem lista os nomes. Confira o `tipoDocumento` e a enumeração de variáveis.
10021004	400	O HTML do modelo contém conteúdo proibido: tag, atributo, `style`, `href` ou `src` fora da lista, ou corpo acima de 64 KB; a mensagem aponta cada ocorrência.

Salvar modelo de e-mail

Parâmetros

Corpo da requisição

Respostas

Cenários4 blocos

Modelo mínimo

Modelo com logotipo e botões

Variáveis próprias do tipo

Sobrescrever e desativar um modelo

Variáveis e formatação

Lista permitida do HTML do corpo

Enumerações6 tabelas

tipoDocumentoTipo de documento

idiomaIdioma do modelo

corpoHtmlVariáveis comuns aos quatro tipos

corpoHtmlVariáveis só da NFSe

corpoHtmlVariáveis só do CTe

corpoHtmlVariáveis só da DCe

Erros4 itens

`tipoDocumento`Tipo de documento

`idioma`Idioma do modelo

`corpoHtml`Variáveis comuns aos quatro tipos

`corpoHtml`Variáveis só da NFSe

`corpoHtml`Variáveis só do CTe

`corpoHtml`Variáveis só da DCe