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

Perfil comercial

Lê e atualiza o perfil público do número de WhatsApp Business do seller: nome, descrição, categoria, endereço, e-mail, site e foto.

O perfil comercial é a ficha que o cliente vê ao abrir o contato da loja no WhatsApp: foto, nome, texto "Sobre", categoria, endereço, e-mail e site. Ele mora na Meta, não na plataforma. Por isso GET consulta a Meta ao vivo e PUT envia as mudanças para lá.

O perfil só existe depois que o número está conectado (Credencial ou Assistente de cadastro). Sem número, as duas rotas respondem 404 whatsapp number not connected.

Ler o perfil

GET/api/v1/vendor/whatsapp/profileSeller

Lê o perfil comercial do número do seller

Junta o que a Meta informa com o último rascunho salvo pelo seller. Se a Meta não responder, a rota ainda devolve o rascunho local, com meta_sync: false e o motivo em meta_error. Efeito colateral: quando a Meta confirma que o número está vivo, a credencial passa a constar como verificada (verified: true), como se você tivesse chamado credentials/verify.

Exemplo de requisição

bash

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

Resposta

200Perfil devolvido

json

{
  "display_name": "Loja Centro",
  "verified_name": "Loja Centro",
  "display_phone_number": "+55 11 99999-0000",
  "about": "Moda e acessórios no centro de São Paulo.",
  "description": "Moda e acessórios no centro de São Paulo. Atendimento de segunda a sábado.",
  "category": "RETAIL",
  "address": "Rua Direita, 100, São Paulo, SP",
  "email": "contato@minhaloja.example.com",
  "website": "https://minhaloja.example.com",
  "profile_picture_url": "https://pps.whatsapp.net/v/t61.24694-24/example.jpg",
  "photo_on_meta": true,
  "business_phone": "+5511999990000",
  "phone_number_id": "104857392011234",
  "verified": true,
  "meta_sync": true,
  "quality_rating": "GREEN",
  "name_status": "APPROVED"
}

Campos da resposta

display_namestring

Nome de exibição que o seller quer ter. É o último salvo; se nunca houve rascunho, cai no verified_name.

verified_namestring

Nome aprovado pela Meta e mostrado ao cliente hoje. Só leitura: mudar exige análise da Meta.

display_phone_numberstring

Telefone como a Meta o exibe.

aboutstring

Texto curto "Sobre" (até 139 caracteres).

descriptionstring

Descrição da empresa (até 512 caracteres).

categorystring

Ramo do negócio, no padrão da Meta (RETAIL, APPAREL, GROCERY...).

addressstring

Endereço comercial (até 256 caracteres).

emailstring

E-mail comercial (até 128 caracteres).

websitestring

Site principal, sempre com https://.

profile_picture_urlstring

URL da foto. Pode ser da Meta ou um rascunho local (/uploads/...).

photo_on_metaboolean

true quando a foto já está publicada na Meta. Um rascunho local não conta como publicado.

business_phonestring

Telefone do número, em formato internacional.

phone_number_idstring

Código do número na Meta.

verifiedboolean

true se a credencial do número está ativa e conferida.

meta_syncboolean

true quando a Meta respondeu a ao menos uma das consultas.

meta_errorstring

Último erro da Meta, quando meta_sync é false.

quality_ratingstring

GREENYELLOWREDUNKNOWN

Qualidade do número segundo a Meta. RED indica risco de limitar os envios.

name_statusstring

APPROVEDAVAILABLE_WITHOUT_REVIEWPENDING_REVIEWDECLINEDEXPIREDNONE

Situação da análise do nome de exibição. Ausente se a Meta não informa.

warningstring

