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

Escopos necessários

  • whatsapp_modelos:read - listagem, consulta de modelo e histórico (rotas GET).
  • 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 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 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â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/whatsapp-modelos/historico?slug=iss_aliquota_mensal&page=1&per_page=20

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

Request

POST /api/v1/whatsapp-modelos/historico/9120/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: 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âmetroTipoLocalObrigatórioDescrição
slugstr (1-60)rotasimIdentificador do modelo.

Request

GET /api/v1/whatsapp-modelos/iss_aliquota_mensal

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

Request

DELETE /api/v1/whatsapp-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: 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âmetroTipoLocalObrigatórioDescrição
slugstr (1-60)rotasimIdentificador 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âmetroTipoLocalObrigatórioDescrição
slugstr (1-60)rotasimIdentificador 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.

CampoTipoObrigatórioObservações
corpostrsimTexto da mensagem, até 4096 caracteres. Veja as regras.

ModeloResumo

CampoTipoObrigatórioObservações
slugstrsimIdentificador do modelo.
titulostrsimNome exibível.
descricaostrsimQuando a mensagem é enviada.
destinatario"cliente"simSempre cliente.
anexostr | nullnãoO que segue junto da mensagem (informativo).
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
corpostrsimTexto efetivo (personalizado ou padrão).
corpo_padraostrsimTexto padrã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 texto.
sensivelboolsimPrecisa ficar isolada no texto.

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 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 PUT persiste o texto.