Endpoints de templates

O Switchbord expõe um pequeno conjunto de endpoints autenticados sob /api/templates na aplicação control-plane (apps/app) para gerenciar a biblioteca de templates do WhatsApp do workspace. Todas as rotas exigem um operador autenticado com acesso a settings (owner, admin ou developer); a rota de seed exige adicionalmente owner ou admin. As requisições são restritas ao workspace ativo do chamador — você não pode ver ou alterar templates de outro workspace. Erros de autenticação retornam 401 unauthenticated ou 403 forbidden.

Resumo

Método	Caminho	Finalidade	Papel necessário
GET	`/api/templates`	Lista todos os templates do workspace	acesso a settings
POST	`/api/templates`	Cria um rascunho de template	acesso a settings
GET	`/api/templates/{id}`	Busca um template	acesso a settings
PUT	`/api/templates/{id}`	Atualiza um rascunho de template	acesso a settings
DELETE	`/api/templates/{id}`	Exclui um rascunho (apenas status `draft`)	acesso a settings
POST	`/api/templates/{id}/submit`	Envia um rascunho à Meta para aprovação	acesso a settings
POST	`/api/templates/seed-starter-pack`	Semeia o pacote inicial da GB Viaggi	owner ou admin

GET /api/templates

Lista todos os templates do workspace ativo, ordenados pelos atualizados mais recentemente. Resposta 200

{
  "templates": [
    {
      "id": "b3d2b8f1-...",
      "name": "booking_confirmed",
      "language": "it",
      "category": "UTILITY",
      "status": "approved",
      "parameterFormat": "POSITIONAL",
      "components": [ ... ],
      "variables": ["var1", "var2"],
      "preview": "Prenotazione confermata per var1 a var2.",
      "metaTemplateId": "123456789",
      "rejectionReason": null,
      "updatedAt": "2026-04-22T10:15:00Z"
    }
  ]
}

Erros — 401 unauthenticated, 403 forbidden, 500 internal_error.

POST /api/templates

Cria um novo rascunho de template. O template é armazenado com status = "draft" e não é enviado à Meta. Use POST /api/templates/{id}/submit depois que o rascunho estiver pronto. Corpo da requisição

{
  "name": "winback_30d",
  "language": "it",
  "category": "MARKETING",
  "parameterFormat": "POSITIONAL",
  "components": [
    { "type": "BODY",
      "text": "Ciao {{1}}, è passato un po' dall'ultima volta...",
      "example": { "body_text": [["Marco"]] } }
  ]
}

Campos:

name (string, obrigatório) — letras minúsculas; caracteres não correspondentes são removidos e substituídos por _. Veja name-regex.
language (string, padrão "en_US") — código de locale da Meta, por exemplo "it", "en_US", "pt_BR".
category ("MARKETING" | "UTILITY" | "AUTHENTICATION", padrão "UTILITY").
parameterFormat ("POSITIONAL" | "NAMED", padrão "POSITIONAL").
components (array) — o formato de componente do schema da Meta.

Resposta 200

{ "template": { "id": "...", "status": "draft", ... } }

Erros — 400 create_failed com message descrevendo o erro de banco de dados ou de validação, além de erros de autenticação.

GET /api/templates/

Busca um único template por id. Retorna 404 not_found se o id não existir no workspace do chamador. Resposta 200 — mesmo formato de uma entrada de lista.

PUT /api/templates/

Atualiza um ou mais campos de um rascunho de template. Os campos enviados são aplicados (patched); campos não enviados permanecem inalterados. Corpo da requisição (todos os campos são opcionais)

{
  "name": "winback_30d_v2",
  "language": "it",
  "category": "MARKETING",
  "parameterFormat": "POSITIONAL",
  "components": [ ... ]
}

Resposta 200

{ "template": { ... } }

Erros — 400 update_failed, erros de autenticação.

DELETE /api/templates/