Aviso não fatal da última gravação. Só aparece em respostas do PUT.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"authentication required"}`
403	Token que não é de seller; módulo desligado; sem cadastro de seller	veja o resumo da seção
404	Nenhum número conectado	`{"error":"whatsapp number not connected","detail":"..."}`
500	Falha ao ler	`{"error":"failed to load profile","detail":"..."}`

Atualizar o perfil

PUT/api/v1/vendor/whatsapp/profileSeller

Atualiza o perfil comercial na Meta

Envia o perfil à Meta e guarda um rascunho local. A resposta é o perfil atualizado, com o mesmo formato do GET.

Atenção: o PUT é uma substituição, não um ajuste parcial. Descrição, "Sobre", endereço, e-mail e site são enviados sempre, e um campo que você deixa de fora vai vazio e apaga o valor na Meta. O jeito seguro é ler o perfil com GET, mudar o que precisa e devolver o objeto inteiro.

Corpo da requisição

display_namestring

Nome de exibição desejado. Se diferente do verified_name, abre um pedido de troca de nome na Meta, que analisa antes de aprovar. Reenviar o mesmo nome não gasta outro pedido.

descriptionstring

Descrição da empresa. Até 512 caracteres (o excedente é cortado). O "Sobre" público é gerado a partir dela, cortado em 139 caracteres.

aboutstring

Usado só quando description vem vazio: nesse caso vale como descrição.

categorystring

Ramo do negócio, em maiúsculas, no padrão da Meta. Vazio mantém o atual.

addressstring

Endereço comercial. Até 256 caracteres.

emailstring

E-mail comercial. Até 128 caracteres.

websitestring

Site. Sem https:// a plataforma acrescenta. Se o perfil tem um segundo site (definido no cadastro), ele é mantido.

profile_picture_urlstring

URL pública da nova foto. Se omitida, a foto atual não muda. Se enviada e a Meta não aceitar o arquivo, a chamada inteira 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": "Loja Centro",
    "description": "Moda e acessórios no centro de São Paulo. Atendimento de segunda a sábado.",
    "category": "RETAIL",
    "address": "Rua Direita, 100, São Paulo, SP",
    "email": "contato@minhaloja.example.com",
    "website": "https://minhaloja.example.com"
  }'

Resposta

200Perfil atualizado

json

{
  "display_name": "Loja Centro",
  "verified_name": "Loja Centro",
  "about": "Moda e acessórios no centro de São Paulo. Atendimento de segunda a sábado.",
  "description": "Moda e acessórios no centro de São Paulo. Atendimento de segunda a sábado.",
  "category": "RETAIL",
  "address": "Rua Direita, 100, São Paulo, SP",
  "email": "contato@minhaloja.example.com",
  "website": "https://minhaloja.example.com",
  "photo_on_meta": true,
  "phone_number_id": "104857392011234",
  "verified": true,
  "meta_sync": true,
  "warning": "A Meta não aceitou apagar estes campos do perfil: e-mail. O restante das alterações foi salvo."
}

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid request body","detail":"..."}`
403	Token que não é de seller; módulo desligado; sem cadastro de seller	veja o resumo da seção
404	Nenhum número conectado	`{"error":"whatsapp number not connected","detail":"..."}`
502	A credencial não tem token da Meta	`{"error":"meta credentials missing","detail":"..."}`
502	A Meta recusou a atualização (inclui foto que não foi aceita)	`{"error":"failed to update profile","detail":"..."}`

Veja também

Perfil comercial

Lê e atualiza o perfil público do número de WhatsApp Business do seller: nome, descrição, categoria, endereço, e-mail, site e foto.

O perfil só existe depois que o número está conectado (Credencial ou Assistente de cadastro). Sem número, as duas rotas respondem 404 whatsapp number not connected.

Ler o perfil

GET/api/v1/vendor/whatsapp/profileSeller

Lê o perfil comercial do número do seller

Exemplo de requisição

bash

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

Resposta

200Perfil devolvido

json

{
  "display_name": "Loja Centro",
  "verified_name": "Loja Centro",
  "display_phone_number": "+55 11 99999-0000",
  "about": "Moda e acessórios no centro de São Paulo.",
  "description": "Moda e acessórios no centro de São Paulo. Atendimento de segunda a sábado.",
  "category": "RETAIL",
  "address": "Rua Direita, 100, São Paulo, SP",
  "email": "contato@minhaloja.example.com",
  "website": "https://minhaloja.example.com",
  "profile_picture_url": "https://pps.whatsapp.net/v/t61.24694-24/example.jpg",
  "photo_on_meta": true,
  "business_phone": "+5511999990000",
  "phone_number_id": "104857392011234",
  "verified": true,
  "meta_sync": true,
  "quality_rating": "GREEN",
  "name_status": "APPROVED"
}

Campos da resposta

display_namestring

Nome de exibição que o seller quer ter. É o último salvo; se nunca houve rascunho, cai no verified_name.

verified_namestring

Nome aprovado pela Meta e mostrado ao cliente hoje. Só leitura: mudar exige análise da Meta.

display_phone_numberstring

Telefone como a Meta o exibe.

aboutstring

Texto curto "Sobre" (até 139 caracteres).

