VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/WhatsApp Commerce: canal e catálogo

Mini-loja

Configura a aparência da mini-loja aberta pelo WhatsApp, envia imagens para ela e manda o link a um cliente pelo melhor caminho disponível.

A mini-loja é a página web leve que o cliente abre por um link dentro do WhatsApp: vitrine, carrinho e pedido, com o cliente já reconhecido pelo telefone. A aparência dela (logo, cores, faixa de destaque, rodapé) é definida aqui.

A aparência é da loja inteira

Existe uma única configuração de aparência por loja, não uma por seller. Quando um seller grava web-preview/settings, a mudança vale para todos. Combine com a equipe antes de alterar uma loja com vários sellers.

Ler a aparência

GET/api/v1/vendor/whatsapp/web-preview/settingsSeller

Lê a aparência da mini-loja

Campos que o seller não preencheu aparecem vazios; nesse caso a mini-loja herda logo e cores do tema da loja. Os campos brand_* mostram o que seria herdado, só para você exibir de referência.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/whatsapp/web-preview/settings" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Aparência
json
{
  "store_name": "Loja Centro",
  "brand_logo_url": "https://minhaloja.io.venddor.com.br/uploads/logo.png",
  "brand_header_color": "#0F172A",
  "brand_accent_color": "#16A34A",
  "logo_media_id": "",
  "header_color": "",
  "accent_color": "#16A34A",
  "hero_media_id": "5d0c1a44-8f0e-4d6b-9a4e-0b8f7c1e2a33",
  "hero_title": "Frete grátis acima de R$ 200",
  "hero_subtitle": "Só até domingo",
  "greeting_template": "Oi, {{customer_name}}! Veja as novidades.",
  "card_style": "C",
  "footer_info": { "hours_summary": "Seg a sáb, 9h às 18h" },
  "hours_summary": "Seg a sáb, 9h às 18h",
  "updated_at": "2026-10-10T18:00:00Z"
}

Campos da resposta

store_namestring
Nome da loja (só leitura).
brand_logo_urlstring
Logo herdado do tema. Só leitura.
brand_header_colorstring
Cor de cabeçalho herdada do tema. Só leitura.
brand_accent_colorstring
Cor de destaque herdada do tema. Só leitura.
logo_media_idstring
Id da imagem do logo, enviada por web-preview/media. Vazio herda o do tema.
header_colorstring
Cor do cabeçalho em #RGB ou #RRGGBB. Vazio herda a do tema.
accent_colorstring
Cor de destaque em #RGB ou #RRGGBB. Vazio herda a do tema.
hero_media_idstring
Id da imagem da faixa de destaque.
hero_titlestring
Título da faixa de destaque.
hero_subtitlestring
Subtítulo da faixa.
greeting_templatestring
Saudação mostrada ao cliente. Aceita variáveis como {{customer_name}}.
card_stylestring
Estilo dos cartões de produto, uma letra. O padrão é C.
pinned_collectionsarray
Coleções fixadas no topo. Ausente se não houver.
footer_infoobject
Dados do rodapé, como o texto, o resumo de horário e a opção de mostrar o endereço da loja. Ausente se não houver.
hours_summarystring
Resumo de horário, o mesmo que está dentro de footer_info.
updated_atstring
RFC 3339. Última alteração.

Erros

StatusQuandoCorpo
401Sem token{"error":"authentication required"}
403Token que não é de seller; módulo desligado; falta o privilégio{"error":"insufficient permissions"} e demais
404Usuário sem cadastro de seller{"error":"vendor profile not found","code":"vendor_profile_not_found"}
500Falha ao ler{"error":"..."}

Gravar a aparência

PUT/api/v1/vendor/whatsapp/web-preview/settingsSeller

Grava a aparência da mini-loja

Devolve a aparência já atualizada, no formato da leitura. Cuidado com as duas regras diferentes:

  • Os campos simples (logo_media_id, cores, faixa, saudação, card_style) são substituídos: o que você não enviar volta para vazio e passa a herdar o tema. card_style vazio vira C.
  • pinned_collections e footer_info são mesclados com o que já existe: quem não enviar mantém o valor atual.

Por isso, o jeito seguro é ler, alterar o necessário e devolver o objeto inteiro.

