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

Cadastro do número da loja

Cadastra um número novo no WhatsApp Business em quatro passos: registrar, pedir o código, verificar e acompanhar.

Assistente de cadastro do número da própria loja. Use quando o telefone ainda não está na Meta: a plataforma adiciona o número à conta WhatsApp Business (WABA), a Meta manda um código por SMS ou ligação, você confirma o código e o número entra no ar.

1. Registrar o número

Cria o número na conta WhatsApp Business e guarda o perfil como rascunho. O número ainda não atende ninguém: fica pending_verification até o passo 3.

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

Adiciona o número à WABA e grava o perfil (pendente)

Corpo da requisição

country_codestringpadrão: 55
Código do país, só dígitos, sem +.
phone_numberstringobrigatório
Telefone sem o código do país. Qualquer formatação é aceita: só os dígitos são usados.
display_namestringobrigatório
Nome da empresa que a Meta vai verificar (nome de exibição).
display_name_2string
Nome alternativo, guardado para reenvio se a Meta recusar o principal.
display_name_3string
Segundo nome alternativo.
categorystring
Categoria da Meta (RETAIL, AUTO, GROCERY...).
descriptionstring
Descrição do negócio.
addressstring
Endereço.
emailstring
E-mail.
websitestring
Site principal.
website_2string
Segundo site (a Meta aceita até dois).
usernamestring
@usuário do WhatsApp, opcional. Aplicado se a Meta permitir.
profile_picture_urlstring
URL pública da foto de perfil, opcional.
replace_existingbooleanpadrão: false
true autoriza trocar o número ativo por este novo.

Exemplo de requisição (1. Registrar o número)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/store-setup/register" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "55",
    "phone_number": "11 99999-8888",
    "display_name": "Loja Exemplo",
    "category": "RETAIL",
    "description": "Loja de moda com entrega para todo o Brasil.",
    "email": "contato@lojaexemplo.com.br",
    "website": "https://lojaexemplo.com.br"
  }'

Resposta (1. Registrar o número)

200Número criado
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.
dataobject

Resultado do cadastro.

phone_number_idstring
Id do número na Meta. Use nos próximos passos.
business_phonestring
Telefone, só dígitos, com código do país.
already_existedboolean
true quando a Meta já tinha esse número na WABA.
statusstring
pending_verification até concluir o passo 3.
route_pendingboolean
Só aparece quando true: o número já entrega mensagens a outro destino.

Erros (1. Registrar o número)

StatusQuandoCorpo
400Corpo que não é JSON, campo obrigatório ausente, ou erro de validação da Meta (a resposta traz kind).{"error":"Invalid request body"}
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"}
409kind = limit_reached (a loja já tem número ativo), whatsapp_exists (o telefone já tem conta de WhatsApp), phone_deleted, number_in_use ou number_in_use_other_store.{"error":"...","kind":"limit_reached"}
429kind = rate_limited: pediu código demais. retry_after_seconds diz quando tentar de novo.{"error":"...","kind":"rate_limited","retry_after_seconds":60,"method":"SMS"}
503kind = config_missing: a plataforma não tem token ou WABA para cadastrar números.{"error":"...","kind":"config_missing"}

2. Pedir o código

Pede à Meta que envie o código de 6 dígitos por SMS ou ligação de voz. Se o SMS não chegar, repita com VOICE.

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

A Meta envia o código de validação ao número

Corpo da requisição

phone_number_idstringobrigatório
Id devolvido no passo 1.
methodstringpadrão: SMS
SMSVOICE
Canal do código.

Exemplo de requisição (2. Pedir o código)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/store-setup/request-code" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "109876543210987",
    "method": "SMS"
  }'

Resposta (2. Pedir o código)

200Código pedido
json
{
  "success": true
}

Campos da resposta

successboolean
true quando a Meta aceitou o pedido.

Erros (2. Pedir o código)

StatusQuandoCorpo
400phone_number_id ausente.{"error":"phone_number_id is required"}
400Corpo que não é JSON, campo obrigatório ausente, ou erro de validação da Meta (a resposta traz kind).{"error":"Invalid request body"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O phone_number_id não pertence à loja.{"error":"Número não pertence a esta loja"}
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"}
409kind = limit_reached (a loja já tem número ativo), whatsapp_exists (o telefone já tem conta de WhatsApp), phone_deleted, number_in_use ou number_in_use_other_store.{"error":"...","kind":"limit_reached"}
429kind = rate_limited: pediu código demais. retry_after_seconds diz quando tentar de novo.{"error":"...","kind":"rate_limited","retry_after_seconds":60,"method":"SMS"}
503kind = config_missing: a plataforma não tem token ou WABA para cadastrar números.{"error":"...","kind":"config_missing"}

3. Confirmar o código

Confere o código recebido, conclui o registro na Cloud API da Meta (com o PIN de duas etapas), reaplica o perfil e registra a rota de mensagens recebidas deste número para a loja. Guarde o two_step_pin.

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

Valida o código e coloca o número no ar

Corpo da requisição

phone_number_idstringobrigatório
Id devolvido no passo 1.
codestringobrigatório
Código de 6 dígitos recebido.

Exemplo de requisição (3. Confirmar o código)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/store-setup/verify" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "109876543210987",
    "code": "123456"
  }'

