Documentação de Integração

Manual para desenvolvedores integrarem o BELIA em lojas e-commerce.

1. Inclusão do script

Inclua o script do BELIA em todas as páginas da loja onde você quiser rastrear busca, vitrines, visualização de produto, carrinho e compra. A base da API é a mesma origem da loja (host + porta).

<script src="https://www.agliardi.xyz/belia/belia.js" data-belia-key="SUA_PUBLIC_KEY" data-belia-env="prod"></script>

Alternativa: use meta tags no <head> em vez de data-attributes no script:

<meta name="belia-site-key" content="SUA_PUBLIC_KEY" />
<meta name="belia-env" content="prod" />
<meta name="belia-api-base" content="https://sua-origem.com" />  <!-- opcional, padrão: window.location.origin -->

2. Objeto `window.Belia`

Após o carregamento, o script expõe:

Belia.base — base da API
Belia.key — site key
Belia.visitor_id / Belia.session_id — identificadores do visitante
Belia.setLastTerm(term) — define o termo de busca atual (para atribuição de compra ao termo)
Belia.boot() — reescaneia a página (útil após injetar HTML dinâmico, ex.: modal de produto)

3. Eventos e onde integrar

Evento	Onde usar	Como
Vitrines (impressão)	Blocos de produtos (ex.: “Mais vistos”, “Compre junto”)	O script detecta automaticamente itens com `data-belia-showcase` + `data-belia-product` (ou `data-showcase-block` + `data-showcase-item`) e envia impressão quando o item entra em vista (~60% visível).
Clique em vitrine	Mesmo bloco de vitrine	Clique em um produto do bloco. Não dispara se o clique for em botão de carrinho/compra.
Visualização de produto	Página ou modal do produto	Adicione `data-belia-product-page` e `data-belia-product="ID_EXTERNO"` no container da página/modal do produto. O script chama `trackProductView` ao carregar (com TTL 5 min por produto/sessão).
Adicionar ao carrinho	Botão “Adicionar ao carrinho”	No botão: `data-belia-add-to-cart` e `data-belia-product="ID_EXTERNO"`. Opcional: `data-belia-qty="1"`.
Compra	Botão “Finalizar compra” / “Registrar compra”	No botão: `data-belia-purchase`, `data-belia-product="ID_EXTERNO"`, `data-belia-value-cents="9999"`. Opcional: `data-belia-qty="1"`. O script envia o evento de compra e, se houver termo de busca em contexto (`setLastTerm`), atribui a compra ao termo.

4. Atribuição de compra ao termo de busca

Para que cliques em “Comprar” sejam atribuídos ao termo que o usuário buscou, o script usa um termo “último” em localStorage. Se sua busca ou abertura de produto for feita por JavaScript (ex.: SPA ou Livewire), dispare um evento para atualizar esse termo:

window.dispatchEvent(new CustomEvent('belia-set-last-term', { detail: { term: 'macacao' } }));

Ou chame diretamente: window.Belia.setLastTerm('macacao'). Faça isso ao exibir resultados de busca ou ao abrir a ficha do produto a partir da busca.

5. Resumo dos data-attributes

Vitrine: no bloco: data-belia-showcase="slug-da-vitrine", data-belia-page="home" (ou página atual). No item: data-belia-product="ID_EXTERNO", data-belia-position="1".
Página de produto: no container: data-belia-product-page + data-belia-product="ID_EXTERNO".
Carrinho: data-belia-add-to-cart + data-belia-product="ID_EXTERNO" (+ data-belia-qty opcional).
Compra: data-belia-purchase + data-belia-product="ID_EXTERNO" + data-belia-value-cents (+ data-belia-qty opcional).

Teste todos os endpoints da API pelo Swagger. Informe a Public Key e o ambiente uma vez e execute as requisições.

Abrir Swagger

Autenticação

Todas as requisições à API devem enviar o header:

X-BELIA-SITE-KEY: SUA_PUBLIC_KEY

Para ambiente de teste, use o parâmetro environment=test (query string ou body). O padrão é prod.

Endpoints usados na integração

Estes endpoints são chamados pelo belia.js ou podem ser usados diretamente pelo e-commerce (ex.: para buscar resultados de busca ou listar vitrines).

Método / Rota	Uso na integração
`GET /api/v1/pages/{type}`	Componentes da página (home, category, etc.). Usado se a loja montar a página a partir da API.
`GET /api/v1/showcases`	Lista de vitrines ativas. Use para montar o menu ou blocos (ex.: “Mais vistos”, “Mais comprados”).
`GET /api/v1/showcases/{slug}`	Dados de uma vitrine por slug (nome, estratégia, janela, limite).
`GET /api/v1/showcases/{slug}/products`	Produtos da vitrine (com scores e dados para exibição). Query: `environment=test\|prod`.
`GET /api/v1/products/{externalId}`	Detalhes de um produto por ID externo (sku). Use na página ou modal do produto.
`GET /api/v1/search`	Busca com redirecionamentos, sinônimos e correção. Query: `q`, `page`, `limit`, `environment`.
`GET /api/v1/search/autocomplete`	Autocomplete e sugestões. Query: `q` (vazio = top termos), `limit`.
`GET /api/v1/search/metrics`	Métricas do dia (buscas, CTR, conversões). Query: `environment=test\|prod`.
`GET /api/v1/catalog/products`	Listagem do catálogo com filtros (marca, categoria, preço, ordenação) e facetas.
`POST /api/v1/events/showcase-impression`	Enviado pelo belia.js quando um item de vitrine entra em vista. Body: `showcase_slug`, `page`, `items` (array de `{ product_external_id, position }`), `session_id`, `visitor_id`, `environment`.
`POST /api/v1/events/showcase-click`	Enviado pelo belia.js no clique em produto de vitrine. Body: `showcase_slug`, `product_external_id`, `position`, `page`, `session_id`, `visitor_id`, `environment`.
`POST /api/v1/events/product-view`	Visualização de produto. Body: `product_external_id`, `qty` (opcional), `term` (opcional, para atribuição), `session_id`, `visitor_id`, `environment`.
`POST /api/v1/events/add-to-cart`	Adicionar ao carrinho. Body: `product_external_id`, `qty`, `term` (opcional), `session_id`, `visitor_id`, `environment`.
`POST /api/v1/events/purchase`	Compra. Body: `product_external_id`, `qty`, `value_cents`, `term` (opcional), `session_id`, `visitor_id`, `environment`.
`POST /api/v1/search/click`	Clique em um termo/sugestão da busca. Body: `term`, `product_external_id` (opcional). Chamado pela loja ao registrar clique em resultado/autocomplete.
`POST /api/v1/search/purchase`	Atribuição de compra ao termo (alimenta métricas de conversão por termo). O belia.js chama após `POST /api/v1/events/purchase` quando há termo em contexto. Body: `term`, `revenue_cents`, `product_external_id`, `qty`, `session_id`, `visitor_id`.

Base URL

A base da API deve ser a mesma origem do site onde o script está instalado (ex.: https://minhaloja.com), ou a URL do backend que expõe a API Belia. O script usa window.location.origin por padrão; para override, use meta name="belia-api-base" ou window.Belia.apiBase antes do script carregar.