VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/WhatsApp: campanhas

Templates gerenciados

Cria templates na Meta e acompanha, edita, sincroniza e exclui os que a loja administra.

O template gerenciado é o registro local de um template: a plataforma o cria na Meta, guarda o status de aprovação e adiciona configurações próprias (destino do botão, textos padrão, o que o seller pode alterar). Pode ser universal (T, da loja toda) ou de um seller (V). Depois de criar, a Meta analisa o template (minutos a horas) e o status muda de P para A ou R: use a sincronização para atualizar.

Listar

Ordenados por escopo, nome e idioma. Com vendor_id, devolve os universais mais os desse seller.

GET/api/v1/admin/whatsapp/templates/managedAdmin

Lista os templates gerenciados

Parâmetros de consulta

approvedstring
1
1 devolve só os aprovados.
vendor_idstring
UUID do seller.

Exemplo de requisição (Listar)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/templates/managed?approved=1" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar)

200Templates
json
{
  "templates": [
    {
      "id": "9a2b7c1e-3d4f-4a5b-8c6d-7e8f9a0b1c2d",
      "name": "venddor_welcome_loja",
      "language": "pt_BR",
      "category": "UTILITY",
      "status": "A",
      "status_label": "APPROVED",
      "scope": "T",
      "meta_template_id": "1234567890123456",
      "components": [
        {
          "type": "BODY",
          "text": "Olá{{1}}! Bem-vindo(a) à *{{2}}*."
        }
      ],
      "body_param_defaults": [],
      "cta_purpose": "store",
      "cta_label": "Ver loja",
      "seller_body_template": "",
      "allow_seller_edit_params": true,
      "allow_seller_edit_cta": true,
      "created_at": "2026-10-11T20:00:00Z",
      "updated_at": "2026-10-11T20:00:00Z"
    }
  ]
}

Campos da resposta

templatesarray

Templates gerenciados.

idstring
UUID do template gerenciado.
namestring
Nome na Meta (minúsculas, espaços viram sublinhado).
languagestring
Idioma.
categorystring
Categoria.
statusstring
PARX
Situação como letra: P pendente de análise, A aprovado, R rejeitado, X desativado/pausado.
status_labelstring
A mesma situação por extenso: PENDING, APPROVED, REJECTED, DISABLED.
scopestring
TV
T template universal da loja; V template de um seller.
vendor_idstring
UUID do seller, quando scope é V.
meta_template_idstring
Id do template na Meta.
componentsarray
Estrutura no formato da Meta.
body_param_defaultsarray
Valores padrão das variáveis do corpo.
cta_purposestring
Destino padrão do botão: store, cart ou checkout.
cta_labelstring
Texto padrão do botão.
seller_body_templatestring
Texto livre usado dentro da janela de 24 horas.
allow_seller_edit_paramsboolean
O seller pode alterar os valores padrão das variáveis.
allow_seller_edit_ctaboolean
O seller pode alterar o botão.
rejection_reasonstring
Motivo, quando rejeitado.
quality_scorestring
Qualidade informada pela Meta.
synced_atstring
Última sincronização com a Meta.
created_atstring
Criação.
updated_atstring
Última alteração.

Erros (Listar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}

Criar

Envia o template à Meta para análise e grava o registro local como pendente. Você pode informar components no formato da Meta, ou só body_text (e opcionalmente um botão de link dinâmico) e a plataforma monta a estrutura.

POST/api/v1/admin/whatsapp/templates/managedAdmin

Cria um template na Meta e o registra na loja

Corpo da requisição

namestringobrigatório
Nome. Convertido para minúsculas, com espaços em sublinhado.
languagestringpadrão: pt_BR
Idioma.
categorystringpadrão: UTILITY
UTILITYMARKETINGAUTHENTICATION
Categoria.
body_textstring
Texto do corpo, com {{1}}. Obrigatório se não enviar components.
componentsarray
Estrutura completa no formato da Meta (BODY, HEADER, BUTTONS...). Substitui body_text.
url_button_labelstring
Texto do botão de link (cortado em 25 caracteres).
url_button_basestring
Endereço do botão. Se não terminar em {{1}}, a plataforma acrescenta /{{1}}.
scopestringpadrão: T
T universal ou V de um seller (vendor também vale).
vendor_idstring
UUID do seller. Obrigatório com scope V.
body_param_defaultsarray
Valores padrão das variáveis.
cta_purposestringpadrão: store
storecartcheckout
Destino do botão.
cta_labelstringpadrão: Ver loja
Texto padrão do botão.
seller_body_templatestring
Texto livre para uso dentro da janela de 24 horas.
allow_seller_edit_paramsbooleanpadrão: true
Permite o seller mudar as variáveis.
allow_seller_edit_ctabooleanpadrão: true
Permite o seller mudar o botão.
skip_metabooleanpadrão: false
true só grava na loja, sem enviar à Meta, e já marca como aprovado. Serve para demonstração; não permite envio real.

