API atual/Referência completa/WhatsApp Platform

Mini-shop no storefront

As duas rotas públicas que o site e o mini-shop de WhatsApp leem: a configuração do botão flutuante e os layouts das telas do WhatsApp.

Duas rotas públicas (sem token) alimentam a experiência de WhatsApp de uma loja: uma diz como mostrar o botão flutuante de conversa, a outra entrega o desenho das telas do mini-shop (as páginas de catálogo e pedido que abrem a partir da conversa). Ambas respondem pela loja resolvida pelo domínio da requisição (em testes, pelo cabeçalho X-Tenant-ID).

Configuração do botão flutuante

GET/api/v1/storefront/whatsapp/settingsPública

Configuração pública do botão de WhatsApp

Devolve só o que o site precisa para desenhar o botão: se está ligado, para qual telefone aponta, a mensagem de boas-vindas, o canto da tela, o modo de venda da loja e a lista de palavras de descadastro. Só responde se o módulo WhatsApp Commerce estiver ativo na loja. A chamada tem limite de 20 segundos e a carga interna 6 segundos: se estourar, a resposta é um padrão seguro (botão desligado, modo b2c) em vez de erro.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/whatsapp/settings"

Resposta

200Configuração lida

json

{
  "mode": "b2b",
  "floating_button_enabled": true,
  "floating_button_phone": "+5511999999999",
  "floating_button_position": "bottom-right"
}

Campos da resposta

modestring

b2bb2c

Modo de venda. É o que a loja configurou; se não configurou, vira b2b quando a loja usa algum dos módulos de venda para empresas (login por CNPJ, preços B2B ou subcontas corporativas) e b2c nos demais casos.

floating_button_enabledboolean

Se o botão deve aparecer. Sempre presente.

floating_button_phonestring

Telefone do botão. Ausente quando vazio.

floating_button_welcomestring

Mensagem inicial que o cliente envia ao tocar no botão. Ausente quando vazio.

floating_button_positionstring

Canto da tela (por exemplo bottom-right). Ausente quando não configurado.

stop_keywordsstring

Palavras que o cliente digita para parar de receber mensagens, separadas por vírgula. Ausente quando não configurado (a plataforma usa STOP, PARAR e CANCELAR).

Campos vazios não aparecem no JSON (apenas floating_button_enabled é sempre enviado), como no exemplo, que vem de uma loja de testes sem mensagem de boas-vindas.

Telas do mini-shop

GET/api/v1/storefront/wa-page-layoutsPública

Layouts de todas as telas do WhatsApp da loja

Devolve de uma vez o desenho de todas as telas do mini-shop da loja, em vez de uma requisição por tela. São as páginas do layout padrão do tema ativo cujo identificador (dispatch) começa com wa., como wa.home, wa.cart ou wa.checkout. Cada página é editada no construtor de layouts do painel.

Se um visitante está logado (token opcional), os blocos restritos a grupos de usuários são filtrados para ele. A resposta nunca é guardada em cache pelo navegador.

200Layouts devolvidos

json

