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

Conectar um número

Cadastra o número de WhatsApp de uma loja na conta compartilhada, pede o código de verificação e conclui o registro na Cloud API.

Para uma loja atender no WhatsApp ela precisa de um número cadastrado na conta empresarial (WABA) da plataforma. O operador pode fazer isso em nome de qualquer loja, sem trocar de painel. O processo tem três passos e uma consulta:

Cadastrar→Pedir código→Verificar→Número ativo
  1. Cadastrar
    POST /setup/register adiciona o número à WABA, grava o perfil comercial e cria a credencial da loja como pendente. Devolve o phone_number_id que os passos seguintes usam.
  2. Pedir o código
    POST /setup/request-code faz a Meta enviar um código por SMS ou ligação ao telefone.
  3. Verificar
    POST /setup/verify confirma o código, registra o número na Cloud API com um PIN aleatório de 6 dígitos, ativa a credencial e tenta criar a rota de callback.
  4. Acompanhar
    GET /setup/status consulta a situação do número na Meta quando quiser.

Todas as chamadas exigem root_admin com o privilégio manage_whatsapp_platform. As rotas aceitam o mesmo store_id (UUID da loja ou storefront_id numérico) para dizer de qual loja é o número.

O número não pode ter WhatsApp pessoal ativo

A Meta recusa um número que já tem uma conta de WhatsApp comum. Apague a conta no aparelho antes de cadastrar; senão o retorno é 409 com kind: "whatsapp_exists".

Cadastrar o número

POST/api/v1/admin/whatsapp-platform/setup/registerAdmin

Cadastrar o número de uma loja na WABA

Adiciona o telefone à WABA da plataforma (ou reaproveita, se uma tentativa anterior já o adicionou), aplica o perfil comercial, cria a credencial pendente da loja e registra a rota de callback. Neste fluxo de operador a rota do número é sempre gravada, mesmo que ele já aponte para outro destino: veja o aviso no fim da página.

Corpo da requisição

store_idstringobrigatório
UUID da loja (tenant) ou o storefront_id numérico. Loja desconhecida devolve 400.
vendor_iduuid
Seller (lojista) dono do número. Se omitido, usa o seller mais antigo e não apagado da loja.
country_codestringpadrão: 55
DDI, só dígitos, sem +.
phone_numberstringobrigatório
Telefone sem o DDI. Qualquer formatação é aceita; só os dígitos contam.
display_namestringobrigatório
Nome comercial enviado à Meta (o verified_name).
display_name_2string
Nome alternativo, guardado para reenviar se a Meta recusar o principal.
display_name_3string
Segundo nome alternativo.
categorystring
Categoria comercial da Meta (por exemplo RETAIL, GROCERY, AUTO).
descriptionstring
Descrição do negócio no perfil.
addressstring
Endereço do negócio.
emailstring
E-mail de contato do perfil.
websitestring
Site principal.
website_2string
Segundo site (a Meta aceita até dois).
usernamestring
@usuário do WhatsApp. Opcional, aplicado em melhor esforço.
profile_picture_urlstring
URL pública da foto do perfil. Opcional, aplicada em melhor esforço.
replace_existingbooleanpadrão: false
Autoriza trocar a credencial já gravada para o seller.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp-platform/setup/register" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "8d1f6a52-3b0e-4e57-9f31-2c4a7b9d0e11",
    "country_code": "55",
    "phone_number": "11 99999-8888",
    "display_name": "Loja Exemplo",
    "category": "RETAIL",
    "email": "contato@lojaexemplo.com.br",
    "website": "https://lojaexemplo.com.br"
  }'

Resposta

200Número cadastrado, aguardando verificação
json
{
  "success": true,
  "data": {
    "phone_number_id": "109876543210987",
    "business_phone": "+5511999998888",
    "already_existed": false,
    "status": "pending_verification"
  }
}

Campos da resposta

successboolean
Sempre true em caso de sucesso.
data.phone_number_idstring
Id do número na Meta. Guarde: os próximos passos pedem.
data.business_phonestring
Telefone no formato + DDI e número, só dígitos.
data.already_existedboolean
true quando o número já estava na WABA de uma tentativa anterior.
data.statusstring
pending_verification
Sempre pending_verification neste passo.

Pedir o código de verificação

POST/api/v1/admin/whatsapp-platform/setup/request-codeAdmin

Fazer a Meta enviar o código por SMS ou voz

A Meta envia um código de verificação ao telefone. Há limites de frequência próprios da plataforma, por método: no mínimo 60 segundos entre dois pedidos do mesmo método, dobrando a cada bloqueio imposto pela Meta (120 s, 240 s...) até 900 s. Se a Meta bloqueia por excesso, a plataforma segura novos pedidos por 15 min, 30 min, 1 h, 2 h, 6 h e por fim 24 h. SMS e voz têm contagens separadas. Se o número já estiver VERIFIED, a chamada responde sucesso sem enviar nada.

Corpo da requisição