Corpo da requisição

logo_media_idstring
Id do logo. Vazio herda o do tema.
header_colorstring
Cor do cabeçalho. Aceita #RGB e #RRGGBB; um # repetido (##004590) é corrigido. Vazio herda do tema.
accent_colorstring
Cor de destaque, no mesmo formato.
hero_media_idstring
Id da imagem da faixa de destaque.
hero_titlestring
Título da faixa.
hero_subtitlestring
Subtítulo da faixa.
greeting_templatestring
Saudação ao cliente.
card_stylestringpadrão: C
Estilo dos cartões, uma letra.
pinned_collectionsarray
Coleções fixadas. Mesclado.
footer_infoobject
Rodapé. Pode ser um objeto ou, por compatibilidade, um texto simples (guardado como text). Mesclado chave a chave.
hours_summarystring
Resumo de horário, guardado dentro de footer_info. Enviar "" apaga.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/vendor/whatsapp/web-preview/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "accent_color": "#16A34A",
  "hero_title": "Frete grátis acima de R$ 200",
  "hero_subtitle": "Só até domingo",
  "greeting_template": "Oi, {{customer_name}}! Veja as novidades.",
  "card_style": "C",
  "hours_summary": "Seg a sáb, 9h às 18h"
}'

Resposta

200Aparência atualizada
json
{
  "store_name": "Loja Centro",
  "accent_color": "#16A34A",
  "hero_title": "Frete grátis acima de R$ 200",
  "hero_subtitle": "Só até domingo",
  "greeting_template": "Oi, {{customer_name}}! Veja as novidades.",
  "card_style": "C",
  "footer_info": { "hours_summary": "Seg a sáb, 9h às 18h" },
  "hours_summary": "Seg a sáb, 9h às 18h",
  "updated_at": "2026-10-11T16:00:00Z"
}

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid body"}
400Cor que não é #RGB/#RRGGBB{"error":"invalid_color"}
401 / 403Autenticação, módulo ou privilégioveja acima
500Falha ao gravar{"error":"..."}

Enviar uma imagem

POST/api/v1/vendor/whatsapp/web-preview/mediaSeller

Envia uma imagem de logo ou de faixa para a mini-loja

Corpo multipart/form-data. O destino é fixo (a aparência da mini-loja): você não escolhe dono. Só aceita imagens raster, para que o ajuste da mini-loja não vire uma porta para o envio de arquivos genéricos.

Corpo da requisição

filefileobrigatório
A imagem, até 10 MB. Tipos aceitos: JPEG, PNG, GIF, WebP e AVIF. O tipo é detectado pelo conteúdo.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/web-preview/media" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@faixa-promocao.jpg"

Resposta

201Imagem recebida
json
{
  "id": "5d0c1a44-8f0e-4d6b-9a4e-0b8f7c1e2a33",
  "owner_id": "appearance",
  "owner_type": "whatsapp_minishop",
  "filename": "faixa-promocao.jpg",
  "content_type": "image/jpeg",
  "size": 120344,
  "url": "/uploads/dfe2555e/whatsapp_minishop/faixa-promocao.jpg",
  "position": 0,
  "created_at": "2026-10-11T15:55:00Z"
}

Campos da resposta

iduuid
Id da imagem. Use em logo_media_id ou hero_media_id.
urlstring
URL da imagem (completa ou como caminho /uploads/...).
filenamestring
Nome original.
content_typestring
Tipo detectado.
sizeinteger
Tamanho em bytes.
owner_typestring
Sempre whatsapp_minishop.
owner_idstring
Sempre appearance.
created_atstring
RFC 3339.

Erros

StatusQuandoCorpo
400Corpo que não é multipart ou grande demais{"error":"failed to parse multipart form","detail":"..."}
400Falta file{"error":"file is required","detail":"..."}
400Não é imagem raster (SVG, PDF e MP4 são recusados aqui){"error":"unsupported file type","detail":"Mini-shop assets accept JPEG, PNG, GIF, WebP, or AVIF images only. Detected: application/pdf"}
401 / 403Autenticação, módulo ou privilégioveja acima
500Falha ao gravar{"error":"failed to upload file","detail":"..."}

