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

Perfil do número

Lê e atualiza o perfil comercial (foto, nome, sobre, endereço, site) do número de WhatsApp do seller.

O perfil comercial vive na Meta. Estas rotas o espelham: a leitura busca o perfil atual e a gravação o reenvia. Pré-requisito: o seller já ter conectado um número.

Ler o perfil

O perfil comercial é o cartão que o cliente vê ao abrir o contato do número no WhatsApp: foto, nome, sobre, descrição, endereço, e-mail e site. Esta rota lê o perfil ao vivo na Meta e completa com o rascunho salvo na plataforma quando a Meta não responde (veja meta_sync).

GET/api/v1/vendor/whatsapp/profileSeller

Retorna o perfil comercial 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/profile" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Perfil
json
{
  "display_name": "Casa do Pão Quente",
  "verified_name": "Casa do Pão Quente",
  "display_phone_number": "+55 41 99999-0000",
  "about": "Pães artesanais e café fresco todos os dias.",
  "description": "Pães artesanais e café fresco todos os dias.",
  "category": "RETAIL",
  "address": "Rua das Flores, 120, Curitiba, PR",
  "email": "contato@casadopao.example.com",
  "website": "https://casadopao.example.com",
  "profile_picture_url": "https://scontent.example.net/v/profile.jpg",
  "photo_on_meta": true,
  "business_phone": "5541999990000",
  "phone_number_id": "109876543210987",
  "verified": true,
  "meta_sync": true,
  "quality_rating": "GREEN",
  "name_status": "APPROVED"
}

Campos da resposta

display_namestring
Nome de exibição que o seller editou. Se nunca editou, repete verified_name.
verified_namestring
Nome oficial aprovado pela Meta. Só leitura: trocá-lo exige revisão da Meta.
display_phone_numberstring
Número como a Meta o mostra.
aboutstring
Texto curto do perfil (a Meta aceita até cerca de 139 caracteres).
descriptionstring
Descrição do negócio (até 512 caracteres).
categorystring
Categoria (vertical) do negócio na Meta, em maiúsculas, como RETAIL.
addressstring
Endereço do negócio (até 256 caracteres).
emailstring
E-mail de contato (até 128 caracteres).
websitestring
Site do negócio. A plataforma acrescenta https:// se faltar.
profile_picture_urlstring
Endereço da foto de perfil.
photo_on_metaboolean
true quando a foto já está publicada na Meta. Um rascunho local não conta.
business_phonestring
Telefone em dígitos usado para roteamento.
phone_number_idstring
Id do número na Meta.
verifiedboolean
A Meta confirmou o número nesta leitura.
meta_syncboolean
true quando pelo menos uma das consultas à Meta funcionou. Se for false, os dados vêm do rascunho local.
meta_errorstring
Último erro da Meta, legível. Omitido quando a sincronia deu certo.
quality_ratingstring
Qualidade do número segundo a Meta: GREEN, YELLOW, RED ou UNKNOWN.
name_statusstring
Situação da revisão do nome na Meta: APPROVED, AVAILABLE_WITHOUT_REVIEW, PENDING_REVIEW, DECLINED, EXPIRED ou NONE. Omitido se a Meta não informa.
warningstring
Aviso não fatal da última gravação (por exemplo, a Meta recusou apagar um campo). O perfil foi salvo. Só aparece no PUT.

Erros

StatusQuandoCorpo de exemplo
404O seller ainda não conectou um número.{"error":"whatsapp number not connected","detail":"whatsapp profile: number not connected"}
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 montar o perfil.{"error":"failed to load profile","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"}

Atualizar o perfil

Grava o perfil na Meta e guarda uma cópia (rascunho) na plataforma. Todos os campos editáveis são enviados, inclusive os vazios, porque a Meta mantém o valor antigo de qualquer campo omitido: mande o perfil completo, não só o que mudou. Enviar um campo em branco o apaga.

O nome de exibição é um caso à parte: o nome oficial do número só muda com revisão da Meta, então a plataforma pede a troca e a resposta traz um warning explicando que o nome antigo continua valendo até a aprovação.

