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-modelos

Escopos necessários

  • email_modelos:read - listagem, consulta de modelo e histórico (rotas GET).
  • 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 obrigatoria no corpo;
  • usa no assunto uma variável com permitida_no_assunto: false;
  • contém endereço digitado: URL (http://, https://, www.), domínio como site.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 sensivel em 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âmetroTipoDefaultObservações
slugstr (≤ 60)-Filtra por modelo. slug desconhecido retorna 404.
pageint (≥ 1)1Página, 1-based.
per_pageint (1-200)20Itens por página.

Request

GET /api/v1/email-modelos/historico?slug=iss_aliquota_mensal&page=1&per_page=20

Response 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âmetroTipoLocalObrigatórioDescrição
historico_idintrotasimid de um item de GET /email-modelos/historico.

Request

POST /api/v1/email-modelos/historico/8812/reverter

Response 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âmetroTipoLocalObrigatórioDescrição
slugstr (1-60)rotasimIdentificador do modelo.

Request

GET /api/v1/email-modelos/iss_aliquota_mensal

Response 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âmetroTipoLocalObrigatórioDescrição
slugstr (1-60)rotasimIdentificador 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âmetroTipoLocalObrigatórioDescrição
slugstr (1-60)rotasimIdentificador do modelo.

Request

DELETE /api/v1/email-modelos/iss_aliquota_mensal

Response 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âmetroTipoLocalObrigatórioDescrição
slugstr (1-60)rotasimIdentificador 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âmetroTipoLocalObrigatórioDescrição
slugstr (1-60)rotasimIdentificador 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.

CampoTipoObrigatórioObservações
assuntostrsimAté 200 caracteres, sem quebra de linha.
corpostrsimAté 20000 caracteres.
texto_botaostr | nullnãoAté 80 caracteres. Obrigatório quando o modelo tem botão; vazio vira null.

ModeloResumo

CampoTipoObrigatórioObservações
slugstrsimIdentificador do modelo.
titulostrsimNome exibível.
descricaostrsimQuando o e-mail é enviado.
destinatario"cliente" | "funcionario"simQuem recebe o e-mail.
caixa"clientes" | "automacoes"simCaixa de envio usada.
personalizadoboolsimtrue quando há texto personalizado.
atualizado_emstr | nullnãoData/hora da última personalização.
atualizado_por_nomestr | nullnãoNome de quem personalizou.

ModeloDetalhe

Contém todos os campos de ModeloResumo e mais:

CampoTipoObrigatórioObservações
assuntostrsimAssunto efetivo (personalizado ou padrão).
corpostrsimCorpo efetivo.
texto_botaostr | nullnãoTexto efetivo do botão; null se o modelo não tem botão.
assunto_padraostrsimAssunto padrão.
corpo_padraostrsimCorpo padrão.
texto_botao_padraostr | nullnãoTexto padrão do botão.
tem_botaoboolsimSe o e-mail tem botão.
variaveisList[Variavel]simVariáveis aceitas pelo modelo.

Variavel

CampoTipoObrigatórioObservações
nomestrsimUsada como {{nome}} no texto.
descricaostrsimO que a variável representa.
exemplostrsimValor fictício usado na prévia.
obrigatoriaboolsimPrecisa aparecer no corpo.
sensivelboolsimPrecisa ficar isolada no texto.
permitida_no_assuntoboolsimSe pode ser usada no assunto.

HistoricoItem

CampoTipoObrigatórioObservações
idintsimIdentificador do registro (usado em reverter).
slugstrsimModelo alterado.
operacaostrsimdefinir, restaurar_padrao ou reverter.
criado_emstrsimData/hora da alteração, no horário de Brasília.
ator_nomestr | nullnãoNome de quem alterou.
ipstr | nullnãoIP 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 PUT persiste o texto.