API atual/Referência completa/WhatsApp Platform

Rotas de callback

Liga cada número de WhatsApp ao destino que processa as mensagens recebidas, com listagem, criação, exclusão e liga/desliga.

Quando um cliente escreve para um número de WhatsApp, a Meta avisa um único endereço central da plataforma. A rota de callback diz para onde a mensagem vai a partir daí: processar dentro da plataforma Venddor ou encaminhar para um sistema externo (por exemplo, uma loja da plataforma antiga que ainda não foi migrada). Cada rota liga um telefone a um destino.

As rotas ficam no banco mestre. Elas são criadas sozinhas quando uma loja conecta o número, e estas operações servem para o operador conferir, mover um número de destino ou cadastrar um número externo. Exigem root_admin com o privilégio manage_whatsapp_platform.

Listar rotas

GET/api/v1/admin/whatsapp-platform/routesAdmin

Listar todas as rotas e os contadores

Devolve todas as rotas, da mais nova para a mais antiga, e três contadores. Não há paginação nem filtro. Cada rota traz a api_key e o verify_token em texto puro.

200Rotas listadas

json

{
  "routes": [
    {
      "route_id": 14,
      "name": "Loja Exemplo",
      "phone_number": "5511999998888",
      "webhook_url": "platform",
      "verify_token": "testtoken",
      "api_key": "9f2c...64 caracteres hexadecimais...e41b",
      "active": true,
      "created_at": "2026-10-06T14:21:09.317Z",
      "updated_at": "2026-10-06T14:21:09.317Z"
    }
  ],
  "stats": { "total": 1, "active": 1, "inactive": 0 }
}

Campos da resposta

routesarray

Rotas, da mais nova para a mais antiga.

routes[].route_idinteger

Id numérico da rota. É o {id} das rotas de exclusão e liga/desliga.

routes[].namestring

Nome para humanos (normalmente o da loja).

routes[].phone_numberstring

Telefone só com dígitos, com DDI (5511999998888). É único: não existem duas rotas para o mesmo telefone.

routes[].webhook_urlstring

Destino. platform processa dentro da plataforma Venddor; uma URL encaminha a mensagem para esse endereço.

routes[].verify_tokenstring

Token de verificação do destino.

routes[].api_keystring

Chave própria da rota, 64 caracteres hexadecimais, gerada na criação e nunca alterada por atualização.

routes[].activeboolean

Rota inativa não encaminha mensagens.

routes[].created_atstring

Criação, RFC 3339 (UTC).

routes[].updated_atstring

Última alteração, RFC 3339 (UTC).

statsobject

Contadores total, active e inactive (inteiros).

Criar ou atualizar uma rota

POST/api/v1/admin/whatsapp-platform/routesAdmin

Criar uma rota ou atualizar a do mesmo telefone

Uma só operação cria e atualiza, e a chave é o telefone: se já existe rota para o telefone informado, ela é atualizada (a api_key é preservada); senão, uma nova é criada com uma api_key nova. O telefone é normalizado: tudo que não é dígito é removido e o prefixo 55 é acrescentado se o número não começar com 55. Depois disso precisa ter de 12 a 15 dígitos.

Corpo da requisição

namestringobrigatório

Nome da rota. Espaços das pontas são removidos; vazio devolve 400.

phone_numberstringobrigatório

Telefone brasileiro, com ou sem +55, parênteses e hífens.

webhook_urlstringpadrão: a URL padrão das rotas

Destino. Vazio usa a URL padrão configurada em Chave mestra e URL padrão (inicialmente platform). Numa atualização, omitir o campo troca o destino atual pela URL padrão.

verify_tokenstringpadrão: testtoken

Token de verificação do destino. Vazio grava testtoken, inclusive numa atualização.

activebooleanpadrão: true

