Modelos de e-mail
Endpoints da WebApiAlcance para administrar os modelos de e-mail editáveis enviados pelo sistema (acesso criado, recuperação de senha, alíquota de ISS, certidão negativa e outros). Cada modelo tem um texto padrão e pode ser personalizado (assunto, corpo e, quando existir, texto do botão). As rotas cobrem listagem, consulta, personalização, restauração do padrão, histórico de alterações com reversão, pré-visualização do rascunho e envio de teste.
Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key.
Acesso restrito
Todas as rotas exigem login de usuário (sessão); credenciais de integração recebem 403. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
Base path
/api/v1/email-modelosEscopos necessários
email_modelos:read- listagem, consulta de modelo e histórico (rotasGET).email_modelos:write- personalização, restauração do padrão, reversão, pré-visualização e envio de teste (POST,PUT,DELETE).
O escopo é derivado do prefixo público da rota: /email-modelos vira o recurso email_modelos (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE). Na prática o escopo não basta: as restrições de acesso descritas acima também são exigidas.
Envelope de resposta
Toda resposta de sucesso segue o envelope padrão da WebApi:
{
"status": "success",
"message": "Mensagem em PT-BR",
"data": {}
}Erros de regra de negócio (404, 422, 502, 503) vêm como { "detail": "mensagem", "message": "mensagem" }. Erros de validação do corpo (tipo errado, texto acima do tamanho máximo) vêm como 422 no formato { "detail": [...] }. As mutações, a pré-visualização e o envio de teste também podem responder 429 quando o limite de requisições é excedido.
Modelos disponíveis
O slug identifica o modelo. Os valores atuais são:
portal_acesso_criado, hub_acesso_criado, hub_senha_redefinida, portal_recuperacao_senha, interno_recuperacao_senha, portal_confirmacao_novo_email, portal_aviso_email_antigo, portal_aviso_login_alterado, iss_aliquota_mensal, certidao_negativa_envio, open_finance_consentimento.
Um slug desconhecido retorna 404.
Regras do conteúdo do modelo
O texto é texto simples com variáveis no formato {{nome.da.variavel}} (minúsculas). Nada além disso é interpretado. A lista de variáveis de cada modelo vem em variaveis no GET /email-modelos/{slug}. O PUT, a pré-visualização e o envio de teste recusam com 422 (mensagens em PT-BR unidas por ; ) o conteúdo que:
- tem assunto vazio, com mais de 200 caracteres ou com quebra de linha;
- tem corpo vazio ou com mais de 20000 caracteres;
- tem texto do botão com mais de 80 caracteres, vazio quando o modelo tem botão, preenchido quando o modelo não tem botão, com quebra de linha ou com variáveis;
- usa marcação de variável malformada ou variável que não existe no modelo;
- omite uma variável marcada como
obrigatoriano corpo; - usa no assunto uma variável com
permitida_no_assunto: false; - contém endereço digitado: URL (
http://,https://,www.), domínio comosite.com.br, e-mail ou IP. Links entram somente por variável. Se for fim de frase, deixe um espaço depois do ponto; - cola uma variável
sensivelem outro texto. Variáveis sensíveis (por exemplo{{link}}e{{acesso.senha}}) precisam ficar isoladas, separadas por espaço ou quebra de linha, aceitando apenas uma pontuação final (.,;:!?).
A saudação inicial do e-mail não é editável. As quebras de linha do corpo são normalizadas.
Endpoints
GET /email-modelos/
Lista todos os modelos do catálogo, indicando quais estão personalizados.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query.
Request
GET /api/v1/email-modelos/Response 200 OK
{
"status": "success",
"message": "Modelos recuperados",
"data": {
"itens": [
{
"slug": "iss_aliquota_mensal",
"titulo": "Alíquota do ISS / Simples Nacional",
"descricao": "Orientação mensal de alíquota de ISS enviada pela automação.",
"destinatario": "cliente",
"caixa": "automacoes",
"personalizado": true,
"atualizado_em": "2026-10-20T14:32:10",
"atualizado_por_nome": "Maria Souza"
}
]
}
}Os itens seguem ModeloResumo.
Escopo: email_modelos:read
Exige login de usuário (sessão); credenciais de integração recebem 403. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
GET /email-modelos/historico
Lista, de forma paginada, o histórico de alterações dos modelos (personalizar, restaurar o padrão e reverter).
Parâmetros de query
| Parâmetro | Tipo | Default | Observações |
|---|---|---|---|
slug | str (≤ 60) | - | Filtra por modelo. slug desconhecido retorna 404. |
page | int (≥ 1) | 1 | Página, 1-based. |
per_page | int (1-200) | 20 | Itens por página. |
Request
GET /api/v1/email-modelos/historico?slug=iss_aliquota_mensal&page=1&per_page=20Response 200 OK
{
"status": "success",
"message": "Histórico recuperado",
"data": {
"itens": [
{
"id": 8812,
"slug": "iss_aliquota_mensal",
"operacao": "definir",
"criado_em": "2026-10-20T11:32:10",
"ator_nome": "Maria Souza",
"ip": "203.0.113.10"
}
],
"total": 1,
"page": 1,
"per_page": 20
}
}O id do item é o valor que o endpoint de reversão recebe. criado_em está no horário de Brasília. Os itens seguem HistoricoItem.
Escopo: email_modelos:read
Exige login de usuário (sessão); credenciais de integração recebem 403. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
POST /email-modelos/historico/{historico_id}/reverter
Reverte uma alteração: restaura o estado que o modelo tinha antes dela (se não havia personalização, o modelo volta ao padrão). A própria reversão é registrada no histórico.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
historico_id | int | rota | sim | id de um item de GET /email-modelos/historico. |
Request
POST /api/v1/email-modelos/historico/8812/reverterResponse 200 OK
{
"status": "success",
"message": "Alteração revertida",
"data": {}
}O data segue ModeloDetalhe.
Erros
404 se o registro de histórico não existir; 422 se o texto da versão anterior não for mais aceito pelas regras atuais; 503 se o serviço estiver temporariamente indisponível.
Escopo: email_modelos:write
Exige login de usuário (sessão); credenciais de integração recebem 403. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
GET /email-modelos/{slug}
Retorna o modelo efetivo (personalizado ou padrão), o texto padrão e as variáveis disponíveis.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
slug | str (1-60) | rota | sim | Identificador do modelo. |
Request
GET /api/v1/email-modelos/iss_aliquota_mensalResponse 200 OK
{
"status": "success",
"message": "Modelo recuperado",
"data": {
"slug": "iss_aliquota_mensal",
"titulo": "Alíquota do ISS / Simples Nacional",
"descricao": "Orientação mensal de alíquota de ISS enviada pela automação.",
"destinatario": "cliente",
"caixa": "automacoes",
"personalizado": false,
"assunto": "Alíquota Simples Nacional para {{cliente.razao_social}}",
"corpo": "Espero que este e-mail te encontre bem!\n\n...",
"texto_botao": null,
"assunto_padrao": "Alíquota Simples Nacional para {{cliente.razao_social}}",
"corpo_padrao": "Espero que este e-mail te encontre bem!\n\n...",
"texto_botao_padrao": null,
"tem_botao": false,
"variaveis": [
{
"nome": "iss.aliquota",
"descricao": "Alíquota de ISS a destacar (%)",
"exemplo": "2.00",
"obrigatoria": true,
"sensivel": false,
"permitida_no_assunto": true
}
],
"atualizado_em": null,
"atualizado_por_nome": null
}
}O data segue ModeloDetalhe. 404 se o slug não existir.
Escopo: email_modelos:read
Exige login de usuário (sessão); credenciais de integração recebem 403. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
PUT /email-modelos/{slug}
Personaliza o modelo. O conteúdo é validado pelas regras do conteúdo e a alteração entra no histórico.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
slug | str (1-60) | rota | sim | Identificador do modelo. |
O corpo segue ModeloBody.
Request
{
"assunto": "Alíquota de ISS de {{iss.periodo}}",
"corpo": "Olá.\n\nA alíquota de ISS a destacar é {{iss.aliquota}}%.",
"texto_botao": null
}Response 200 OK
{
"status": "success",
"message": "Modelo salvo",
"data": {}
}O data segue ModeloDetalhe, já com personalizado: true.
Erros
404 (slug desconhecido), 422 (conteúdo recusado pelas regras) e 503 (serviço temporariamente indisponível; a alteração não é aplicada).
Escopo: email_modelos:write
Exige login de usuário (sessão); credenciais de integração recebem 403. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
DELETE /email-modelos/{slug}
Remove a personalização e restaura o texto padrão. Se o modelo já estava no padrão, nada muda e o detalhe é retornado normalmente.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
slug | str (1-60) | rota | sim | Identificador do modelo. |
Request
DELETE /api/v1/email-modelos/iss_aliquota_mensalResponse 200 OK
{
"status": "success",
"message": "Padrão restaurado",
"data": {}
}O data segue ModeloDetalhe, com personalizado: false. 404 se o slug não existir; 503 se o serviço estiver temporariamente indisponível.
Escopo: email_modelos:write
Exige login de usuário (sessão); credenciais de integração recebem 403. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
POST /email-modelos/{slug}/pre-visualizar
Gera a prévia do rascunho com dados fictícios e o layout real do e-mail. Não grava nada.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
slug | str (1-60) | rota | sim | Identificador do modelo. |
O corpo segue ModeloBody.
Request
{
"assunto": "Alíquota de ISS de {{iss.periodo}}",
"corpo": "A alíquota de ISS a destacar é {{iss.aliquota}}%.",
"texto_botao": null
}Response 200 OK
{
"status": "success",
"message": "Pré-visualização gerada",
"data": {
"assunto": "Alíquota de ISS de 09/2026",
"html": "<html>...</html>"
}
}O html já traz a logo embutida, pronto para exibir em um iframe. 422 se o rascunho violar as regras do conteúdo.
Escopo: email_modelos:write
Exige login de usuário (sessão); credenciais de integração recebem 403. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
POST /email-modelos/{slug}/enviar-teste
Envia o rascunho como e-mail de teste, com o assunto prefixado por [TESTE] , para o e-mail do usuário logado. O destino não é configurável: campos extras no corpo (como destinatario) são ignorados.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
slug | str (1-60) | rota | sim | Identificador do modelo. |
O corpo segue ModeloBody.
Request
{
"assunto": "Alíquota de ISS de {{iss.periodo}}",
"corpo": "A alíquota de ISS a destacar é {{iss.aliquota}}%.",
"texto_botao": null
}Response 200 OK
{
"status": "success",
"message": "E-mail de teste enviado",
"data": {
"enviado_para": "msouza@exemplo.com.br"
}
}Erros
404 (slug desconhecido), 422 (rascunho recusado pelas regras, ou usuário sem e-mail cadastrado), 502 (a caixa de envio está incompleta ou o envio foi recusado) e 429 (limite de testes por usuário excedido).
Escopo: email_modelos:write
Exige login de usuário (sessão); credenciais de integração recebem 403. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
Schemas
ModeloBody
Corpo de PUT /{slug}, pre-visualizar e enviar-teste. Campos extras são ignorados.
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
assunto | str | sim | Até 200 caracteres, sem quebra de linha. |
corpo | str | sim | Até 20000 caracteres. |
texto_botao | str | null | não | Até 80 caracteres. Obrigatório quando o modelo tem botão; vazio vira null. |
ModeloResumo
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
slug | str | sim | Identificador do modelo. |
titulo | str | sim | Nome exibível. |
descricao | str | sim | Quando o e-mail é enviado. |
destinatario | "cliente" | "funcionario" | sim | Quem recebe o e-mail. |
caixa | "clientes" | "automacoes" | sim | Caixa de envio usada. |
personalizado | bool | sim | true quando há texto personalizado. |
atualizado_em | str | null | não | Data/hora da última personalização. |
atualizado_por_nome | str | null | não | Nome de quem personalizou. |
ModeloDetalhe
Contém todos os campos de ModeloResumo e mais:
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
assunto | str | sim | Assunto efetivo (personalizado ou padrão). |
corpo | str | sim | Corpo efetivo. |
texto_botao | str | null | não | Texto efetivo do botão; null se o modelo não tem botão. |
assunto_padrao | str | sim | Assunto padrão. |
corpo_padrao | str | sim | Corpo padrão. |
texto_botao_padrao | str | null | não | Texto padrão do botão. |
tem_botao | bool | sim | Se o e-mail tem botão. |
variaveis | List[Variavel] | sim | Variáveis aceitas pelo modelo. |
Variavel
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
nome | str | sim | Usada como {{nome}} no texto. |
descricao | str | sim | O que a variável representa. |
exemplo | str | sim | Valor fictício usado na prévia. |
obrigatoria | bool | sim | Precisa aparecer no corpo. |
sensivel | bool | sim | Precisa ficar isolada no texto. |
permitida_no_assunto | bool | sim | Se pode ser usada no assunto. |
HistoricoItem
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
id | int | sim | Identificador do registro (usado em reverter). |
slug | str | sim | Modelo alterado. |
operacao | str | sim | definir, restaurar_padrao ou reverter. |
criado_em | str | sim | Data/hora da alteração, no horário de Brasília. |
ator_nome | str | null | não | Nome de quem alterou. |
ip | str | null | não | IP de origem da alteração. |
Notas
- Personalizado inválido não bloqueia envios. Se um texto personalizado deixar de ser aceito pelas regras, o sistema envia o e-mail com o texto padrão.
- Alterações são auditadas. Cada personalização, restauração e reversão entra no histórico.
- A prévia e o teste não gravam o rascunho; só o
PUTpersiste o texto.