store_idstringobrigatório
UUID da loja ou storefront_id.
phone_number_idstringobrigatório
Id devolvido pelo cadastro.
methodstringpadrão: SMS
SMSVOICE
Como receber o código. Qualquer valor diferente de VOICE vira SMS.
200Código solicitado
json
{ "success": true }
429Espera obrigatória
json
{
  "error": "Aguarde 47 segundos para solicitar um novo código via SMS, ou tente outro método.",
  "kind": "rate_limited",
  "retry_after_seconds": 47,
  "method": "SMS"
}

O texto do aviso é montado pelo servidor em português (para voz, diz "ligação" no lugar de "SMS"). Use retry_after_seconds e method para decidir quando liberar o botão de reenvio, ou troque para VOICE.

Verificar o código

POST/api/v1/admin/whatsapp-platform/setup/verifyAdmin

Confirmar o código e registrar o número na Cloud API

Confirma o código recebido, registra o número na Cloud API com um PIN aleatório de 6 dígitos (a verificação em duas etapas), ativa a credencial da loja, reaplica o perfil comercial e tenta criar a rota de callback do número. O PIN é guardado e devolvido na resposta: anote-o, o seller pode precisar dele no gerenciador da Meta.

Corpo da requisição

store_idstringobrigatório
UUID da loja ou storefront_id.
phone_number_idstringobrigatório
Id do número.
codestringobrigatório
Código recebido por SMS ou voz.
200Número verificado e ativo
json
{
  "success": true,
  "two_step_pin": "482915",
  "register_ok": true,
  "data": { "two_step_pin": "482915", "register_ok": true }
}

Campos da resposta

successboolean
true quando o código foi aceito.
two_step_pinstring
PIN de 6 dígitos enviado à Meta no registro.
register_okboolean
true quando a Meta aceitou o registro (ou disse que o número já estava registrado). false indica que o código foi aceito mas o registro falhou: repita o passo.
dataobject
Repete two_step_pin e register_ok.

Consultar o número

GET/api/v1/admin/whatsapp-platform/setup/statusAdmin

Ver a situação de um número na Meta

Consulta a Meta e devolve o nome verificado, o telefone exibido e a situação do código. Serve para acompanhar o fim do processo ou para saber se o número já está VERIFIED antes de pedir outro código.

Parâmetros de consulta

store_idstringobrigatório
UUID da loja ou storefront_id.
phone_number_idstringobrigatório
Id do número.
200Situação do número
json
{
  "success": true,
  "data": {
    "phone_number_id": "109876543210987",
    "verified_name": "Loja Exemplo",
    "display_phone_number": "+55 11 99999-8888",
    "code_verification_status": "VERIFIED"
  }
}

Erros

StatusQuandoCorpo de exemplo
400Corpo inválido{"error":"Invalid request body"}
400phone_number_id ausente (request-code, status){"error":"phone_number_id is required"}
400phone_number_id ou code ausente (verify){"error":"phone_number_id and code are required"}
400store_id vazio ou loja inexistente{"error":"whatsapp root setup: store id required"} (vazio) ou {"error":"whatsapp root setup: store \"x\" not found: ..."}
400Loja sem seller e vendor_id omitido (register){"error":"whatsapp root setup: no vendor found for store, pass vendor_id explicitly: ..."}
401 / 403Sem token / sem ser root_admin com manage_whatsapp_platform{"error":"insufficient permissions"}
409O número já tem WhatsApp ativo (whatsapp_exists), foi apagado há pouco (phone_deleted), a conta atingiu o limite (limit_reached) ou o número já pertence a outro seller ou loja (number_in_use, number_in_use_other_store){"error":"Este número já possui uma conta WhatsApp ativa. ...","kind":"whatsapp_exists"}
429Espera obrigatória entre pedidos de códigoveja acima
503Credenciais da plataforma ausentes ou token inválido ou expirado (config_missing){"error":"Configure o token de acesso da plataforma ...","kind":"config_missing"}
500phone_number ou display_name ausentes no cadastro, código errado, ou qualquer recusa da Meta{"error":"whatsapp self-setup: display name required"}

As mensagens com kind são redigidas em português pelo servidor.

O fluxo de operador sobrescreve a rota do número

Quando a loja conecta o próprio número, a plataforma não toma um número que já aponta para outro destino. No fluxo do operador (estas rotas) a rota é sobrescrita: é assim que um número muda de loja ou migra da plataforma antiga. Confira a rota existente em Rotas de callback antes de conectar um número que já esteja em uso.

Valide antes de chamar

Faltar phone_number ou display_name volta como 500, não como 400. Valide os campos obrigatórios no seu cliente e trate o kind do corpo para decidir a mensagem ao usuário.

Veja também

  • Rotas de callback
  • Saúde, números e webhook
  • Credenciais da plataforma
Anterior
Saúde, números e webhook
Próxima
Rotas de callback
Nesta página
  • Cadastrar o número
  • Exemplo de requisição
  • Resposta
  • Pedir o código de verificação
  • Verificar o código
  • Consultar o número
  • Erros
  • Veja também