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

bash

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

Resposta

200Credencial conectada

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"
}

200Nada conectado

json

{
  "vendor_id": "3f2a8c1e-5b7d-4c2a-9e41-0d6b8a7c1f22",
  "phone_number_id": "",
  "display_name": "",
  "business_account_id": "",
  "has_token": false,
  "verified": false
}

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

Status	Quando	Corpo de exemplo
403	O usuário não tem perfil de seller e a loja não tem número ativo para assumir.	`{"error":"vendor profile not found"}`
500	Falha ao ler a credencial.	`{"error":"failed to load credentials","detail":"..."}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O 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 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

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"
  }'

Resposta

200Credencial salva

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"
}

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

Status	Quando	Corpo de exemplo
400	Corpo que não é um JSON válido.	`{"error":"invalid request body","detail":"..."}`
400	`phone_number_id` ausente ou em branco.	`{"error":"phone_number_id is required"}`
400	Primeira 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"}`
403	O usuário não tem perfil de seller.	`{"error":"vendor profile not found"}`
409	O 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."}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O 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"}`

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

bash

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

Resposta

200Credencial removida

json

{
  "ok": true
}

Campos da resposta

okboolean

Sempre true.

Erros

Status	Quando	Corpo de exemplo
403	O usuário não tem perfil de seller.	`{"error":"vendor profile not found"}`
500	Falha ao apagar.	`{"error":"failed to delete credentials","detail":"..."}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O 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"}`

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

bash

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

Resposta

200Credencial válida

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"
}

Campos da resposta

...object

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

Erros

Status	Quando	Corpo de exemplo
400	Não há credencial, ou ela não tem token ou `phone_number_id`.	`{"error":"credentials not configured"}`
502	A 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: ..."}`
403	O usuário não tem perfil de seller.	`{"error":"vendor profile not found"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O 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

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).

Ler a credencial

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

bash

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

Resposta

200Credencial conectada

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"
}

200Nada conectado

json

{
  "vendor_id": "3f2a8c1e-5b7d-4c2a-9e41-0d6b8a7c1f22",
  "phone_number_id": "",
  "display_name": "",
  "business_account_id": "",
  "has_token": false,
  "verified": false
}

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

Status	Quando	Corpo de exemplo
403	O usuário não tem perfil de seller e a loja não tem número ativo para assumir.	`{"error":"vendor profile not found"}`
500	Falha ao ler a credencial.	`{"error":"failed to load credentials","detail":"..."}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O 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 a credencial

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

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"
  }'

Resposta

200Credencial salva

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"
}

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

Status	Quando	Corpo de exemplo
400	Corpo que não é um JSON válido.	`{"error":"invalid request body","detail":"..."}`
400	`phone_number_id` ausente ou em branco.	`{"error":"phone_number_id is required"}`
400	Primeira 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"}`
403	O usuário não tem perfil de seller.	`{"error":"vendor profile not found"}`
409	O 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."}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O 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"}`

Remover a credencial

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

bash

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

Resposta

200Credencial removida

json

{
  "ok": true
}

Campos da resposta

okboolean

Sempre true.

Erros

Status	Quando	Corpo de exemplo
403	O usuário não tem perfil de seller.	`{"error":"vendor profile not found"}`
500	Falha ao apagar.	`{"error":"failed to delete credentials","detail":"..."}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O 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"}`

Verificar a credencial

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

bash

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

Resposta

200Credencial válida

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"
}

Campos da resposta

...object

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

Erros

Status	Quando	Corpo de exemplo
400	Não há credencial, ou ela não tem token ou `phone_number_id`.	`{"error":"credentials not configured"}`
502	A 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: ..."}`
403	O usuário não tem perfil de seller.	`{"error":"vendor profile not found"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O 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"}`