API atual/Referência completa/WhatsApp: conexão

Número da loja: credenciais

Lê, conecta, verifica e desconecta o número de WhatsApp que a loja usa para atender clientes.

O número da loja é o telefone de WhatsApp Business pelo qual o atendimento e o assistente respondem como a própria loja. Estas quatro rotas guardam a ligação entre a loja e esse número na Meta (a dona da API do WhatsApp). Use PUT quando você já tem o phone_number_id e o token da Meta; se o número ainda não existe, use o assistente de cadastro.

Consultar o número

Devolve o número atual da loja ou o estado vazio (campos em branco) quando nada foi conectado. O token nunca é devolvido: só has_token.

GET/api/v1/admin/whatsapp/credentialsAdmin

Mostra o número de WhatsApp conectado à loja

Exemplo de requisição (Consultar o número)

bash

curl "$BASE_URL/api/v1/admin/whatsapp/credentials" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Consultar o número)

200Número conectado

json

{
  "vendor_id": "",
  "phone_number_id": "109876543210987",
  "display_name": "5511999998888",
  "business_account_id": "223344556677889",
  "has_token": true,
  "verified": true,
  "last_verified_at": "2026-10-11T21:33:11Z"
}

Campos da resposta

vendor_idstring

Sempre vazio nesta rota: o número é da loja, não de um seller.

phone_number_idstring

Id do número na Meta (string numérica). Vazio quando a loja ainda não conectou um número.

display_namestring

Rótulo do número guardado na loja (normalmente o telefone). Não é o nome verificado da Meta.

business_account_idstring

Id da conta WhatsApp Business (WABA) na Meta.

has_tokenboolean

true quando há um token de acesso guardado. O token nunca volta na resposta.

verifiedboolean

true quando o número está ativo e já passou por uma verificação bem-sucedida na Meta.

last_verified_atstring

Data da última verificação, RFC 3339. Ausente se nunca verificou.

two_step_pinstring

PIN de duas etapas gerado no cadastro do número. Só aparece quando existe.

route_pendingboolean

true quando o número já entrega as mensagens recebidas em outro destino e a plataforma não sobrescreveu. Só aparece no PUT.

route_pending_reasonstring

Motivo do route_pending.

Erros (Consultar o número)

Status	Quando	Corpo
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O 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"}`

Conectar ou editar o número

Grava o phone_number_id como número da loja (ou altera os campos do número atual). Depois de salvar, a plataforma consulta a Meta para completar o telefone e marcar o número como verificado, e tenta registrar a rota de mensagens recebidas para esta loja.

PUT/api/v1/admin/whatsapp/credentialsAdmin

Conecta um número já existente na Meta como número da loja

Corpo da requisição

phone_number_idstringobrigatório

Id do número na Meta. Espaços nas pontas são removidos.

display_namestring

Rótulo do número (normalmente o telefone com DDD). É guardado como telefone comercial do número.

business_account_idstring

Id da WABA na Meta.

auth_tokenstring

Token de acesso da Meta. Só de escrita: nunca volta. Se você não enviar, vale o token já guardado ou o token compartilhado da plataforma.

Exemplo de requisição (Conectar ou editar o número)

bash

curl -X PUT "$BASE_URL/api/v1/admin/whatsapp/credentials" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "109876543210987",
    "display_name": "5511999998888",
    "business_account_id": "223344556677889",
    "auth_token": "EAAB..."
  }'

Resposta (Conectar ou editar o número)

200Número salvo

json

{
  "vendor_id": "",
  "phone_number_id": "109876543210987",
  "display_name": "5511999998888",
  "business_account_id": "223344556677889",
  "has_token": true,
  "verified": true,
  "last_verified_at": "2026-10-11T21:33:11Z",
  "route_pending": false
}

Campos da resposta

(...)object

Mesmos campos da rota de consulta. route_pending aparece só quando é true.

Erros (Conectar ou editar o número)

Status	Quando	Corpo
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
400	`phone_number_id` vazio.	`{"error":"phone_number_id is required"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O 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"}`
409	O número já está ligado a outra loja. O `detail` traz o código `number_in_use`.	`{"error":"...","detail":"number_in_use"}`

Verificar na Meta

Faz uma chamada de teste à Meta usando o token guardado do número. Se a Meta aceitar, a plataforma grava a data da verificação e o número passa a contar como ativo. Não tem corpo.

POST/api/v1/admin/whatsapp/credentials/verifyAdmin

Testa o token do número na Meta e marca o número como verificado

Exemplo de requisição (Verificar na Meta)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/credentials/verify" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Verificar na Meta)

200Verificado

json

{
  "vendor_id": "",
  "phone_number_id": "109876543210987",
  "display_name": "5511999998888",
  "business_account_id": "223344556677889",
  "has_token": true,
  "verified": true,
  "last_verified_at": "2026-10-11T21:33:11Z"
}

Campos da resposta

(...)object

Mesmo formato da rota de consulta, já com verified: true.

Erros (Verificar na Meta)

Status	Quando	Corpo
400	Não há número, token ou `phone_number_id` guardados.	`{"error":"credentials not configured"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O 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"}`
502	A Meta recusou o token ou o número. O `detail` traz o texto da Meta.	`{"error":"Meta verification failed","detail":"..."}`

Desconectar o número

Desativa o número da loja. É uma exclusão lógica: nenhum dado (conversas, mensagens) é apagado, e o número deixa de receber o atendimento. Para voltar, conecte de novo com PUT.

DELETE/api/v1/admin/whatsapp/credentialsAdmin

Desconecta o número de WhatsApp da loja

Exemplo de requisição (Desconectar o número)

bash

