VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/WhatsApp: número e perfil

Credencial do número

Lê, salva, remove e testa a credencial do número de WhatsApp do seller (lojista).

Uma credencial liga o seller a um número de WhatsApp da Meta. Estas quatro operações a gerenciam: ler o estado, salvar um número que já existe, apagar e testar. Todas agem sobre o seller dono do token; o vendor_id nunca vem do corpo da requisição.

Ler a credencial

Devolve o número de WhatsApp que o seller conectou: o phone_number_id da Meta, a conta empresarial e se a credencial já foi validada. Use para desenhar a tela "meu número" e decidir se mostra o assistente de conexão. Se nada foi conectado, a resposta é 200 com os campos vazios (não é um erro).

GET/api/v1/vendor/whatsapp/credentialsSeller

Retorna a credencial do número de WhatsApp do seller

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.

Exemplo de requisição

Resposta

200Credencial conectada
200Nada conectado

Campos da resposta

vendor_iduuid
Id do seller dono do número. Para um usuário da equipe sem perfil de seller próprio, é o seller do número ativo da loja.
phone_number_idstring
Id do número na Meta (phone_number_id), um texto só de dígitos. Vazio quando nada foi conectado.
display_namestring
Nome livre do número, só para você se orientar no painel. Vem do campo display_name do PUT; se ele foi omitido, repete o phone_number_id.
business_account_idstring
Id da conta empresarial (WABA) da Meta à qual o número pertence.
has_tokenboolean
true quando há um token de acesso guardado. O token nunca é devolvido pela API.
verifiedboolean
true quando a credencial está ativa e a plataforma já conseguiu consultar a Meta com ela pelo menos uma vez.
last_verified_atstring
Data da última consulta bem-sucedida à Meta (RFC 3339, UTC). Omitido se nunca houve.
two_step_pinstring
PIN de verificação em duas etapas de 6 dígitos gerado no verify. Omitido se ainda não existe.
route_pendingboolean
Só aparece, com true, no PUT: o número já entrega as mensagens recebidas a outro destino e a plataforma não o sobrescreveu.
route_pending_reasonstring
Motivo de route_pending.

Erros

StatusQuandoCorpo de exemplo
403O usuário não tem perfil de seller e a loja não tem número ativo para assumir.{"error":"vendor profile not found"}
500Falha ao ler a credencial.{"error":"failed to load credentials","detail":"..."}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não é um seller, o módulo de WhatsApp está desligado na loja (module_disabled) ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"module_disabled","module":"whatsapp-commerce"}
O token nunca sai

A API só diz se existe token (has_token). Não há como ler o token de volta. Para trocá-lo, envie um novo auth_token no PUT.

Salvar a credencial

Conecta um número que já existe na Meta: você informa o phone_number_id e a plataforma guarda a credencial, ativa o número e registra para ele a rota de recebimento de mensagens. É o caminho curto, para quem já tem o número cadastrado numa conta empresarial (WABA). Quem ainda não tem o número na Meta usa o cadastro guiado em Conectar um número.

A gravação é um upsert: cada seller tem no máximo uma credencial, e um novo PUT substitui a anterior. Depois de salvar, a plataforma tenta ler o perfil do número na Meta; se der certo, verified passa a true na própria resposta.

PUT/api/v1/vendor/whatsapp/credentialsSeller

Cria ou atualiza a credencial do número de WhatsApp do seller

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.
Content-Typestringobrigatório
application/json.

Corpo da requisição

phone_number_idstringobrigatório
Id do número na Meta. Obrigatório.
display_namestring
Nome livre do número. Omitido ou em branco, a plataforma usa o próprio phone_number_id.
business_account_idstring
Id da conta empresarial (WABA). Omitido, a plataforma usa o da conta da própria Venddor configurada para a loja.
auth_tokenstring
Token permanente de acesso da Meta. Só escrita. Na primeira gravação, se for omitido, a plataforma usa o token dela (WABA compartilhada); nas seguintes, omitir mantém o token já guardado.

Exemplo de requisição

Resposta

200Credencial salva

Campos da resposta

vendor_iduuid
Id do seller dono do número. Para um usuário da equipe sem perfil de seller próprio, é o seller do número ativo da loja.
phone_number_idstring
Id do número na Meta (phone_number_id), um texto só de dígitos. Vazio quando nada foi conectado.
display_namestring
Nome livre do número, só para você se orientar no painel. Vem do campo display_name do PUT; se ele foi omitido, repete o phone_number_id.
business_account_idstring
Id da conta empresarial (WABA) da Meta à qual o número pertence.
has_tokenboolean
true quando há um token de acesso guardado. O token nunca é devolvido pela API.
verifiedboolean
true quando a credencial está ativa e a plataforma já conseguiu consultar a Meta com ela pelo menos uma vez.
last_verified_atstring
Data da última consulta bem-sucedida à Meta (RFC 3339, UTC). Omitido se nunca houve.
two_step_pinstring
PIN de verificação em duas etapas de 6 dígitos gerado no verify. Omitido se ainda não existe.
route_pendingboolean
Só aparece, com true, no PUT: o número já entrega as mensagens recebidas a outro destino e a plataforma não o sobrescreveu.
route_pending_reasonstring
Motivo de route_pending.

Erros