Exemplo de requisição (Criar)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/templates/managed" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "venddor boas vindas",
    "language": "pt_BR",
    "category": "UTILITY",
    "body_text": "Olá{{1}}! Bem-vindo(a) à *{{2}}*.",
    "url_button_label": "Ver loja",
    "url_button_base": "https://minhaloja.io.venddor.com.br/wa/{{1}}",
    "scope": "T"
  }'

Resposta (Criar)

201Criado
json
{
  "template": {
    "id": "9a2b7c1e-3d4f-4a5b-8c6d-7e8f9a0b1c2d",
    "name": "venddor_welcome_loja",
    "language": "pt_BR",
    "category": "UTILITY",
    "status": "P",
    "status_label": "PENDING",
    "scope": "T",
    "meta_template_id": "1234567890123456",
    "components": [
      {
        "type": "BODY",
        "text": "Olá{{1}}! Bem-vindo(a) à *{{2}}*."
      }
    ],
    "body_param_defaults": [],
    "cta_purpose": "store",
    "cta_label": "Ver loja",
    "seller_body_template": "",
    "allow_seller_edit_params": true,
    "allow_seller_edit_cta": true,
    "created_at": "2026-10-11T20:00:00Z",
    "updated_at": "2026-10-11T20:00:00Z"
  },
  "warning": "MARKETING custa mais que UTILITY. Prefira UTILITY para mensagens transacionais."
}

Campos da resposta

templateobject

O template criado.

idstring
UUID do template gerenciado.
namestring
Nome na Meta (minúsculas, espaços viram sublinhado).
languagestring
Idioma.
categorystring
Categoria.
statusstring
PARX
Situação como letra: P pendente de análise, A aprovado, R rejeitado, X desativado/pausado.
status_labelstring
A mesma situação por extenso: PENDING, APPROVED, REJECTED, DISABLED.
scopestring
TV
T template universal da loja; V template de um seller.
vendor_idstring
UUID do seller, quando scope é V.
meta_template_idstring
Id do template na Meta.
componentsarray
Estrutura no formato da Meta.
body_param_defaultsarray
Valores padrão das variáveis do corpo.
cta_purposestring
Destino padrão do botão: store, cart ou checkout.
cta_labelstring
Texto padrão do botão.
seller_body_templatestring
Texto livre usado dentro da janela de 24 horas.
allow_seller_edit_paramsboolean
O seller pode alterar os valores padrão das variáveis.
allow_seller_edit_ctaboolean
O seller pode alterar o botão.
rejection_reasonstring
Motivo, quando rejeitado.
quality_scorestring
Qualidade informada pela Meta.
synced_atstring
Última sincronização com a Meta.
created_atstring
Criação.
updated_atstring
Última alteração.
warningstring
Aviso (por exemplo, categoria MARKETING mais cara). Só quando existe.

Erros (Criar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
422A API do WhatsApp não está configurada (code presente no corpo).{"error":"WhatsApp Cloud API is not fully configured (token + WABA).","code":"...","detail":""}
502Qualquer outra falha: nome ou corpo ausente, vendor_id ausente em escopo V, ou recusa da Meta (Meta create template HTTP 400: ...).{"error":"whatsapp: template name required"}
Erros de validação saem como 502

Esta rota não separa erro seu de erro da Meta: campos faltando também voltam 502. Leia a mensagem em error.

Editar

Ajusta os padrões locais (variáveis, botão, permissões do seller). Se o template ainda estiver pendente ou rejeitado, enviar components ou body_text o recria na Meta.

PUT/api/v1/admin/whatsapp/templates/managed/{id}Admin

Altera as configurações de um template gerenciado

Parâmetros de caminho

idstringobrigatório
UUID do template gerenciado.

Corpo da requisição

body_param_defaultsarray
Valores padrão das variáveis.
cta_purposestring
storecartcheckout
Destino do botão.
cta_labelstring
Texto do botão.
seller_body_templatestring
Texto livre.
allow_seller_edit_paramsboolean
Permissão do seller.
allow_seller_edit_ctaboolean
Permissão do seller.
scopestring
T ou V.
vendor_idstring
Seller, com escopo V.
componentsarray
Nova estrutura (só para pendente ou rejeitado).
body_textstring
Novo corpo.
url_button_labelstring
Texto do botão de link.
url_button_basestring
Endereço do botão.
categorystring
Categoria.

Exemplo de requisição (Editar)

bash
curl -X PUT "$BASE_URL/api/v1/admin/whatsapp/templates/managed/9a2b7c1e-3d4f-4a5b-8c6d-7e8f9a0b1c2d" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cta_label": "Abrir loja",
    "allow_seller_edit_cta": false
  }'