descriptionstring

Descrição da empresa (até 512 caracteres).

categorystring

Ramo do negócio, no padrão da Meta (RETAIL, APPAREL, GROCERY...).

addressstring

Endereço comercial (até 256 caracteres).

emailstring

E-mail comercial (até 128 caracteres).

websitestring

Site principal, sempre com https://.

profile_picture_urlstring

URL da foto. Pode ser da Meta ou um rascunho local (/uploads/...).

photo_on_metaboolean

true quando a foto já está publicada na Meta. Um rascunho local não conta como publicado.

business_phonestring

Telefone do número, em formato internacional.

phone_number_idstring

Código do número na Meta.

verifiedboolean

true se a credencial do número está ativa e conferida.

meta_syncboolean

true quando a Meta respondeu a ao menos uma das consultas.

meta_errorstring

Último erro da Meta, quando meta_sync é false.

quality_ratingstring

GREENYELLOWREDUNKNOWN

Qualidade do número segundo a Meta. RED indica risco de limitar os envios.

name_statusstring

APPROVEDAVAILABLE_WITHOUT_REVIEWPENDING_REVIEWDECLINEDEXPIREDNONE

Situação da análise do nome de exibição. Ausente se a Meta não informa.

warningstring

Aviso não fatal da última gravação. Só aparece em respostas do PUT.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"authentication required"}`
403	Token que não é de seller; módulo desligado; sem cadastro de seller	veja o resumo da seção
404	Nenhum número conectado	`{"error":"whatsapp number not connected","detail":"..."}`
500	Falha ao ler	`{"error":"failed to load profile","detail":"..."}`

Atualizar o perfil

PUT/api/v1/vendor/whatsapp/profileSeller

Atualiza o perfil comercial na Meta

Envia o perfil à Meta e guarda um rascunho local. A resposta é o perfil atualizado, com o mesmo formato do GET.

Corpo da requisição

display_namestring

Nome de exibição desejado. Se diferente do verified_name, abre um pedido de troca de nome na Meta, que analisa antes de aprovar. Reenviar o mesmo nome não gasta outro pedido.

descriptionstring

Descrição da empresa. Até 512 caracteres (o excedente é cortado). O "Sobre" público é gerado a partir dela, cortado em 139 caracteres.

aboutstring

Usado só quando description vem vazio: nesse caso vale como descrição.

categorystring

Ramo do negócio, em maiúsculas, no padrão da Meta. Vazio mantém o atual.

addressstring

Endereço comercial. Até 256 caracteres.

emailstring

E-mail comercial. Até 128 caracteres.

websitestring

Site. Sem https:// a plataforma acrescenta. Se o perfil tem um segundo site (definido no cadastro), ele é mantido.

profile_picture_urlstring

URL pública da nova foto. Se omitida, a foto atual não muda. Se enviada e a Meta não aceitar o arquivo, a chamada inteira 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": "Loja Centro",
    "description": "Moda e acessórios no centro de São Paulo. Atendimento de segunda a sábado.",
    "category": "RETAIL",
    "address": "Rua Direita, 100, São Paulo, SP",
    "email": "contato@minhaloja.example.com",
    "website": "https://minhaloja.example.com"
  }'

Resposta

200Perfil atualizado

json

{
  "display_name": "Loja Centro",
  "verified_name": "Loja Centro",
  "about": "Moda e acessórios no centro de São Paulo. Atendimento de segunda a sábado.",
  "description": "Moda e acessórios no centro de São Paulo. Atendimento de segunda a sábado.",
  "category": "RETAIL",
  "address": "Rua Direita, 100, São Paulo, SP",
  "email": "contato@minhaloja.example.com",
  "website": "https://minhaloja.example.com",
  "photo_on_meta": true,
  "phone_number_id": "104857392011234",
  "verified": true,
  "meta_sync": true,
  "warning": "A Meta não aceitou apagar estes campos do perfil: e-mail. O restante das alterações foi salvo."
}

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid request body","detail":"..."}`
403	Token que não é de seller; módulo desligado; sem cadastro de seller	veja o resumo da seção
404	Nenhum número conectado	`{"error":"whatsapp number not connected","detail":"..."}`
502	A credencial não tem token da Meta	`{"error":"meta credentials missing","detail":"..."}`
502	A Meta recusou a atualização (inclui foto que não foi aceita)	`{"error":"failed to update profile","detail":"..."}`