curl -X DELETE "$BASE_URL/api/v1/admin/whatsapp/credentials" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Desconectar o número)

200Desconectado

json

{
  "ok": true
}

Campos da resposta

okboolean

Sempre true quando a chamada funciona.

Erros (Desconectar o número)

Status	Quando	Corpo
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O 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"}`

Veja também

API atual/Referência completa/WhatsApp: conexão

Número da loja: credenciais

Lê, conecta, verifica e desconecta o número de WhatsApp que a loja usa para atender clientes.

Consultar o número

Devolve o número atual da loja ou o estado vazio (campos em branco) quando nada foi conectado. O token nunca é devolvido: só has_token.

GET/api/v1/admin/whatsapp/credentialsAdmin

Mostra o número de WhatsApp conectado à loja

Exemplo de requisição (Consultar o número)

bash

curl "$BASE_URL/api/v1/admin/whatsapp/credentials" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Consultar o número)

200Número conectado

json

{
  "vendor_id": "",
  "phone_number_id": "109876543210987",
  "display_name": "5511999998888",
  "business_account_id": "223344556677889",
  "has_token": true,
  "verified": true,
  "last_verified_at": "2026-10-11T21:33:11Z"
}

Campos da resposta

vendor_idstring

Sempre vazio nesta rota: o número é da loja, não de um seller.

phone_number_idstring

Id do número na Meta (string numérica). Vazio quando a loja ainda não conectou um número.

display_namestring

Rótulo do número guardado na loja (normalmente o telefone). Não é o nome verificado da Meta.

business_account_idstring

Id da conta WhatsApp Business (WABA) na Meta.

has_tokenboolean

true quando há um token de acesso guardado. O token nunca volta na resposta.

verifiedboolean

true quando o número está ativo e já passou por uma verificação bem-sucedida na Meta.

last_verified_atstring

Data da última verificação, RFC 3339. Ausente se nunca verificou.

two_step_pinstring

PIN de duas etapas gerado no cadastro do número. Só aparece quando existe.

route_pendingboolean

true quando o número já entrega as mensagens recebidas em outro destino e a plataforma não sobrescreveu. Só aparece no PUT.

route_pending_reasonstring

Motivo do route_pending.

Erros (Consultar o número)

Status	Quando	Corpo
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O 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"}`

Conectar ou editar o número

PUT/api/v1/admin/whatsapp/credentialsAdmin

Conecta um número já existente na Meta como número da loja

Corpo da requisição

phone_number_idstringobrigatório

Id do número na Meta. Espaços nas pontas são removidos.

display_namestring

Rótulo do número (normalmente o telefone com DDD). É guardado como telefone comercial do número.

business_account_idstring

Id da WABA na Meta.

auth_tokenstring

Token de acesso da Meta. Só de escrita: nunca volta. Se você não enviar, vale o token já guardado ou o token compartilhado da plataforma.

Exemplo de requisição (Conectar ou editar o número)

bash

curl -X PUT "$BASE_URL/api/v1/admin/whatsapp/credentials" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "109876543210987",
    "display_name": "5511999998888",
    "business_account_id": "223344556677889",
    "auth_token": "EAAB..."
  }'

Resposta (Conectar ou editar o número)

200Número salvo

json

{
  "vendor_id": "",
  "phone_number_id": "109876543210987",
  "display_name": "5511999998888",
  "business_account_id": "223344556677889",
  "has_token": true,
  "verified": true,
  "last_verified_at": "2026-10-11T21:33:11Z",
  "route_pending": false
}

Campos da resposta

(...)object

Mesmos campos da rota de consulta. route_pending aparece só quando é true.

Erros (Conectar ou editar o número)

Status	Quando	Corpo
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
400	`phone_number_id` vazio.	`{"error":"phone_number_id is required"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O 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"}`
409	O número já está ligado a outra loja. O `detail` traz o código `number_in_use`.	`{"error":"...","detail":"number_in_use"}`

Verificar na Meta

Faz uma chamada de teste à Meta usando o token guardado do número. Se a Meta aceitar, a plataforma grava a data da verificação e o número passa a contar como ativo. Não tem corpo.

POST/api/v1/admin/whatsapp/credentials/verifyAdmin

Testa o token do número na Meta e marca o número como verificado

Exemplo de requisição (Verificar na Meta)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/credentials/verify" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Verificar na Meta)

200Verificado

json

{
  "vendor_id": "",
  "phone_number_id": "109876543210987",
  "display_name": "5511999998888",
  "business_account_id": "223344556677889",
  "has_token": true,
  "verified": true,
  "last_verified_at": "2026-10-11T21:33:11Z"
}

Campos da resposta

(...)object

Mesmo formato da rota de consulta, já com verified: true.

Erros (Verificar na Meta)

Status	Quando	Corpo
400	Não há número, token ou `phone_number_id` guardados.	`{"error":"credentials not configured"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O 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"}`
502	A Meta recusou o token ou o número. O `detail` traz o texto da Meta.	`{"error":"Meta verification failed","detail":"..."}`

Desconectar o número

Desativa o número da loja. É uma exclusão lógica: nenhum dado (conversas, mensagens) é apagado, e o número deixa de receber o atendimento. Para voltar, conecte de novo com PUT.

DELETE/api/v1/admin/whatsapp/credentialsAdmin

Desconecta o número de WhatsApp da loja

Exemplo de requisição (Desconectar o número)

bash

curl -X DELETE "$BASE_URL/api/v1/admin/whatsapp/credentials" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Desconectar o número)

200Desconectado

json

{
  "ok": true
}

Campos da resposta

okboolean

Sempre true quando a chamada funciona.

Erros (Desconectar o número)

Status	Quando	Corpo
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O 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"}`