Resposta (Editar)

200Atualizado
json
{
  "template": {
    "id": "9a2b7c1e-3d4f-4a5b-8c6d-7e8f9a0b1c2d",
    "name": "venddor_welcome_loja",
    "language": "pt_BR",
    "category": "UTILITY",
    "status": "A",
    "status_label": "APPROVED",
    "scope": "T",
    "meta_template_id": "1234567890123456",
    "components": [
      {
        "type": "BODY",
        "text": "Olá{{1}}! Bem-vindo(a) à *{{2}}*."
      }
    ],
    "body_param_defaults": [],
    "cta_purpose": "store",
    "cta_label": "Abrir loja",
    "seller_body_template": "",
    "allow_seller_edit_params": true,
    "allow_seller_edit_cta": false,
    "created_at": "2026-10-11T20:00:00Z",
    "updated_at": "2026-10-11T20:00:00Z"
  }
}

Campos da resposta

templateobject
O template atualizado.

Erros (Editar)

StatusQuandoCorpo
400Corpo inválido, template inexistente ou recusa da Meta ao recriar. A mensagem vem em error.{"error":"..."}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}

Excluir

Tenta apagar o template na Meta pelo nome e remove o registro local.

DELETE/api/v1/admin/whatsapp/templates/managed/{id}Admin

Exclui o template na Meta e na loja

Parâmetros de caminho

idstringobrigatório
UUID do template gerenciado.

Exemplo de requisição (Excluir)

bash
curl -X DELETE "$BASE_URL/api/v1/admin/whatsapp/templates/managed/9a2b7c1e-3d4f-4a5b-8c6d-7e8f9a0b1c2d" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Excluir)

200Excluído
json
{
  "ok": true
}

Campos da resposta

okboolean
true.

Erros (Excluir)

StatusQuandoCorpo
400Template inexistente.{"error":"sql: no rows in result set"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
Falha na Meta não bloqueia

O erro da chamada à Meta é ignorado: mesmo se a Meta recusar a exclusão, o registro local some e a resposta é ok. Confira o template no gerenciador da Meta se isso importa.

Sincronizar com a Meta

Lê os templates da conta na Meta e atualiza os registros locais de mesmo nome e idioma. Templates que existem só na Meta entram como universais (T). Sem corpo.

POST/api/v1/admin/whatsapp/templates/managed/syncAdmin

Atualiza status e estrutura dos templates a partir da Meta

Parâmetros de consulta

vendor_idstring
Sincroniza usando as credenciais desse seller.

Exemplo de requisição (Sincronizar com a Meta)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/templates/managed/sync" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Sincronizar com a Meta)

200Sincronizado
json
{
  "synced": 3
}

Campos da resposta

syncedinteger
Templates atualizados ou criados.

Erros (Sincronizar com a Meta)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
422A API do WhatsApp não está configurada.{"error":"...","code":"whatsapp.templates.not_configured"}
502Falha ao falar com a Meta.{"error":"..."}

Veja também

  • Templates da Meta
  • Criar campanha
Anterior
Templates da Meta
Próxima
WhatsApp: catálogo na Meta
Nesta página
  • Listar
  • Exemplo de requisição (Listar)
  • Resposta (Listar)
  • Erros (Listar)
  • Criar
  • Exemplo de requisição (Criar)
  • Resposta (Criar)
  • Erros (Criar)
  • Editar
  • Exemplo de requisição (Editar)
  • Resposta (Editar)
  • Erros (Editar)
  • Excluir
  • Exemplo de requisição (Excluir)
  • Resposta (Excluir)
  • Erros (Excluir)
  • Sincronizar com a Meta
  • Exemplo de requisição (Sincronizar com a Meta)
  • Resposta (Sincronizar com a Meta)
  • Erros (Sincronizar com a Meta)
  • Veja também