Resposta (3. Confirmar o código)

200Número no ar
json
{
  "success": true,
  "two_step_pin": "482910",
  "register_ok": true,
  "data": {
    "two_step_pin": "482910",
    "register_ok": true
  }
}

Campos da resposta

successboolean
true em caso de sucesso.
two_step_pinstring
PIN de duas etapas definido para o número. Anote: a Meta o pede para mudar o número de aparelho.
register_okboolean
true quando o registro na Cloud API foi concluído.
dataobject
Cópia detalhada do resultado.
route_pendingboolean
Só aparece quando true: o número já entrega mensagens a outro destino e não foi sobrescrito.

Erros (3. Confirmar o código)

StatusQuandoCorpo
400Corpo que não é JSON, campo obrigatório ausente, ou erro de validação da Meta (a resposta traz kind).{"error":"Invalid request body"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403Código ausente ou número que não pertence à loja.{"error":"Número não pertence a esta loja ou código ausente"}
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"}
409kind = limit_reached (a loja já tem número ativo), whatsapp_exists (o telefone já tem conta de WhatsApp), phone_deleted, number_in_use ou number_in_use_other_store.{"error":"...","kind":"limit_reached"}
429kind = rate_limited: pediu código demais. retry_after_seconds diz quando tentar de novo.{"error":"...","kind":"rate_limited","retry_after_seconds":60,"method":"SMS"}
503kind = config_missing: a plataforma não tem token ou WABA para cadastrar números.{"error":"...","kind":"config_missing"}

4. Acompanhar o status

Lê na Meta o nome verificado e a situação do código. Serve para saber se o passo 3 já terminou e se o nome foi aprovado.

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

Mostra o status de verificação do número na Meta

Parâmetros de consulta

phone_number_idstringobrigatório
Id do número na Meta.

Exemplo de requisição (4. Acompanhar o status)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/store-setup/status?phone_number_id=109876543210987" \
  -H "Authorization: Bearer $TOKEN"

Resposta (4. Acompanhar o status)

200Status
json
{
  "success": true,
  "data": {
    "phone_number_id": "109876543210987",
    "verified_name": "Loja Exemplo",
    "display_phone_number": "+55 11 99999-8888",
    "code_verification_status": "VERIFIED"
  }
}

Campos da resposta

dataobject

Estado do número.

phone_number_idstring
Id do número.
verified_namestring
Nome verificado pela Meta (pode estar vazio antes da aprovação).
display_phone_numberstring
Telefone como a Meta o exibe.
code_verification_statusstring
Situação do código, por exemplo NOT_VERIFIED ou VERIFIED.

Erros (4. Acompanhar o status)

StatusQuandoCorpo
400Corpo que não é JSON, campo obrigatório ausente, ou erro de validação da Meta (a resposta traz kind).{"error":"Invalid request body"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O número não pertence à loja.{"error":"Número não pertence a esta loja"}
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"}
409kind = limit_reached (a loja já tem número ativo), whatsapp_exists (o telefone já tem conta de WhatsApp), phone_deleted, number_in_use ou number_in_use_other_store.{"error":"...","kind":"limit_reached"}
429kind = rate_limited: pediu código demais. retry_after_seconds diz quando tentar de novo.{"error":"...","kind":"rate_limited","retry_after_seconds":60,"method":"SMS"}
503kind = config_missing: a plataforma não tem token ou WABA para cadastrar números.{"error":"...","kind":"config_missing"}
Mensagens em português

Os textos de error destes passos são devolvidos em português. Use o campo estável kind para decidir o que mostrar ao usuário.

Veja também

  • Credenciais do número
  • Perfil comercial
Anterior
Perfil comercial do número
Próxima
Cadastro do número de um seller
Nesta página
  • 1. Registrar o número
  • Exemplo de requisição (1. Registrar o número)
  • Resposta (1. Registrar o número)
  • Erros (1. Registrar o número)
  • 2. Pedir o código
  • Exemplo de requisição (2. Pedir o código)
  • Resposta (2. Pedir o código)
  • Erros (2. Pedir o código)
  • 3. Confirmar o código
  • Exemplo de requisição (3. Confirmar o código)
  • Resposta (3. Confirmar o código)
  • Erros (3. Confirmar o código)
  • 4. Acompanhar o status
  • Exemplo de requisição (4. Acompanhar o status)
  • Resposta (4. Acompanhar o status)
  • Erros (4. Acompanhar o status)
  • Veja também