VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/WhatsApp: conexão

Mini-loja no WhatsApp

Aparência da mini-loja aberta dentro do WhatsApp, envio do link ao cliente e pré-visualização dos links personalizados.

A mini-loja é a página leve da loja que abre dentro do navegador do WhatsApp quando o cliente toca no botão da conversa. O link carrega um token que identifica o cliente e a loja (por isso é chamado de link personalizado). Estas rotas configuram a aparência, enviam o link a um cliente e geram uma amostra de links.

Ler a aparência

Devolve as escolhas da loja e, ao lado, a marca do tema (brand_*) usada quando a escolha está em branco.

GET/api/v1/admin/whatsapp/web-preview/settingsAdmin

Lê as configurações visuais da mini-loja

Exemplo de requisição (Ler a aparência)

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

Resposta (Ler a aparência)

200Aparência
json
{
  "store_name": "Loja Exemplo",
  "brand_logo_url": "/uploads/tenant/theme/logo/logo.png",
  "brand_header_color": "#2563eb",
  "brand_accent_color": "#2563eb",
  "logo_media_id": "",
  "header_color": "",
  "accent_color": "",
  "hero_media_id": "",
  "hero_title": "",
  "hero_subtitle": "",
  "greeting_template": "",
  "card_style": "C",
  "updated_at": "2026-07-30T04:13:07.992553Z"
}

Campos da resposta

store_namestring
Nome da loja, do cadastro.
brand_logo_urlstring
Logo do tema da loja. Usado se logo_media_id estiver vazio.
brand_header_colorstring
Cor de cabeçalho do tema.
brand_accent_colorstring
Cor de destaque do tema.
logo_media_idstring
Id de mídia do logo escolhido para a mini-loja. Vem do envio de imagem abaixo.
header_colorstring
Cor do cabeçalho (#RGB ou #RRGGBB). Vazio herda a do tema.
accent_colorstring
Cor de destaque. Vazio herda a do tema.
hero_media_idstring
Id de mídia da imagem de capa.
hero_titlestring
Título da capa.
hero_subtitlestring
Subtítulo da capa.
greeting_templatestring
Texto de boas-vindas.
card_stylestring
Estilo dos cartões de produto. Padrão C.
pinned_collectionsarray
Coleções fixadas no topo, se houver.
footer_infoobject
Informações do rodapé, como horários.
hours_summarystring
Resumo de horários exibido no rodapé.
updated_atstring
Última alteração, RFC 3339.

Erros (Ler a aparência)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}

Salvar a aparência

Substitui as configurações. Campos de texto omitidos ficam em branco (herdam o tema). Devolve a configuração já salva, no mesmo formato do GET.

PUT/api/v1/admin/whatsapp/web-preview/settingsAdmin

Salva as configurações visuais da mini-loja

Corpo da requisição

logo_media_idstring
Id de mídia do logo.
header_colorstring
Cor #RGB ou #RRGGBB. Um # duplicado (##004590) é corrigido; vazio herda o tema.
accent_colorstring
Cor de destaque, mesmas regras.
hero_media_idstring
Id de mídia da capa.
hero_titlestring
Título da capa.
hero_subtitlestring
Subtítulo da capa.
greeting_templatestring
Texto de boas-vindas.
card_stylestringpadrão: C
Estilo dos cartões.
pinned_collectionsarray
Coleções fixadas (JSON livre).
footer_infoobject
Rodapé: texto ou objeto.
hours_summarystring
Resumo de horários. Se enviado vazio, apaga o horário salvo.

Exemplo de requisição (Salvar a aparência)

bash
curl -X PUT "$BASE_URL/api/v1/admin/whatsapp/web-preview/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "header_color": "#0F766E",
    "accent_color": "#F59E0B",
    "hero_title": "Moda para o seu dia",
    "hero_subtitle": "Entrega para todo o Brasil",
    "greeting_template": "Olá! Escolha o que quer ver.",
    "card_style": "C",
    "hours_summary": "Seg a Sex, 9h às 18h"
  }'

Resposta (Salvar a aparência)

200Aparência salva
json
{
  "store_name": "Loja Exemplo",
  "header_color": "#0F766E",
  "accent_color": "#F59E0B",
  "hero_title": "Moda para o seu dia",
  "hero_subtitle": "Entrega para todo o Brasil",
  "greeting_template": "Olá! Escolha o que quer ver.",
  "card_style": "C",
  "hours_summary": "Seg a Sex, 9h às 18h"
}

