API atual/Referência completa/Mini-loja WhatsApp: sessão

Aparência e utilidades

Lê a aparência, o horário, a política de checkout e as funcionalidades da loja, converte endereços em coordenadas e pede a credencial de uma chamada de voz.

Estas três rotas alimentam a interface: a primeira diz como a loja se apresenta e quais regras valem (cores, horário, quando exige conta, o que está ligado), a segunda ajuda a localizar um endereço e a terceira prepara uma chamada de voz com o assistente da loja.

Ler a aparência e as regras da loja

GET/api/v1/storefront/wa-coex/appearance/{token}Pública

Aparência, horário, política de checkout e funcionalidades ligadas

A resposta mistura identidade visual e regras de negócio, e é o ponto de partida para decidir o que mostrar. O mapa store_caps (de capabilities, funcionalidades) diz quais recursos opcionais a loja ligou, e checkout_policy diz o que o cliente pode fazer sem conta. Tem cache público de 60 segundos; a resposta com cores incompletas (tema ainda não lido) não é guardada em cache.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Parâmetros de consulta

partstring

min_order

Com min_order, devolve só o pedido mínimo da loja para o destino do cliente (veja abaixo), sem o documento de aparência.

zipstring

Só com part=min_order. CEP de entrega com 8 dígitos. Sem ele, a plataforma usa o destino do cliente (rascunho do chat ou primeiro endereço salvo) e, se não houver, o mínimo geral da loja.

Cabeçalhos

X-Wa-Dest-Cepstring

Opcional, vale para qualquer rota com token. CEP de 8 dígitos que o checkout cotou por último para esta sacola. Serve de destino da sacola quando a conta não tem endereço salvo e só muda o pedido mínimo mostrado, nunca preços nem frete. Outros valores são ignorados.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wa-coex/appearance/$TOKEN"

Resposta

200Aparência da loja (resumida)

json

{
  "store_name": "Loja de Demonstração Venddor",
  "whatsapp_phone": "5511999998888",
  "store_address": "Rua dos Testes, 100, Volta Redonda/RJ (CEP 27253-650)",
  "show_store_address": true,
  "accent_color": "#2563eb",
  "header_color": "#2563eb",
  "logo_media_id": "/uploads/dfe2555e/theme/logo/logo-v1.png",
  "hero_title": "",
  "card_style": "C",
  "is_open": true,
  "closed_message": "",
  "allow_orders_closed": false,
  "business_hours": { "is_24_hours": false, "is_open": true, "timezone": "America/Sao_Paulo", "days": [], "message": "", "summary": "" },
  "min_order_cents": 0,
  "free_ship_cents": 10000,
  "assistant_checkout": false,
  "checkout_policy": {
    "allow_guest_checkout": true,
    "allow_guest_cart": true,
    "allow_guest_view_price": true,
    "allow_shopping_unlogged": true,
    "allow_multiple_addresses": true,
    "allow_seller_chat": true,
    "offer_account_after_order": true,
    "terms_required": false,
    "min_order_amount": 0,
    "min_qty_per_product": 1,
    "max_qty_per_product": 0
  },
  "login_capabilities": { "allow_auto_phone_login": true, "allow_cnpj_login": true, "allow_cpf_login": true, "allow_email_login": true },
  "registration_required_fields": [
    { "field_name": "cpf", "label": "CPF", "is_canonical": true, "scope": "pf" },
    { "field_name": "email", "label": "E-mail", "is_canonical": true, "scope": "all" }
  ],
  "store_caps": { "wa.pdp.reviews": false, "wa.pdp.shipping_calc": false, "wa.bag.wallet": true, "wa.checkout.sales_rep": false },
  "delivery_forecast": null
}

Campos da resposta

store_namestring

Nome de exibição da loja.

whatsapp_phonestring

Número de WhatsApp da loja, só dígitos (5511999998888), para montar links https://wa.me/<número>.

store_addressstring

Endereço da loja em uma linha. Mostre só se show_store_address for true.

appearanceobject

Documento de aparência completo (logo_media_id, header_color, accent_color, hero_media_id, hero_title, hero_subtitle, greeting_template, card_style, updated_at).

logo_media_idstring

Caminho do logotipo. Os campos header_color, accent_color, hero_media_id, hero_title, hero_subtitle, greeting_template, card_style (pinned_collections, footer_info) repetem o documento appearance na raiz, por compatibilidade com clientes antigos.

commerce_profileobject

Perfil comercial da loja: segment (por exemplo general, B2B), config, labels, capabilities.

copyobject

Mapa de textos da loja (chave para texto já resolvido pelo segmento). Trate como opaco e use só as chaves que a sua interface conhece.

is_openboolean

A loja está aberta agora, pelo horário de funcionamento.

