API atual/Referência completa/WhatsApp Commerce: número do seller

Credencial do número

Lê, salva, confere e remove a credencial que liga o seller ao seu número de WhatsApp Business na Meta.

A credencial é o registro que diz à plataforma por qual número do WhatsApp o seller envia e recebe mensagens. Use estas rotas quando o número já existe na Meta e você só precisa informá-lo. Para adicionar um número novo, use o assistente de cadastro.

O seller é sempre o dono do token: o corpo nunca escolhe de qual seller é a credencial. O token de acesso da Meta é guardado criptografado e nunca volta em nenhuma resposta; você só vê has_token.

Ler a credencial

GET/api/v1/vendor/whatsapp/credentialsSeller

Lê a credencial do número do seller

Sem credencial salva, devolve 200 com os campos vazios (e has_token: false), não 404. Um usuário da equipe que não tem cadastro de seller próprio pode ver a credencial do número da loja.

Exemplo de requisição

bash

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

Resposta

200Credencial devolvida

json

{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "phone_number_id": "104857392011234",
  "display_name": "+5511999990000",
  "business_account_id": "112233445566778",
  "has_token": true,
  "verified": true,
  "last_verified_at": "2026-10-10T17:45:12-03:00",
  "two_step_pin": "482910"
}

Campos da resposta

vendor_iduuid

Seller dono da credencial.

phone_number_idstring

Código do número na Meta. Vazio se não há credencial.

display_namestring

Rótulo do número (por exemplo o telefone ou o nome que você deu).

business_account_idstring

Código da conta WhatsApp Business (WABA). Pode estar vazio.

has_tokenboolean

true quando há um token de acesso guardado. O token em si nunca é devolvido.

verifiedboolean

true quando a credencial está ativa e já passou na conferência da Meta.

last_verified_atstring

RFC 3339. Quando a conferência passou pela última vez. Ausente se nunca passou.

two_step_pinstring

PIN de verificação em duas etapas de 6 dígitos criado pelo assistente de cadastro. Ausente quando o número foi salvo manualmente.

route_pendingboolean

Só aparece (true) em respostas de PUT. Veja o aviso abaixo.

route_pending_reasonstring

Explicação do route_pending.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"authentication required"}`
403	Token que não é de seller	`{"error":"insufficient permissions"}`
403	Módulo desligado	`{"error":"module_disabled","module":"whatsapp-commerce"}`
403	Usuário sem cadastro de seller e a loja não tem número próprio	`{"error":"vendor profile not found"}`
500	Falha ao ler	`{"error":"failed to load credentials","detail":"..."}`

Salvar a credencial

PUT/api/v1/vendor/whatsapp/credentialsSeller

Salva ou atualiza a credencial do número

Cria a credencial ou atualiza a existente. O token é opcional: sem ele, na primeira vez a plataforma usa o token padrão da loja; em salvamentos seguintes, o token já guardado é mantido. Depois de salvar, a plataforma registra a rota de mensagens recebidas e consulta a Meta para marcar o número como verificado.

Corpo da requisição

phone_number_idstringobrigatório

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

display_namestring

Rótulo livre. Se vazio, vale o próprio phone_number_id.

business_account_idstring

Código da conta WhatsApp Business (WABA). Necessário para listar e gerenciar modelos de mensagem. Se vazio, a plataforma usa o da conta padrão da loja, quando existe.

auth_tokenstring

Token permanente de acesso da Meta. Só escrita: nunca é devolvido.

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": "104857392011234",
    "display_name": "Loja Centro",
    "business_account_id": "112233445566778"
  }'

Resposta

200Credencial salva

json

{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "phone_number_id": "104857392011234",
  "display_name": "+5511999990000",
  "business_account_id": "112233445566778",
  "has_token": true,
  "verified": true,
  "last_verified_at": "2026-10-11T10:02:41-03:00"
}

Os campos são os mesmos da leitura. Note que display_name pode voltar diferente do enviado: ao consultar a Meta, a plataforma corrige esse campo com o telefone real do número.

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid request body","detail":"..."}`
400	`phone_number_id` vazio	`{"error":"phone_number_id is required"}`
400	Primeira vez, sem token e a loja não tem token padrão	`{"error":"missing required field","detail":"..."}`
401 / 403	Autenticação, módulo ou perfil	veja acima
409	O número é de outro seller ou da própria loja	`{"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."}`
409	O número é de outra loja da plataforma	`{"error":"number_in_use_other_store","detail":"Este número já está conectado a outra loja da plataforma. Fale com o suporte para transferi-lo."}`
500	Falha ao salvar	`{"error":"failed to save credentials","detail":"..."}`