Se a rota nasce ligada. Omitido mantém true (também numa atualização: omitir religa uma rota desligada).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp-platform/routes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Loja Exemplo",
    "phone_number": "(11) 99999-8888",
    "webhook_url": "platform",
    "active": true
  }'

200Rota criada ou atualizada

json

{
  "route_id": 14,
  "name": "Loja Exemplo",
  "phone_number": "5511999998888",
  "webhook_url": "platform",
  "verify_token": "testtoken",
  "api_key": "9f2c...64 caracteres hexadecimais...e41b",
  "active": true,
  "created_at": "2026-10-06T14:21:09.317Z",
  "updated_at": "2026-10-06T14:21:09.317Z"
}

A resposta é a rota gravada, com os mesmos campos da listagem.

Apagar uma rota

DELETE/api/v1/admin/whatsapp-platform/routes/{id}Admin

Apagar uma rota pelo id

Remove a rota definitivamente. O número deixa de ter destino: as mensagens recebidas nele não chegam a ninguém até uma nova rota ser criada. Apagar um id que não existe também devolve sucesso.

Parâmetros de caminho

idintegerobrigatório

route_id da rota (número inteiro, não UUID).

200Rota apagada

json

{ "success": true }

Ligar ou desligar uma rota

POST/api/v1/admin/whatsapp-platform/routes/{id}/toggleAdmin

Inverter o estado ativo de uma rota

Inverte o campo active e devolve o novo valor. É a forma segura de pausar um destino sem perder a api_key nem o histórico da configuração. Não tem corpo.

Parâmetros de caminho

idintegerobrigatório

route_id da rota.

200Novo estado

json

{ "active": false }

Erros

Status	Quando	Corpo de exemplo
400	Corpo inválido (POST)	`{"error":"Invalid request body"}`
400	`name` vazio	`{"error":"name is required"}`
400	Telefone que, depois de normalizado, não tem entre 12 e 15 dígitos	`{"error":"invalid phone number format: must be a Brazilian number with country code 55"}`
400	`{id}` que não é inteiro (DELETE, toggle)	`{"error":"Invalid id"}`
401 / 403	Sem token / sem ser `root_admin` com `manage_whatsapp_platform`	`{"error":"insufficient permissions"}`
500	`toggle` de uma rota que não existe	`{"error":"route not found"}`
500	Falha de banco em listar, apagar e ligar/desligar	`{"error":"..."}`
400	Falha de banco ao criar ou atualizar (o `POST` devolve qualquer erro como `400`)	`{"error":"..."}`

Veja também

API atual/Referência completa/WhatsApp Platform

Rotas de callback

Liga cada número de WhatsApp ao destino que processa as mensagens recebidas, com listagem, criação, exclusão e liga/desliga.

Listar rotas

GET/api/v1/admin/whatsapp-platform/routesAdmin

Listar todas as rotas e os contadores

Devolve todas as rotas, da mais nova para a mais antiga, e três contadores. Não há paginação nem filtro. Cada rota traz a api_key e o verify_token em texto puro.

200Rotas listadas

json

{
  "routes": [
    {
      "route_id": 14,
      "name": "Loja Exemplo",
      "phone_number": "5511999998888",
      "webhook_url": "platform",
      "verify_token": "testtoken",
      "api_key": "9f2c...64 caracteres hexadecimais...e41b",
      "active": true,
      "created_at": "2026-10-06T14:21:09.317Z",
      "updated_at": "2026-10-06T14:21:09.317Z"
    }
  ],
  "stats": { "total": 1, "active": 1, "inactive": 0 }
}

Campos da resposta

routesarray

Rotas, da mais nova para a mais antiga.

routes[].route_idinteger

Id numérico da rota. É o {id} das rotas de exclusão e liga/desliga.

routes[].namestring

Nome para humanos (normalmente o da loja).

routes[].phone_numberstring

Telefone só com dígitos, com DDI (5511999998888). É único: não existem duas rotas para o mesmo telefone.

routes[].webhook_urlstring