closed_messagestring

Recado da loja enquanto fechada.

allow_orders_closedboolean

A loja aceita pedido mesmo fechada. Nesse caso is_open já vem true.

business_hoursobject

Horário de funcionamento: is_24_hours, is_open, timezone, days, message, summary. null quando a loja não configurou horário.

min_order_centsinteger

Pedido mínimo geral da loja, em centavos. Sacolas com destino que tem mínimo próprio veem outro valor em cart.min_order_cents.

free_ship_centsinteger

Valor da sacola a partir do qual o frete é grátis, em centavos. 0 quando não há.

assistant_checkoutboolean

O assistente fecha o pedido dentro do chat.

checkout_policyobject

Regras do checkout da loja. Os principais campos: allow_shopping_unlogged (visitante pode navegar), allow_guest_cart, allow_guest_view_price, allow_guest_checkout (visitante pode comprar), allow_multiple_addresses, offer_account_after_order, terms_required (aceite de termos obrigatório), min_qty_per_product, max_qty_per_product (0 = sem limite) e min_order_amount.

login_capabilitiesobject

Formas de entrar aceitas: allow_auto_phone_login, allow_cnpj_login, allow_cpf_login, allow_email_login.

registration_required_fieldsarray

Campos de cadastro obrigatórios, cada um com field_name, label, is_canonical (true para nome, e-mail, documento e telefone) e scope (all, pf ou pj). Campos não canônicos vão em extra_fields de Cadastro. null quando nenhum é exigido.

store_capsobject

Mapa funcionalidade para booleano. As chaves usam o prefixo wa.: por exemplo wa.pdp.reviews (avaliações), wa.pdp.shipping_calc (cálculo de frete na ficha), wa.pdp.buy_together (compre junto), wa.bag.wallet (cashback), wa.checkout.sales_rep (escolha de consultor), wa.checkout.pix_manual (Pix com comprovante), wa.catalog.show_out_of_stock. Ligue ou desligue cada recurso da sua interface por este mapa.

delivery_forecastobject

Previsão de entrega por seller, quando a loja a mostra. null quando desligada.

Pedido mínimo do destino

Com ?part=min_order a resposta é só:

200Pedido mínimo

json

{ "min_order_cents": 90000, "zip": "80010000", "source": "destination" }

Campos da resposta

min_order_centsinteger

Mínimo em centavos.

zipstring

CEP usado, 8 dígitos. Ausente quando não havia destino.

sourcestring

destinationstore

destination: a área de entrega do CEP define um mínimo próprio. store: vale o mínimo geral do checkout da loja.

Esta variante nunca é guardada em cache (private, no-store), porque depende da sacola.

Erros

Status	Quando	Corpo
500	Falha ao ler as configurações de aparência.	`{"error":"..."}`

Converter endereço em coordenadas

GET/api/v1/storefront/wa-coex/geocode/{token}Pública

CEP ou texto em latitude e longitude, ou o contrário

Dois usos, escolhidos pelos parâmetros. Com q, devolve a coordenada do endereço (um CEP de 8 dígitos é completado com a UF). Com lat e lng, faz o caminho inverso e devolve o endereço mais próximo. As respostas ficam em cache por 24 horas.

Esta é a única rota da mini-loja com limite próprio: 60 requisições por minuto por IP.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Parâmetros de consulta

qstring

Endereço ou CEP. Até 300 caracteres; espaços repetidos são colapsados.

latnumber

Latitude, para a busca inversa. Precisa vir junto com lng.

lngnumber

Longitude, para a busca inversa.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wa-coex/geocode/$TOKEN?q=01310100"

Resposta

200Coordenada (com q)

json

{ "lat": -23.5628302, "lng": -46.6546177 }

200Endereço (com lat e lng)

json

{ "street": "Rua Rocha", "number": "464", "district": "Morro dos Ingleses", "city": "São Paulo", "uf": "SP", "cep": "01330000" }

Campos da resposta

latnumber

Latitude.

lngnumber

Longitude.

streetstring

Logradouro (busca inversa).

numberstring

Número (busca inversa). Pode vir vazio.

districtstring

Bairro.

citystring

Cidade.

ufstring

UF. Atenção: nesta rota a chave é uf, e nos endereços de entrega é state.

cepstring

CEP só com dígitos. Atenção: aqui a chave é cep, e nos endereços é zip.

Erros

Status	Quando	Corpo
204	`q` vazio ou acima de 300 caracteres, ou nenhum resultado. Não tem corpo.	(vazio)
400	`lat` ou `lng` não é número. Sem corpo.	(vazio)
429	Passou de 60 por minuto.	Corpo padrão de limite.

Pedir a credencial de uma chamada de voz