Os textos de detail do 409 saem em português; no corpo, o campo error traz o código estável para você tratar.

Conferir a credencial

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

Confere na Meta se a credencial funciona

Sem corpo. A plataforma consulta a Meta com o phone_number_id e o token do próprio seller (o token padrão da loja não é usado aqui, de propósito). Se a Meta aceitar, a credencial é marcada como verificada e last_verified_at é atualizado. A chamada à Meta tem limite de 15 segundos.

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": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "phone_number_id": "104857392011234",
  "display_name": "+5511999990000",
  "business_account_id": "112233445566778",
  "has_token": true,
  "verified": true,
  "last_verified_at": "2026-10-11T10:05:00-03:00"
}

Erros

Status	Quando	Corpo
400	Falta `phone_number_id` ou token guardado	`{"error":"credentials not configured"}`
401 / 403	Autenticação, módulo ou perfil	veja acima
502	A Meta recusou ou não respondeu	`{"error":"Meta verification failed","detail":"Meta returned 401: ..."}`
500	Meta aceitou, mas não foi possível registrar	`{"error":"verified but failed to record","detail":"..."}`

Remover a credencial

DELETE/api/v1/vendor/whatsapp/credentialsSeller

Remove a credencial do número do seller

Apaga a credencial do seller. Depois disso o atendimento do seller volta a usar o número padrão da loja. A conversa já gravada permanece. Esta rota não apaga o número na Meta.

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 }

Erros

Status	Quando	Corpo
401 / 403	Autenticação, módulo ou perfil	veja acima
403	Usuário sem cadastro de seller	`{"error":"vendor profile not found"}`
500	Falha ao remover	`{"error":"failed to delete credentials","detail":"..."}`

Veja também

API atual/Referência completa/WhatsApp Commerce: número do seller

Credencial do número

Lê, salva, confere e remove a credencial que liga o seller ao seu número de WhatsApp Business na Meta.

Ler a credencial

GET/api/v1/vendor/whatsapp/credentialsSeller

Lê a credencial do número do seller

Sem credencial salva, devolve 200 com os campos vazios (e has_token: false), não 404. Um usuário da equipe que não tem cadastro de seller próprio pode ver a credencial do número da loja.

Exemplo de requisição

bash

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

Resposta

200Credencial devolvida

json

{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "phone_number_id": "104857392011234",
  "display_name": "+5511999990000",
  "business_account_id": "112233445566778",
  "has_token": true,
  "verified": true,
  "last_verified_at": "2026-10-10T17:45:12-03:00",
  "two_step_pin": "482910"
}

Campos da resposta

vendor_iduuid

Seller dono da credencial.

phone_number_idstring

Código do número na Meta. Vazio se não há credencial.

display_namestring

Rótulo do número (por exemplo o telefone ou o nome que você deu).

business_account_idstring

Código da conta WhatsApp Business (WABA). Pode estar vazio.

has_tokenboolean

true quando há um token de acesso guardado. O token em si nunca é devolvido.

verifiedboolean

true quando a credencial está ativa e já passou na conferência da Meta.

last_verified_atstring

RFC 3339. Quando a conferência passou pela última vez. Ausente se nunca passou.

