Modelos de WhatsApp
Endpoints da WebApiAlcance para administrar os modelos de mensagem de WhatsApp editáveis enviados aos clientes (alvará, TFF Salvador, alíquota de ISS, guias de imposto, certidão negativa e outros). Cada modelo tem um texto padrão e pode ser personalizado. 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/whatsapp-modelosEscopos necessários
whatsapp_modelos:read- listagem, consulta de modelo e histórico (rotasGET).whatsapp_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: /whatsapp-modelos vira o recurso whatsapp_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:
alvara_envio, tff_salvador_envio, iss_aliquota_mensal, guia_imposto_individual, guia_imposto_par, certidao_negativa_envio, open_finance_consentimento.
Um slug desconhecido retorna 404. O campo anexo de cada modelo descreve, de forma informativa, o que segue junto com a mensagem (por exemplo, "PDF da guia"); o anexo não é editável.
Regras do conteúdo do modelo
O texto é texto simples com variáveis no formato {{nome.da.variavel}} (minúsculas). A formatação do WhatsApp (*negrito*, _itálico_, ~riscado~) pode ser usada no texto do modelo. A lista de variáveis de cada modelo vem em variaveis no GET /whatsapp-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:
- está vazio ou tem mais de 4096 caracteres;
- usa marcação de variável malformada ou variável que não existe no modelo;
- omite uma variável marcada como
obrigatoria; - 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 precisam ficar isoladas, separadas por espaço ou quebra de linha, aceitando apenas uma pontuação final (.,;:!?).
Os valores das variáveis (nome do cliente, nome de arquivo e similares) entram na mensagem como texto puro: marcadores de formatação do WhatsApp contidos nesses valores não formatam a mensagem.
Endpoints
GET /whatsapp-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/whatsapp-modelos/Response 200 OK
{
"status": "success",
"message": "Modelos recuperados",
"data": {
"itens": [
{
"slug": "iss_aliquota_mensal",
"titulo": "Alíquota do ISS (mensal)",
"descricao": "Orientação mensal da alíquota de ISS a destacar nas notas.",
"destinatario": "cliente",
"anexo": null,
"personalizado": true,
"atualizado_em": "2026-10-20T14:32:10",
"atualizado_por_nome": "Maria Souza"
}
]
}
}Os itens seguem ModeloResumo.
Escopo: whatsapp_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 /whatsapp-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/whatsapp-modelos/historico?slug=iss_aliquota_mensal&page=1&per_page=20Response 200 OK
{
"status": "success",
"message": "Histórico recuperado",
"data": {
"itens": [
{
"id": 9120,
"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: whatsapp_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 /whatsapp-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 /whatsapp-modelos/historico. |
Request
POST /api/v1/whatsapp-modelos/historico/9120/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: whatsapp_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 /whatsapp-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/whatsapp-modelos/iss_aliquota_mensalResponse 200 OK
{
"status": "success",
"message": "Modelo recuperado",
"data": {
"slug": "iss_aliquota_mensal",
"titulo": "Alíquota do ISS (mensal)",
"descricao": "Orientação mensal da alíquota de ISS a destacar nas notas.",
"destinatario": "cliente",
"anexo": null,
"personalizado": false,
"corpo": "Olá, responsável pela empresa: {{cliente.razao_social}}\n...",
"corpo_padrao": "Olá, responsável pela empresa: {{cliente.razao_social}}\n...",
"variaveis": [
{
"nome": "iss.aliquota",
"descricao": "Alíquota de ISS a destacar (%)",
"exemplo": "2,00",
"obrigatoria": true,
"sensivel": false
}
],
"atualizado_em": null,
"atualizado_por_nome": null
}
}O data segue ModeloDetalhe. 404 se o slug não existir.
Escopo: whatsapp_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 /whatsapp-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
{
"corpo": "Olá, {{cliente.razao_social}}.\nA alíquota de ISS a destacar é {{iss.aliquota}}%."
}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: whatsapp_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 /whatsapp-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/whatsapp-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: whatsapp_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 /whatsapp-modelos/{slug}/pre-visualizar
Gera a prévia do rascunho com dados fictícios. Não grava nem envia 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
{
"corpo": "Olá, {{cliente.razao_social}}.\nA alíquota de ISS a destacar é {{iss.aliquota}}%."
}Response 200 OK
{
"status": "success",
"message": "Pré-visualização gerada",
"data": {
"texto": "Olá, Empresa Exemplo Ltda.\nA alíquota de ISS a destacar é 2,00%."
}
}422 se o rascunho violar as regras do conteúdo.
Escopo: whatsapp_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 /whatsapp-modelos/{slug}/enviar-teste
Envia o rascunho como mensagem de teste, prefixada por [TESTE] , para o WhatsApp do usuário logado. O destino não é configurável: campos extras no corpo (como telefone) 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
{
"corpo": "Olá, {{cliente.razao_social}}.\nA alíquota de ISS a destacar é {{iss.aliquota}}%."
}Response 200 OK
{
"status": "success",
"message": "WhatsApp de teste enviado",
"data": {
"enviado_para": "***8888"
}
}O telefone é devolvido mascarado; o número completo não volta na resposta.
Erros
404 (slug desconhecido), 422 (rascunho recusado pelas regras, ou usuário sem telefone válido cadastrado com DDD e número), 502 (o envio foi recusado ou falhou) e 429 (limite de testes por usuário excedido).
Escopo: whatsapp_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 |
|---|---|---|---|
corpo | str | sim | Texto da mensagem, até 4096 caracteres. Veja as regras. |
ModeloResumo
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
slug | str | sim | Identificador do modelo. |
titulo | str | sim | Nome exibível. |
descricao | str | sim | Quando a mensagem é enviada. |
destinatario | "cliente" | sim | Sempre cliente. |
anexo | str | null | não | O que segue junto da mensagem (informativo). |
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 |
|---|---|---|---|
corpo | str | sim | Texto efetivo (personalizado ou padrão). |
corpo_padrao | str | sim | Texto padrã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 texto. |
sensivel | bool | sim | Precisa ficar isolada no texto. |
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 a mensagem 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.