PUT/api/v1/vendor/whatsapp/profileSeller

Envia o perfil comercial do número para a Meta

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

display_namestring
Nome de exibição desejado (até 75 caracteres vão para a Meta). Se for diferente do nome oficial atual, gera um pedido de revisão.
aboutstring
Texto curto. Usado só quando description vem vazia.
descriptionstring
Descrição do negócio. A plataforma envia o mesmo texto como descrição (até 512 caracteres) e como "sobre" (cortado em 139).
categorystring
Categoria (vertical) da Meta, convertida para maiúsculas, como RETAIL. Vazia, não é enviada.
addressstring
Endereço (até 256 caracteres). Vazio apaga.
emailstring
E-mail de contato (até 128 caracteres). Vazio apaga.
websitestring
Site. https:// é acrescentado se faltar. Vazio apaga.
profile_picture_urlstring
Endereço público de uma imagem para a foto de perfil. Se enviado, a foto precisa chegar à Meta ou a gravação falha.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/vendor/whatsapp/profile" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Casa do Pão Quente",
    "description": "Pães artesanais e café fresco todos os dias.",
    "category": "RETAIL",
    "address": "Rua das Flores, 120, Curitiba, PR",
    "email": "contato@casadopao.example.com",
    "website": "https://casadopao.example.com"
  }'

Resposta

200Perfil gravado
json
{
  "display_name": "Casa do Pão Quente",
  "verified_name": "Casa do Pão Quente",
  "display_phone_number": "+55 41 99999-0000",
  "about": "Pães artesanais e café fresco todos os dias.",
  "description": "Pães artesanais e café fresco todos os dias.",
  "category": "RETAIL",
  "address": "Rua das Flores, 120, Curitiba, PR",
  "email": "contato@casadopao.example.com",
  "website": "https://casadopao.example.com",
  "profile_picture_url": "https://scontent.example.net/v/profile.jpg",
  "photo_on_meta": true,
  "business_phone": "5541999990000",
  "phone_number_id": "109876543210987",
  "verified": true,
  "meta_sync": true,
  "quality_rating": "GREEN",
  "name_status": "APPROVED",
  "warning": "Nome de exibição enviado para revisão da Meta. Até a aprovação os clientes continuam vendo “Casa do Pão”."
}

Campos da resposta

display_namestring
Nome de exibição que o seller editou. Se nunca editou, repete verified_name.
verified_namestring
Nome oficial aprovado pela Meta. Só leitura: trocá-lo exige revisão da Meta.
...object
Demais campos iguais aos de Ler o perfil, já relidos depois da gravação.
warningstring
Aviso não fatal da última gravação (por exemplo, a Meta recusou apagar um campo). O perfil foi salvo. Só aparece no PUT.

Erros

StatusQuandoCorpo de exemplo
400Corpo que não é um JSON válido.{"error":"invalid request body","detail":"..."}
403O usuário não tem perfil de seller.{"error":"vendor profile not found"}
404O seller ainda não conectou um número.{"error":"whatsapp number not connected","detail":"whatsapp profile: number not connected"}
502A plataforma não tem token da Meta para esta loja.{"error":"meta credentials missing","detail":"..."}
502A Meta recusou a atualização ou a foto não chegou a ela.{"error":"failed to update profile","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"}
Perfil parcial apaga dados

Como os campos vazios são enviados e a Meta os apaga, um PUT com só email zera endereço, site e descrição. Leia o perfil com o GET, altere o que precisa e devolva tudo.

Nome oficial demora

Ler name_status mostra em que pé está a revisão. Reenviar o mesmo nome não abre um segundo pedido: a Meta conta cada pedido de troca e eles não podem ser cancelados.

Veja também

  • Credencial do número
  • Sugestões de nome e descrição
Anterior
Credencial do número
Próxima
Conectar um número
Nesta página
  • Ler o perfil
  • Exemplo de requisição
  • Resposta
  • Erros
  • Atualizar o perfil
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também