two_step_pinstring

PIN de verificação em duas etapas de 6 dígitos criado pelo assistente de cadastro. Ausente quando o número foi salvo manualmente.

route_pendingboolean

Só aparece (true) em respostas de PUT. Veja o aviso abaixo.

route_pending_reasonstring

Explicação do route_pending.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"authentication required"}`
403	Token que não é de seller	`{"error":"insufficient permissions"}`
403	Módulo desligado	`{"error":"module_disabled","module":"whatsapp-commerce"}`
403	Usuário sem cadastro de seller e a loja não tem número próprio	`{"error":"vendor profile not found"}`
500	Falha ao ler	`{"error":"failed to load credentials","detail":"..."}`

Salvar a credencial

PUT/api/v1/vendor/whatsapp/credentialsSeller

Salva ou atualiza a credencial do número

Corpo da requisição

phone_number_idstringobrigatório

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

display_namestring

Rótulo livre. Se vazio, vale o próprio phone_number_id.

business_account_idstring

Código da conta WhatsApp Business (WABA). Necessário para listar e gerenciar modelos de mensagem. Se vazio, a plataforma usa o da conta padrão da loja, quando existe.

auth_tokenstring

Token permanente de acesso da Meta. Só escrita: nunca é devolvido.

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": "104857392011234",
    "display_name": "Loja Centro",
    "business_account_id": "112233445566778"
  }'

Resposta

200Credencial salva

json

{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "phone_number_id": "104857392011234",
  "display_name": "+5511999990000",
  "business_account_id": "112233445566778",
  "has_token": true,
  "verified": true,
  "last_verified_at": "2026-10-11T10:02:41-03:00"
}

Os campos são os mesmos da leitura. Note que display_name pode voltar diferente do enviado: ao consultar a Meta, a plataforma corrige esse campo com o telefone real do número.

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid request body","detail":"..."}`
400	`phone_number_id` vazio	`{"error":"phone_number_id is required"}`
400	Primeira vez, sem token e a loja não tem token padrão	`{"error":"missing required field","detail":"..."}`
401 / 403	Autenticação, módulo ou perfil	veja acima
409	O número é de outro seller ou da própria loja	`{"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."}`
409	O número é de outra loja da plataforma	`{"error":"number_in_use_other_store","detail":"Este número já está conectado a outra loja da plataforma. Fale com o suporte para transferi-lo."}`
500	Falha ao salvar	`{"error":"failed to save credentials","detail":"..."}`

Os textos de detail do 409 saem em português; no corpo, o campo error traz o código estável para você tratar.

Conferir a credencial

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

Confere na Meta se a credencial funciona

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": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "phone_number_id": "104857392011234",
  "display_name": "+5511999990000",
  "business_account_id": "112233445566778",
  "has_token": true,
  "verified": true,
  "last_verified_at": "2026-10-11T10:05:00-03:00"
}

Erros

Status	Quando	Corpo
400	Falta `phone_number_id` ou token guardado	`{"error":"credentials not configured"}`
401 / 403	Autenticação, módulo ou perfil	veja acima
502	A Meta recusou ou não respondeu	`{"error":"Meta verification failed","detail":"Meta returned 401: ..."}`
500	Meta aceitou, mas não foi possível registrar	`{"error":"verified but failed to record","detail":"..."}`

Remover a credencial

DELETE/api/v1/vendor/whatsapp/credentialsSeller

Remove a credencial do número do seller

Apaga a credencial do seller. Depois disso o atendimento do seller volta a usar o número padrão da loja. A conversa já gravada permanece. Esta rota não apaga o número na Meta.

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 }

Erros

Status	Quando	Corpo
401 / 403	Autenticação, módulo ou perfil	veja acima
403	Usuário sem cadastro de seller	`{"error":"vendor profile not found"}`
500	Falha ao remover	`{"error":"failed to delete credentials","detail":"..."}`