StatusQuandoCorpo de exemplo
400Corpo que não é um JSON válido.{"error":"invalid request body","detail":"..."}
400phone_number_id ausente ou em branco.{"error":"phone_number_id is required"}
400Primeira gravação sem auth_token e a plataforma não tem token próprio configurado.{"error":"missing required field","detail":"whatsapp vendor creds: auth_token required for first save"}
403O usuário não tem perfil de seller.{"error":"vendor profile not found"}
409O número já está conectado a outro seller da loja, é o número da própria loja (num marketplace) ou pertence a outra loja da plataforma. O campo error é o código que a tela traduz: number_in_use ou number_in_use_other_store.{"error":"number_in_use","detail":"Este número já está conectado a outro vendedor desta loja ou é o número da própria loja. Use um número seu ou fale com o administrador."}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não é um seller, o módulo de WhatsApp está desligado na loja (module_disabled) ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"module_disabled","module":"whatsapp-commerce"}
Salvar não prova que funciona

A credencial fica ativa assim que é gravada. Só verified: true indica que a Meta respondeu com ela. Se vier false, chame Verificar a credencial e leia o erro devolvido.

`route_pending`

Um número só entrega mensagens a um destino. Se ele já aponta para outro (outra loja ou outro sistema), o PUT salva a credencial mas não toma a rota, e a resposta traz route_pending: true. Mostre um aviso em vez de um sucesso silencioso.

Remover a credencial

Apaga a credencial guardada do seller (número, conta e token). A remoção é definitiva e só do lado da Venddor: o número continua existindo na Meta e a rota de recebimento não é desfeita. Depois disso o envio do seller cai no número padrão da loja, se houver. Chamar de novo sem credencial também devolve 200.

DELETE/api/v1/vendor/whatsapp/credentialsSeller

Apaga a credencial do número de WhatsApp do seller

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.

Exemplo de requisição

Resposta

200Credencial removida

Campos da resposta

okboolean
Sempre true.

Erros

StatusQuandoCorpo de exemplo
403O usuário não tem perfil de seller.{"error":"vendor profile not found"}
500Falha ao apagar.{"error":"failed to delete credentials","detail":"..."}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não é um seller, o módulo de WhatsApp está desligado na loja (module_disabled) ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"module_disabled","module":"whatsapp-commerce"}
Sem desfazer

O token guardado é perdido. Para reconectar com o mesmo número, será preciso enviar o token de novo ou repetir o cadastro guiado.

Verificar a credencial

Faz uma chamada real à Meta com o token e o phone_number_id do seller. Se a Meta aceitar, a plataforma marca a credencial como ativa e grava a hora (last_verified_at). Use depois do PUT ou quando as mensagens deixarem de sair, para saber se o problema é a credencial. O corpo da requisição é ignorado.

POST/api/v1/vendor/whatsapp/credentials/verifySeller

Confirma na Meta que a credencial funciona

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.

Exemplo de requisição

Resposta

200Credencial válida

Campos da resposta

...object
Mesmos campos de Ler a credencial, com last_verified_at recém-atualizado.

Erros

StatusQuandoCorpo de exemplo
400Não há credencial, ou ela não tem token ou phone_number_id.{"error":"credentials not configured"}
502A Meta recusou ou não respondeu em 15 segundos. O detail traz o status e o início da resposta da Meta.{"error":"Meta verification failed","detail":"Meta returned 401: ..."}
403O usuário não tem perfil de seller.{"error":"vendor profile not found"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não é um seller, o módulo de WhatsApp está desligado na loja (module_disabled) ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"module_disabled","module":"whatsapp-commerce"}

Veja também

  • Conectar um número
  • Perfil do número
Anterior
Visão geral
Próxima
Perfil do número
Nesta página
  • Ler a credencial
  • Exemplo de requisição
  • Resposta
  • Erros
  • Salvar a credencial
  • Exemplo de requisição
  • Resposta
  • Erros
  • Remover a credencial
  • Exemplo de requisição
  • Resposta
  • Erros
  • Verificar a credencial
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/vendor/whatsapp/credentials" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X PUT "$BASE_URL/api/v1/vendor/whatsapp/credentials" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "109876543210987",
    "display_name": "Casa do Pão Quente"
  }'
bash
curl -X DELETE "$BASE_URL/api/v1/vendor/whatsapp/credentials" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/credentials/verify" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "vendor_id": "3f2a8c1e-5b7d-4c2a-9e41-0d6b8a7c1f22",
  "phone_number_id": "109876543210987",
  "display_name": "Casa do Pão Quente",
  "business_account_id": "104938271650321",
  "has_token": true,
  "verified": true,
  "last_verified_at": "2026-10-11T14:32:08Z",
  "two_step_pin": "482913"
}
json
{
  "vendor_id": "3f2a8c1e-5b7d-4c2a-9e41-0d6b8a7c1f22",
  "phone_number_id": "",
  "display_name": "",
  "business_account_id": "",
  "has_token": false,
  "verified": false
}
json
{
  "vendor_id": "3f2a8c1e-5b7d-4c2a-9e41-0d6b8a7c1f22",
  "phone_number_id": "109876543210987",
  "display_name": "Casa do Pão Quente",
  "business_account_id": "104938271650321",
  "has_token": true,
  "verified": true,
  "last_verified_at": "2026-10-11T14:32:08Z",
  "two_step_pin": "482913"
}
json
{
  "ok": true
}
json
{
  "vendor_id": "3f2a8c1e-5b7d-4c2a-9e41-0d6b8a7c1f22",
  "phone_number_id": "109876543210987",
  "display_name": "Casa do Pão Quente",
  "business_account_id": "104938271650321",
  "has_token": true,
  "verified": true,
  "last_verified_at": "2026-10-11T14:32:08Z",
  "two_step_pin": "482913"
}