Número do seller no WhatsApp
Como o seller conecta o seu número de WhatsApp Business à plataforma, mantém o perfil comercial e confere se o número atende ligações.
Para atender clientes no WhatsApp, o seller (lojista) precisa de um número de WhatsApp Business ligado à plataforma. O número pertence a uma conta da Meta (a dona do WhatsApp) e é identificado por um phone_number_id: um código numérico que a Meta gera para cada número, diferente do telefone em si. Esta seção cobre as rotas que ligam, validam e descrevem esse número.
Há dois caminhos para conectar:
- Assistente de cadastro (
self-setup): a plataforma adiciona um número novo à conta da Meta, a Meta envia um código por SMS ou ligação e o seller digita o código para ativar. É o caminho de quem ainda não tem o número no WhatsApp Business. - Credencial manual (
credentials): o número já existe na Meta e o seller informa ophone_number_id(e, opcionalmente, o token). É o caminho de quem já configurou tudo no painel da Meta.
Como funciona
O ciclo de um número
| Estado | verified | O que significa |
|---|---|---|
| Sem credencial | false | O seller ainda não conectou nada; vale o número padrão da loja. |
| Aguardando verificação | false | O número foi adicionado à conta da Meta (register) e a credencial está pendente. A Meta ainda precisa validar o código. |
| Ativo e verificado | true | O código foi aceito, ou a credencial manual passou na conferência (verify). O número recebe e envia mensagens. |
- Cadastrar o número
POST /self-setup/registeradiciona o número e envia o nome e o perfil à Meta. Anote ophone_number_iddevolvido. - Pedir o código
POST /self-setup/request-codefaz a Meta mandar o código por SMS ou ligação de voz. - Confirmar o código
POST /self-setup/verifyativa o número e registra a rota que entrega as mensagens recebidas à loja. - Completar o perfil
PUT /profiledefine foto, descrição, endereço e site que o cliente vê.
Conceitos-chave
Os identificadores da Meta
| Termo | O que é |
|---|---|
phone_number_id | Código do número na Meta. É o que a API usa para enviar e receber. |
business_account_id | Código da conta WhatsApp Business (WABA) que agrupa os números. Necessário para modelos de mensagem. |
Token (auth_token) | Chave de acesso à Meta. Fica criptografada e é só de escrita. |
| Nome de exibição | O nome que o cliente vê. Mudar exige análise da Meta, então demora e pode ser recusado. |
Quem é dono do número
A plataforma recusa conectar um número que já pertence a outro seller da mesma loja, à própria loja (em marketplace) ou a outra loja da plataforma. O erro é 409 com number_in_use ou number_in_use_other_store. Salvar de novo o seu próprio número passa normalmente.
Rota de mensagens recebidas
Ao ativar um número, a plataforma tenta registrar automaticamente a rota que leva as mensagens dele para esta loja. Se o número já entrega para outro destino, ela não sobrescreve e a resposta traz route_pending: true. Nesse caso as mensagens ainda não chegam aqui: procure o suporte da plataforma.
Endpoints
Auth: Seller é um usuário do painel do seller (Authorization: Bearer $TOKEN).
| Método | Rota | O que faz | Auth | Página |
|---|---|---|---|---|
| GET | /api/v1/vendor/whatsapp/credentials | Lê a credencial do número | Seller | Credencial |
| PUT | /api/v1/vendor/whatsapp/credentials | Salva a credencial manualmente | Seller | Credencial |
| DELETE | /api/v1/vendor/whatsapp/credentials | Remove a credencial | Seller | Credencial |
| POST | /api/v1/vendor/whatsapp/credentials/verify | Confere a credencial na Meta | Seller | Credencial |
| POST | /api/v1/vendor/whatsapp/self-setup/register | Adiciona o número e o perfil na Meta | Seller | Assistente de cadastro |
| POST | /api/v1/vendor/whatsapp/self-setup/request-code | Pede o código de verificação | Seller | Assistente de cadastro |
| POST | /api/v1/vendor/whatsapp/self-setup/verify | Confirma o código e ativa | Seller | Assistente de cadastro |
| GET | /api/v1/vendor/whatsapp/self-setup/status | Situação do número na Meta | Seller | Assistente de cadastro |
| POST | /api/v1/vendor/whatsapp/self-setup/suggest-names | Sugere nomes de exibição | Seller | Assistente de cadastro |
| POST | /api/v1/vendor/whatsapp/self-setup/suggest-description | Sugere o texto "Sobre" | Seller | Assistente de cadastro |
| GET | /api/v1/vendor/whatsapp/profile | Lê o perfil comercial | Seller | Perfil comercial |
| PUT | /api/v1/vendor/whatsapp/profile | Atualiza o perfil comercial | Seller | Perfil comercial |
| GET | /api/v1/vendor/whatsapp/diagnostico | Confere se a loja atende ligações | Seller | Ligações |
| GET | /api/v1/vendor/whatsapp/calls | Lista as ligações recebidas | Seller | Ligações |
| GET | /api/v1/vendor/whatsapp/calls/{callID} | Lê uma ligação com a transcrição | Seller | Ligações |
| GET | /api/v1/vendor/whatsapp/calls/{callID}/audio | Baixa a gravação | Seller | Ligações |
Erros comuns
- Procurar o
phone_number_idno telefone. Ele não é o número de telefone: é um código da Meta, visível no painel de desenvolvedores da Meta ou devolvido porregister. - Esperar que
registerjá deixe o número ativo. Ele só adiciona o número. Semrequest-codeeverify, a credencial fica pendente. - Pedir o código várias vezes seguidas. A plataforma impõe um intervalo crescente por método (SMS e voz contam separado). A resposta é
429comretry_after_seconds. - Tentar conectar um segundo número. Com um número ativo,
registerdevolve409 limit_reached, a menos que você enviereplace_existing: true. - Ignorar
route_pending. A credencial foi salva, mas as mensagens do número ainda não chegam a esta loja. - Mudar o nome de exibição e esperar efeito imediato. A Meta analisa; até aprovar, o cliente continua vendo o nome antigo.
- Trocar de número sem remover o antigo. Use
replace_existingou remova a credencial antes.