Campos da resposta

(...)object
Mesmos campos do GET.

Erros (Salvar a aparência)

StatusQuandoCorpo
400Corpo que não é JSON (invalid body) ou cor inválida (invalid_color).{"error":"invalid_color"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
Reenvie o que quer manter

Esta rota grava todos os campos de texto. Se você mandar só header_color, o título, o subtítulo e a saudação voltam ao vazio. Leia com GET, altere e devolva tudo.

Enviar imagem da mini-loja

Recebe um arquivo e devolve o registro da mídia. O id devolvido vai em logo_media_id ou hero_media_id da rota de aparência. Aceita só imagens raster: JPEG, PNG, GIF, WebP e AVIF; até 10 MB. O tipo é conferido pelo conteúdo, não pelo cabeçalho.

POST/api/v1/admin/whatsapp/web-preview/mediaAdmin

Envia uma imagem (logo ou capa) para a mini-loja

Corpo da requisição

filefileobrigatório
Arquivo de imagem, em multipart/form-data.

Exemplo de requisição (Enviar imagem da mini-loja)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/web-preview/media" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@logo.png"

Resposta (Enviar imagem da mini-loja)

201Imagem criada
json
{
  "id": "7d1d2f0e-3c3a-4f6b-9a50-1c2d3e4f5a6b",
  "tenant_id": "dfe2555e-bfd0-41a8-9fa1-9586999f3798",
  "owner_id": "appearance",
  "owner_type": "whatsapp_minishop",
  "filename": "logo.png",
  "content_type": "image/png",
  "size": 18342,
  "url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/whatsapp_minishop/7d1d2f0e_logo.png",
  "position": 0,
  "created_at": "2026-10-11T22:10:00Z"
}

Campos da resposta

idstring
UUID da mídia. Use em logo_media_id ou hero_media_id.
owner_typestring
Sempre whatsapp_minishop nesta rota.
owner_idstring
Sempre appearance nesta rota.
filenamestring
Nome do arquivo.
content_typestring
Tipo detectado pelo conteúdo.
sizeinteger
Tamanho em bytes.
urlstring
Caminho público da imagem.
created_atstring
Criação, RFC 3339.

Erros (Enviar imagem da mini-loja)

StatusQuandoCorpo
400Formulário inválido, arquivo ausente ou tipo não permitido (SVG, PDF e MP4 são recusados nesta rota).{"error":"unsupported file type","detail":"Mini-shop assets accept JPEG, PNG, GIF, WebP, or AVIF images only. Detected: image/svg+xml"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}

Enviar o link ao cliente

Monta um link personalizado e o entrega. Dentro das 24 horas depois da última mensagem do cliente (a janela de atendimento do WhatsApp) a plataforma usa um botão que abre a mini-loja (cta_url); se isso falhar, um texto com a prévia do link. Fora da janela só é permitido enviar um template aprovado pela Meta. Quando os Flows nativos da loja estão ligados, o envio vira um Flow (native_flow).

POST/api/v1/admin/whatsapp/web-preview/sendAdmin

Envia ao cliente o link da mini-loja, do carrinho ou do checkout

Corpo da requisição

phonestringobrigatório
Telefone do cliente com código do país.
vendor_idstring
UUID do seller cujo número e loja serão usados. Omitido, usa a loja.
purposestringpadrão: store
storecartcheckout
Para onde o link leva.
bodystring
Texto da mensagem. Aceita variáveis do catálogo de templates. Vazio usa uma saudação padrão.
cta_labelstringpadrão: Ver loja
Rótulo do botão (até 20 caracteres).
managed_template_idstring
Id de um template gerenciado a usar fora da janela. Seus padrões de texto e botão são aplicados quando o corpo está vazio.
template_namestring
Nome do template da Meta, se não usar o gerenciado.
template_paramsarray
Parâmetros do template, na ordem das variáveis.
force_templatebooleanpadrão: false
true pula o caminho interativo e sempre usa template.
prefer_text_previewbooleanpadrão: false
true envia texto com prévia do link em vez do botão.

Exemplo de requisição (Enviar o link ao cliente)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/web-preview/send" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+5511999998888",
    "purpose": "store",
    "body": "Oi! Toque para abrir a loja.",
    "cta_label": "Ver loja"
  }'

Resposta (Enviar o link ao cliente)