POST/api/v1/storefront/wa-coex/realtime/{token}Pública

Credencial temporária para uma chamada de voz com o assistente

Gera uma credencial de curta duração para o navegador abrir uma conversa por voz com o assistente da loja. Sem corpo. Só funciona com a loja aberta, e cada token pode pedir uma credencial a cada 8 segundos. Use a credencial no mesmo instante: ela expira em poucos minutos.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

200Credencial emitida

json

{ "value": "ek_xxxxxxxxxxxxxxxx", "expires_at": 1791755809, "model": "voice-model-id" }

Campos da resposta

valuestring

Credencial temporária. Trate como segredo e não a guarde.

expires_atinteger

Quando expira, em Unix timestamp (segundos).

modelstring

Identificador do modelo de voz a usar com a credencial.

Erros

Status	Quando	Corpo
409	A loja está fechada.	`{"error":"store_closed","message":"Estamos fechados agora"}` (com o horário de reabertura, quando conhecido)
429	Segunda chamada em menos de 8 segundos.	`{"error":"rate_limited"}`
500	Falha ao montar o pedido da credencial.	`{"error":"token_request_failed"}`
502	O serviço de voz não respondeu ou recusou.	`{"error":"openai_unreachable"}` ou `{"error":"token_mint_failed"}`
503	A loja não tem chamada de voz configurada.	`{"error":"voice_call_unavailable"}`

Veja também

API atual/Referência completa/Mini-loja WhatsApp: sessão

Aparência e utilidades

Lê a aparência, o horário, a política de checkout e as funcionalidades da loja, converte endereços em coordenadas e pede a credencial de uma chamada de voz.

Ler a aparência e as regras da loja

GET/api/v1/storefront/wa-coex/appearance/{token}Pública

Aparência, horário, política de checkout e funcionalidades ligadas

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Parâmetros de consulta

partstring

min_order

Com min_order, devolve só o pedido mínimo da loja para o destino do cliente (veja abaixo), sem o documento de aparência.

zipstring

Só com part=min_order. CEP de entrega com 8 dígitos. Sem ele, a plataforma usa o destino do cliente (rascunho do chat ou primeiro endereço salvo) e, se não houver, o mínimo geral da loja.

Cabeçalhos

X-Wa-Dest-Cepstring

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wa-coex/appearance/$TOKEN"

Resposta

200Aparência da loja (resumida)

json

{
  "store_name": "Loja de Demonstração Venddor",
  "whatsapp_phone": "5511999998888",
  "store_address": "Rua dos Testes, 100, Volta Redonda/RJ (CEP 27253-650)",
  "show_store_address": true,
  "accent_color": "#2563eb",
  "header_color": "#2563eb",
  "logo_media_id": "/uploads/dfe2555e/theme/logo/logo-v1.png",
  "hero_title": "",
  "card_style": "C",
  "is_open": true,
  "closed_message": "",
  "allow_orders_closed": false,
  "business_hours": { "is_24_hours": false, "is_open": true, "timezone": "America/Sao_Paulo", "days": [], "message": "", "summary": "" },
  "min_order_cents": 0,
  "free_ship_cents": 10000,
  "assistant_checkout": false,
  "checkout_policy": {
    "allow_guest_checkout": true,
    "allow_guest_cart": true,
    "allow_guest_view_price": true,
    "allow_shopping_unlogged": true,
    "allow_multiple_addresses": true,
    "allow_seller_chat": true,
    "offer_account_after_order": true,
    "terms_required": false,
    "min_order_amount": 0,
    "min_qty_per_product": 1,
    "max_qty_per_product": 0
  },
  "login_capabilities": { "allow_auto_phone_login": true, "allow_cnpj_login": true, "allow_cpf_login": true, "allow_email_login": true },
  "registration_required_fields": [
    { "field_name": "cpf", "label": "CPF", "is_canonical": true, "scope": "pf" },
    { "field_name": "email", "label": "E-mail", "is_canonical": true, "scope": "all" }
  ],
  "store_caps": { "wa.pdp.reviews": false, "wa.pdp.shipping_calc": false, "wa.bag.wallet": true, "wa.checkout.sales_rep": false },
  "delivery_forecast": null
}

Campos da resposta

store_namestring

Nome de exibição da loja.

whatsapp_phonestring

Número de WhatsApp da loja, só dígitos (5511999998888), para montar links https://wa.me/<número>.

store_addressstring

Endereço da loja em uma linha. Mostre só se show_store_address for true.

appearanceobject

Documento de aparência completo (logo_media_id, header_color, accent_color, hero_media_id, hero_title, hero_subtitle, greeting_template, card_style, updated_at).

logo_media_idstring

commerce_profileobject