Destino. platform processa dentro da plataforma Venddor; uma URL encaminha a mensagem para esse endereço.

routes[].verify_tokenstring

Token de verificação do destino.

routes[].api_keystring

Chave própria da rota, 64 caracteres hexadecimais, gerada na criação e nunca alterada por atualização.

routes[].activeboolean

Rota inativa não encaminha mensagens.

routes[].created_atstring

Criação, RFC 3339 (UTC).

routes[].updated_atstring

Última alteração, RFC 3339 (UTC).

statsobject

Contadores total, active e inactive (inteiros).

Criar ou atualizar uma rota

POST/api/v1/admin/whatsapp-platform/routesAdmin

Criar uma rota ou atualizar a do mesmo telefone

Corpo da requisição

namestringobrigatório

Nome da rota. Espaços das pontas são removidos; vazio devolve 400.

phone_numberstringobrigatório

Telefone brasileiro, com ou sem +55, parênteses e hífens.

webhook_urlstringpadrão: a URL padrão das rotas

Destino. Vazio usa a URL padrão configurada em Chave mestra e URL padrão (inicialmente platform). Numa atualização, omitir o campo troca o destino atual pela URL padrão.

verify_tokenstringpadrão: testtoken

Token de verificação do destino. Vazio grava testtoken, inclusive numa atualização.

activebooleanpadrão: true

Se a rota nasce ligada. Omitido mantém true (também numa atualização: omitir religa uma rota desligada).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp-platform/routes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Loja Exemplo",
    "phone_number": "(11) 99999-8888",
    "webhook_url": "platform",
    "active": true
  }'

200Rota criada ou atualizada

json

{
  "route_id": 14,
  "name": "Loja Exemplo",
  "phone_number": "5511999998888",
  "webhook_url": "platform",
  "verify_token": "testtoken",
  "api_key": "9f2c...64 caracteres hexadecimais...e41b",
  "active": true,
  "created_at": "2026-10-06T14:21:09.317Z",
  "updated_at": "2026-10-06T14:21:09.317Z"
}

A resposta é a rota gravada, com os mesmos campos da listagem.

Apagar uma rota

DELETE/api/v1/admin/whatsapp-platform/routes/{id}Admin

Apagar uma rota pelo id

Remove a rota definitivamente. O número deixa de ter destino: as mensagens recebidas nele não chegam a ninguém até uma nova rota ser criada. Apagar um id que não existe também devolve sucesso.

Parâmetros de caminho

idintegerobrigatório

route_id da rota (número inteiro, não UUID).

200Rota apagada

json

{ "success": true }

Ligar ou desligar uma rota

POST/api/v1/admin/whatsapp-platform/routes/{id}/toggleAdmin

Inverter o estado ativo de uma rota

Inverte o campo active e devolve o novo valor. É a forma segura de pausar um destino sem perder a api_key nem o histórico da configuração. Não tem corpo.

Parâmetros de caminho

idintegerobrigatório

route_id da rota.

200Novo estado

json

{ "active": false }

Erros

Status	Quando	Corpo de exemplo
400	Corpo inválido (POST)	`{"error":"Invalid request body"}`
400	`name` vazio	`{"error":"name is required"}`
400	Telefone que, depois de normalizado, não tem entre 12 e 15 dígitos	`{"error":"invalid phone number format: must be a Brazilian number with country code 55"}`
400	`{id}` que não é inteiro (DELETE, toggle)	`{"error":"Invalid id"}`
401 / 403	Sem token / sem ser `root_admin` com `manage_whatsapp_platform`	`{"error":"insufficient permissions"}`
500	`toggle` de uma rota que não existe	`{"error":"route not found"}`
500	Falha de banco em listar, apagar e ligar/desligar	`{"error":"..."}`
400	Falha de banco ao criar ou atualizar (o `POST` devolve qualquer erro como `400`)	`{"error":"..."}`