{
  "layouts": {
    "wa.home": {
      "layout": null,
      "page": {
        "id": 412,
        "layout_id": 9,
        "dispatch": "wa.home",
        "name": "Início do WhatsApp",
        "is_default": true,
        "position": 0,
        "seo_title": "",
        "seo_description": "",
        "seo_keywords": "",
        "og_image": "",
        "og_type": "",
        "canonical_url": "",
        "no_index": false,
        "custom_html_code": "",
        "created_at": "2026-09-20T10:00:00Z"
      },
      "containers": [
        {
          "id": 1201,
          "page_id": 412,
          "position": "content",
          "sort_order": 0,
          "uses_default": false,
          "rows": [
            {
              "id": 2201,
              "sort_order": 0,
              "full_width": false,
              "spacing": "normal",
              "display_mode": "normal",
              "columns": [
                {
                  "id": 3301,
                  "width_desktop": 12,
                  "width_tablet": 12,
                  "width_mobile": 12,
                  "blocks": [
                    { "id": 4401, "block_type": "text", "name": "Boas-vindas", "status": "active", "config": {}, "content": { "text": "Olá! Como podemos ajudar?" } }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Uma loja sem nenhuma tela de WhatsApp devolve {"layouts": {}} (mapa vazio, não erro). O exemplo acima foi encurtado: o servidor devolve todos os campos de cada linha, coluna e bloco.

Campos da resposta

layoutsobject

Mapa em que a chave é o identificador da tela (dispatch, por exemplo wa.home) e o valor é a tela.

layouts.{dispatch}.pageobject

Dados da página: id, dispatch, name, is_default, campos de SEO e custom_html_code. Havendo mais de uma página para o mesmo dispatch, vale a padrão (is_default), depois a mais antiga.

layouts.{dispatch}.layoutnull

Sempre null nesta rota (diferente da rota de uma página só).

layouts.{dispatch}.containersarray

Zonas da página, cada uma com position (top_panel, header, content, footer), rows, columns e blocks. Larguras de coluna vão de 1 a 12 (width_desktop, width_tablet, width_mobile).

Erros

Status	Quando	Corpo de exemplo
403	`whatsapp/settings`: módulo WhatsApp Commerce desativado na loja	`{"error":"module_disabled","module":"whatsapp-commerce"}`
500	`wa-page-layouts`: falha ao ler os layouts	`{"error":"failed to get wa page layouts", ...}`
500	`whatsapp/settings`: falha ao verificar os módulos	`{"error":"internal_error","detail":"failed to check module status"}`
503	`whatsapp/settings`: a requisição passou de 20 segundos	`{"error":"request timeout","code":"handler_timeout"}`

Veja também

Mini-shop no storefront

As duas rotas públicas que o site e o mini-shop de WhatsApp leem: a configuração do botão flutuante e os layouts das telas do WhatsApp.

Configuração do botão flutuante

GET/api/v1/storefront/whatsapp/settingsPública

Configuração pública do botão de WhatsApp

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/whatsapp/settings"

Resposta

200Configuração lida

json

{
  "mode": "b2b",
  "floating_button_enabled": true,
  "floating_button_phone": "+5511999999999",
  "floating_button_position": "bottom-right"
}

Campos da resposta

modestring

b2bb2c

floating_button_enabledboolean

Se o botão deve aparecer. Sempre presente.

floating_button_phonestring

Telefone do botão. Ausente quando vazio.

floating_button_welcomestring

Mensagem inicial que o cliente envia ao tocar no botão. Ausente quando vazio.

floating_button_positionstring

Canto da tela (por exemplo bottom-right). Ausente quando não configurado.

stop_keywordsstring

Palavras que o cliente digita para parar de receber mensagens, separadas por vírgula. Ausente quando não configurado (a plataforma usa STOP, PARAR e CANCELAR).

Campos vazios não aparecem no JSON (apenas floating_button_enabled é sempre enviado), como no exemplo, que vem de uma loja de testes sem mensagem de boas-vindas.

Telas do mini-shop

GET/api/v1/storefront/wa-page-layoutsPública

Layouts de todas as telas do WhatsApp da loja

Se um visitante está logado (token opcional), os blocos restritos a grupos de usuários são filtrados para ele. A resposta nunca é guardada em cache pelo navegador.

200Layouts devolvidos

json

{
  "layouts": {
    "wa.home": {
      "layout": null,
      "page": {
        "id": 412,
        "layout_id": 9,
        "dispatch": "wa.home",
        "name": "Início do WhatsApp",
        "is_default": true,
        "position": 0,
        "seo_title": "",
        "seo_description": "",
        "seo_keywords": "",
        "og_image": "",
        "og_type": "",
        "canonical_url": "",
        "no_index": false,
        "custom_html_code": "",
        "created_at": "2026-09-20T10:00:00Z"
      },
      "containers": [
        {
          "id": 1201,
          "page_id": 412,
          "position": "content",
          "sort_order": 0,
          "uses_default": false,
          "rows": [
            {
              "id": 2201,
              "sort_order": 0,
              "full_width": false,
              "spacing": "normal",
              "display_mode": "normal",
              "columns": [
                {
                  "id": 3301,
                  "width_desktop": 12,
                  "width_tablet": 12,
                  "width_mobile": 12,
                  "blocks": [
                    { "id": 4401, "block_type": "text", "name": "Boas-vindas", "status": "active", "config": {}, "content": { "text": "Olá! Como podemos ajudar?" } }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Uma loja sem nenhuma tela de WhatsApp devolve {"layouts": {}} (mapa vazio, não erro). O exemplo acima foi encurtado: o servidor devolve todos os campos de cada linha, coluna e bloco.

Campos da resposta

layoutsobject

Mapa em que a chave é o identificador da tela (dispatch, por exemplo wa.home) e o valor é a tela.

layouts.{dispatch}.pageobject

Dados da página: id, dispatch, name, is_default, campos de SEO e custom_html_code. Havendo mais de uma página para o mesmo dispatch, vale a padrão (is_default), depois a mais antiga.

layouts.{dispatch}.layoutnull

Sempre null nesta rota (diferente da rota de uma página só).

layouts.{dispatch}.containersarray

Erros

Status	Quando	Corpo de exemplo
403	`whatsapp/settings`: módulo WhatsApp Commerce desativado na loja	`{"error":"module_disabled","module":"whatsapp-commerce"}`
500	`wa-page-layouts`: falha ao ler os layouts	`{"error":"failed to get wa page layouts", ...}`
500	`whatsapp/settings`: falha ao verificar os módulos	`{"error":"internal_error","detail":"failed to check module status"}`
503	`whatsapp/settings`: a requisição passou de 20 segundos	`{"error":"request timeout","code":"handler_timeout"}`