Visão geral

Para vender pelo WhatsApp, a loja precisa de um número ligado à Meta (a empresa dona do WhatsApp). Numa loja com vários sellers (lojistas), cada seller pode ter o seu. Esta seção reúne as rotas que o seller usa para conectar, testar e apresentar esse número: a credencial (qual número e qual token), o cadastro guiado para quem ainda não tem o número na Meta, o perfil comercial que o cliente vê e dois ajudantes de texto.

Como funciona

Há dois caminhos para conectar um número, conforme ele já exista ou não na Meta.

1. Escolha o caminho

   Se o telefone já está numa conta empresarial da Meta, vá direto a Salvar a credencial. Se não está, use o cadastro guiado.

2. Cadastre e confirme

   No cadastro guiado: register cria a credencial pendente, request-code faz a Meta mandar o código por SMS ou ligação, e verify confirma o código e ativa o número. Guarde o phone_number_id devolvido no primeiro passo.

3. Teste a credencial

   Chame Verificar a credencial. Se der 200, o número fala com a Meta.

4. Capriche no perfil

   Preencha o perfil comercial: foto, descrição, endereço e site. É o que o cliente vê ao abrir o contato.

Estados da credencial

Conceitos-chave

WABA, phone_number_id e token

A WABA (WhatsApp Business Account) é a conta empresarial da Meta que agrupa números. Cada número tem um phone_number_id (um texto de dígitos que identifica o telefone na API da Meta, diferente do telefone em si) e é acessado com um token de acesso. Na Venddor, a conta da própria plataforma é compartilhada: no cadastro guiado e no primeiro PUT sem auth_token, o seller usa o token da plataforma e não precisa colar segredos.

Quem pode chamar

Estas rotas cuidam do seu número. Não há parâmetro para agir em nome de outro seller. Um usuário da equipe do seller que não tem perfil de seller próprio age sobre o número ativo da loja, quando existe um. As rotas de credencial e perfil não exigem privilégio extra; os três passos finais do cadastro e as sugestões exigem o privilégio vendor_manage_whatsapp (um seller sem grupo de usuários o tem automaticamente).

Número em marketplace

Num marketplace, o número da própria loja e os números dos sellers convivem. Um seller só pode assumir o número da loja se for o único seller ativo; caso contrário recebe 409 number_in_use. Se a loja tem números de vários sellers, as escritas do cadastro guiado exigem entrar com o usuário do seller dono (seller_required_for_number).

Datas e formatos

Datas em RFC 3339 (UTC). Ids de seller são UUID; phone_number_id e business_account_id são textos de dígitos. Mensagens de erro do cadastro guiado vêm em português.

Endpoints

Erros comuns

• Confiar em verified logo após o PUT. false quer dizer que a Meta ainda não respondeu; rode verify e leia o erro.
• Mandar um perfil parcial. O PUT /profile envia campos vazios e a Meta os apaga.
• Esquecer replace_existing. Quem já tem número ativo recebe 409 limit_reached ao cadastrar outro.
• Pedir o código sem esperar. O intervalo é de 60 segundos por método; use retry_after_seconds.
• Usar um número com WhatsApp pessoal ativo. A Meta recusa (whatsapp_exists); a conta do aplicativo precisa ser excluída antes.
• Esperar 400 para campos faltando no register. Hoje volta 500; valide no cliente.

Próximos passos