Perfil comercial da loja: segment (por exemplo general, B2B), config, labels, capabilities.

copyobject

Mapa de textos da loja (chave para texto já resolvido pelo segmento). Trate como opaco e use só as chaves que a sua interface conhece.

is_openboolean

A loja está aberta agora, pelo horário de funcionamento.

closed_messagestring

Recado da loja enquanto fechada.

allow_orders_closedboolean

A loja aceita pedido mesmo fechada. Nesse caso is_open já vem true.

business_hoursobject

Horário de funcionamento: is_24_hours, is_open, timezone, days, message, summary. null quando a loja não configurou horário.

min_order_centsinteger

Pedido mínimo geral da loja, em centavos. Sacolas com destino que tem mínimo próprio veem outro valor em cart.min_order_cents.

free_ship_centsinteger

Valor da sacola a partir do qual o frete é grátis, em centavos. 0 quando não há.

assistant_checkoutboolean

O assistente fecha o pedido dentro do chat.

checkout_policyobject

login_capabilitiesobject

Formas de entrar aceitas: allow_auto_phone_login, allow_cnpj_login, allow_cpf_login, allow_email_login.

registration_required_fieldsarray

store_capsobject

delivery_forecastobject

Previsão de entrega por seller, quando a loja a mostra. null quando desligada.

Pedido mínimo do destino

Com ?part=min_order a resposta é só:

200Pedido mínimo

json

{ "min_order_cents": 90000, "zip": "80010000", "source": "destination" }

Campos da resposta

min_order_centsinteger

Mínimo em centavos.

zipstring

CEP usado, 8 dígitos. Ausente quando não havia destino.

sourcestring

destinationstore

destination: a área de entrega do CEP define um mínimo próprio. store: vale o mínimo geral do checkout da loja.

Esta variante nunca é guardada em cache (private, no-store), porque depende da sacola.

Erros

Status	Quando	Corpo
500	Falha ao ler as configurações de aparência.	`{"error":"..."}`

Converter endereço em coordenadas

GET/api/v1/storefront/wa-coex/geocode/{token}Pública

CEP ou texto em latitude e longitude, ou o contrário

Esta é a única rota da mini-loja com limite próprio: 60 requisições por minuto por IP.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Parâmetros de consulta

qstring

Endereço ou CEP. Até 300 caracteres; espaços repetidos são colapsados.

latnumber

Latitude, para a busca inversa. Precisa vir junto com lng.

lngnumber

Longitude, para a busca inversa.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wa-coex/geocode/$TOKEN?q=01310100"

Resposta

200Coordenada (com q)

json

{ "lat": -23.5628302, "lng": -46.6546177 }

200Endereço (com lat e lng)

json

{ "street": "Rua Rocha", "number": "464", "district": "Morro dos Ingleses", "city": "São Paulo", "uf": "SP", "cep": "01330000" }

Campos da resposta

latnumber

Latitude.

lngnumber

Longitude.

streetstring

Logradouro (busca inversa).

numberstring

Número (busca inversa). Pode vir vazio.

districtstring

Bairro.

citystring

Cidade.

ufstring

UF. Atenção: nesta rota a chave é uf, e nos endereços de entrega é state.

cepstring

CEP só com dígitos. Atenção: aqui a chave é cep, e nos endereços é zip.

Erros

Status	Quando	Corpo
204	`q` vazio ou acima de 300 caracteres, ou nenhum resultado. Não tem corpo.	(vazio)
400	`lat` ou `lng` não é número. Sem corpo.	(vazio)
429	Passou de 60 por minuto.	Corpo padrão de limite.

Pedir a credencial de uma chamada de voz

POST/api/v1/storefront/wa-coex/realtime/{token}Pública

Credencial temporária para uma chamada de voz com o assistente

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

200Credencial emitida

json

{ "value": "ek_xxxxxxxxxxxxxxxx", "expires_at": 1791755809, "model": "voice-model-id" }

Campos da resposta

valuestring

Credencial temporária. Trate como segredo e não a guarde.

expires_atinteger

Quando expira, em Unix timestamp (segundos).

modelstring

Identificador do modelo de voz a usar com a credencial.

Erros

Status	Quando	Corpo
409	A loja está fechada.	`{"error":"store_closed","message":"Estamos fechados agora"}` (com o horário de reabertura, quando conhecido)
429	Segunda chamada em menos de 8 segundos.	`{"error":"rate_limited"}`
500	Falha ao montar o pedido da credencial.	`{"error":"token_request_failed"}`
502	O serviço de voz não respondeu ou recusou.	`{"error":"openai_unreachable"}` ou `{"error":"token_mint_failed"}`
503	A loja não tem chamada de voz configurada.	`{"error":"voice_call_unavailable"}`