Enviar a mini-loja a um telefone

POST/api/v1/vendor/whatsapp/web-preview/sendSeller

Envia o link da mini-loja a um telefone pelo melhor caminho disponível

Cria um link personalizado para o telefone e escolhe o caminho de entrega sozinha:

  1. Se os fluxos nativos da Meta estão ligados na loja, abre o formulário nativo no lugar do link (mode: "native_flow").
  2. Se o cliente escreveu nas últimas 24 horas, envia um botão com link (cta_url). Se o botão falhar, tenta texto com pré-visualização do link.
  3. Fora da janela de 24 horas, envia um modelo aprovado com botão de link. Sem modelo, falha.

É a única rota deste conjunto que pode iniciar a conversa com um número que não escreveu antes. O seller responde pelo consentimento do cliente.

Corpo da requisição

phonestringobrigatório
Telefone do cliente, com DDI e DDD. Qualquer formatação é aceita.
purposestringpadrão: store
storecartcheckout
Para onde o link leva: a loja, o carrinho ou o checkout.
bodystring
Texto da mensagem. Aceita variáveis como {{vendor_name}} e {{customer_name}}. Se omitido, usa o texto do modelo gerenciado ou uma frase padrão.
cta_labelstringpadrão: Ver loja
Rótulo do botão (até 20 caracteres).
managed_template_iduuid
Modelo gerenciado a usar fora da janela de 24 horas.
template_namestring
Nome do modelo da Meta, se não usar managed_template_id.
template_paramsarray
Valores das variáveis do modelo, na ordem. Se omitido, usa os padrões do modelo gerenciado.
force_templatebooleanpadrão: false
Ignora a janela de 24 horas e envia sempre por modelo.
prefer_text_previewbooleanpadrão: false
Dentro da janela, envia texto com pré-visualização do link em vez de botão.
vendor_iduuid
Ignorado para sellers: vale o seller do token.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/web-preview/send" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "5511999990000",
  "purpose": "store",
  "body": "Oi! Veja as ofertas da semana na {{vendor_name}}.",
  "cta_label": "Ver ofertas"
}'

Resposta

200Mensagem enviada
json
{
  "result": {
    "mode": "cta_url",
    "url": "https://minhaloja.io.venddor.com.br/wa/eyJ0IjoicyJ9",
    "message_id": 48240,
    "window_open": true
  },
  "message": {
    "id": 48240,
    "phone_number": "5511999990000",
    "message_type": "interactive",
    "status": "sent",
    "created_at": "2026-10-11T16:05:00Z"
  }
}

Campos da resposta

result.modestring
cta_urltext_previewtemplatenative_flow
Como foi entregue.
result.urlstring
O link gerado para o cliente. Vazio em native_flow.
result.message_idinteger
Id da mensagem registrada.
result.window_openboolean
true se o cliente escreveu nas últimas 24 horas.
result.warningstring
Aviso não fatal em português, por exemplo quando o botão falhou e o envio caiu para texto, ou quando foi usado modelo por a janela estar fechada.
messageobject
A mensagem registrada, com id, phone_number, message_type, status e created_at.

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid json"}
401 / 403Autenticação, módulo ou privilégioveja acima
502Falha no envio. Inclui janela fechada sem modelo configurado{"error":"whatsapp: janela de 24h fechada e nenhum template configurado ... crie/aprove um template com botão URL /wa/{{1}}","result":{...}}
Fora da janela, tenha um modelo pronto

Crie e aprove na Meta um modelo com botão de link terminado em /wa/{{1}} (use as sugestões de Modelos e links) e informe managed_template_id. Sem isso, qualquer envio a um cliente que não escreve há mais de 24 horas falha com 502.

Veja também

  • Modelos e links
  • Fluxos nativos da Meta
  • Caixa de entrada: carrinho e cobrança
Anterior
Modelos e links
Próxima
Mini-loja do WhatsApp
Nesta página
  • Ler a aparência
  • Exemplo de requisição
  • Resposta
  • Erros
  • Gravar a aparência
  • Exemplo de requisição
  • Resposta
  • Erros
  • Enviar uma imagem
  • Exemplo de requisição
  • Resposta
  • Erros
  • Enviar a mini-loja a um telefone
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também