200Link enviado
json
{
  "result": {
    "mode": "cta_url",
    "url": "https://minhaloja.io.venddor.com.br/wa/eyJ0IjoiLi4u",
    "message_id": 2081,
    "window_open": true
  },
  "message": {
    "id": 2081,
    "phone_number": "5511999998888",
    "message_type": "interactive",
    "status": "sent"
  }
}

Campos da resposta

resultobject

O que foi feito.

modestring
cta_urltext_previewtemplatenative_flow
Como foi enviado.
urlstring
Link personalizado gerado. Ausente em native_flow.
message_idinteger
Id interno da mensagem registrada.
window_openboolean
true se a janela de 24 horas estava aberta.
warningstring
Aviso quando o botão falhou e a plataforma recorreu a outro caminho.
messageobject
A mensagem registrada, com status (veja Mensagens enviadas).

Erros (Enviar o link ao cliente)

StatusQuandoCorpo
400Corpo que não é JSON.{"error":"invalid json"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
502Falha no envio (telefone ausente, módulo desligado, Meta recusou, template inexistente). result pode vir junto.{"error":"whatsapp: phone required","result":null}
Isto envia uma mensagem de verdade

A rota entrega a mensagem ao telefone informado, e fora da janela de 24 horas consome um template pago. Teste primeiro com o seu próprio número.

Gerar amostra de links

Devolve os links da loja, do carrinho e do checkout, com os tokens e as variáveis de template que eles alimentam. Sem phone, os links são de um visitante anônimo (serve para ver a loja no editor); com phone, o token identifica esse telefone. Não envia nada.

GET/api/v1/admin/whatsapp/link-packAdmin

Gera links personalizados de amostra para pré-visualização

Parâmetros de consulta

vendor_idstring
UUID do seller. Omitido, usa a loja.
phonestring
Telefone do cliente. Omitido, gera link de visitante.
namestring
Nome do cliente para as variáveis do template.

Exemplo de requisição (Gerar amostra de links)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/link-pack?phone=%2B5511999998888&name=Maria" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Gerar amostra de links)

200Links
json
{
  "link_pack": {
    "store_link": "https://minhaloja.io.venddor.com.br/wa/eyJ0Ijoi...",
    "cart_link": "https://minhaloja.io.venddor.com.br/wa/eyJ0Ijoi.../cart",
    "checkout_link": "https://minhaloja.io.venddor.com.br/wa/eyJ0Ijoi.../checkout"
  },
  "vars": {
    "store_link": "https://minhaloja.io.venddor.com.br/wa/eyJ0Ijoi...",
    "vendor_name": "Loja Exemplo"
  },
  "var_catalog": [
    {
      "key": "store_link",
      "label_pt": "Link da loja (mini-shop)",
      "label_en": "Store mini-shop link",
      "example": "https://loja.../wa/{token}"
    }
  ]
}

Campos da resposta

link_packobject
Os links gerados e seus tokens (store_link, cart_link, checkout_link e os tokens correspondentes).
varsobject
As mesmas informações como variáveis de template, prontas para interpolar em textos.
var_catalogarray
Catálogo das variáveis disponíveis para textos e templates: cada item tem key, label_pt, label_en e example.

Erros (Gerar amostra de links)

StatusQuandoCorpo
400Não foi possível montar os links (por exemplo, seller inexistente).{"error":"..."}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
Os links expiram?

O token traz a data de emissão (iat) e identifica loja e cliente. Trate os links como credenciais de uma pessoa: não os publique.

Veja também

  • Atalhos de abertura
  • Templates gerenciados
Anterior
Atalhos de abertura da conversa
Próxima
WhatsApp: caixa de entrada
Nesta página
  • Ler a aparência
  • Exemplo de requisição (Ler a aparência)
  • Resposta (Ler a aparência)
  • Erros (Ler a aparência)
  • Salvar a aparência
  • Exemplo de requisição (Salvar a aparência)
  • Resposta (Salvar a aparência)
  • Erros (Salvar a aparência)
  • Enviar imagem da mini-loja
  • Exemplo de requisição (Enviar imagem da mini-loja)
  • Resposta (Enviar imagem da mini-loja)
  • Erros (Enviar imagem da mini-loja)
  • Enviar o link ao cliente
  • Exemplo de requisição (Enviar o link ao cliente)
  • Resposta (Enviar o link ao cliente)
  • Erros (Enviar o link ao cliente)
  • Gerar amostra de links
  • Exemplo de requisição (Gerar amostra de links)
  • Resposta (Gerar amostra de links)
  • Erros (Gerar amostra de links)
  • Veja também