Exclui um rascunho de template. Apenas templates com status = "draft" podem ser excluídos — uma vez enviado, o template é retido para auditoria. Um template que não é rascunho retorna 409 conflict. Resposta 200

{ "ok": true }

Erros — 404 not_found, 409 conflict com "Only draft templates can be deleted", erros de autenticação.

POST /api/templates//submit

Envia um rascunho de template ao endpoint POST /{waba_id}/message_templates da Meta. O Switchbord primeiro executa o validador completo do lado do cliente (as mesmas regras documentadas em Regras de template); se alguma verificação falhar, nenhuma chamada é feita à Meta e é retornado um 400 validation_failed com o array de problemas (issues) que falharam. Em caso de sucesso, a linha do template é atualizada com meta_template_id, status = "pending_approval" e rejection_reason = null. Em caso de rejeição pela Meta (HTTP 4xx com um corpo error), a linha é atualizada com status = "rejected" e rejection_reason = a mensagem legível para humanos da Meta, e um 400 meta_submit_failed é retornado ao chamador com o payload de erro completo da Meta. Resposta 200

{ "template": { "id": "...", "status": "pending_approval", "metaTemplateId": "123456789" } }

Erros

400 validation_failed — o validador do lado do cliente rejeitou o rascunho. issues é o array de issues do Zod.
400 meta_submit_failed — a Meta retornou um erro. meta é o objeto error bruto da Meta (code, subcode, error_user_msg, error_data.details).
400 no_waba — nenhuma conta do WhatsApp Business configurada para o workspace.
400 no_access_token — nenhum access token da Meta no vault do workspace.
404 not_found, erros de autenticação.

POST /api/templates/seed-starter-pack

Semeador (seeder) único, restrito a admins, que envia o pacote inicial da GB Viaggi (8 UTILITY + 5 MARKETING, italiano + inglês quando aplicável) para a Meta e faz upsert das linhas correspondentes na tabela local templates. Seguro para reexecutar — a chave de upsert é (workspace_id, name, locale). Papel necessário: owner ou admin. Corpo da requisição — vazio. Resposta 200

{
  "total": 13,
  "submitted": 11,
  "errored": 2,
  "results": [
    {
      "name": "booking_confirmed",
      "language": "it",
      "category": "UTILITY",
      "status": "submitted",
      "metaTemplateId": "987654321"
    },
    {
      "name": "flash_sale",
      "language": "it",
      "category": "MARKETING",
      "status": "error",
      "error": "Variable parameters in the body text cannot be next to each other."
    }
  ]
}

status por entrada:

submitted — aceito pela Meta, linha armazenada como pending_approval.
error — erro da Meta ou do banco de dados, linha armazenada como rejected com a mensagem da Meta.
skipped — reservado; não é emitido atualmente.

Erros

400 no_waba — nenhuma conta do WhatsApp Business configurada.
400 no_access_token — segredo meta-access-token do vault ausente.
500 internal_error — falha não tratada.
401 unauthenticated, 403 forbidden — o chamador não possui o papel de owner/admin.

Endpoints internos relacionados

Existem duas rotas internas, não públicas, em apps/api para fluxos de sincronização machine-to-machine:

POST /internal/templates — upsert de template do worker para a API após um evento de webhook.
POST /internal/templates/sync — resincronização completa da biblioteca a partir da Meta de volta para o Switchbord.

Essas rotas não são expostas publicamente e não devem ser chamadas a partir do frontend. Veja a Especificação da API Interna para a lista oficial.

OpenAPI

O formato legível por máquina para esses endpoints será gerado em apps/docs/api-reference/openapi.json por pnpm openapi:generate. Execute o gerador após alterar uma rota para manter a especificação sincronizada.

​Resumo

​GET /api/templates

​POST /api/templates

​GET /api/templates/

​PUT /api/templates/

​DELETE /api/templates/

​POST /api/templates//submit

​POST /api/templates/seed-starter-pack

​Endpoints internos relacionados

​OpenAPI