Integrar a bilheteira de forma nativa

Início rápido

Há dois caminhos para uma loja em funcionamento. Ambos usam o mesmo script e o mesmo elemento; a diferença está em quem cria a sessão.

Sem back-end

O elemento cria a sua própria sessão de navegador para a sua publicKey, limitada aos domínios autorizados. Defina cart-scope="tab": sem identidade de servidor, a predefinição "shared" termina num erro explícito. Cada separador tem então o seu próprio carrinho. A sessão é anónima: os visitantes navegam e enchem o carrinho. Antes do registo, element.config.onUserRequired tem de devolver um token de sessão associado a um utilizador, emitido por um servidor; sem ele a loja para no carrinho com um aviso.

<!-- Site without a backend: load the script once, place the element. -->
<script src="https://developers.aditus.com/api/embed/v1/aditus-shop.js" defer></script>

<aditus-shop
  public-key="pk_your_site"
  cart-scope="tab"
></aditus-shop>

Com back-end

O seu servidor cria a sessão com o mint secret e decide quem é o comprador. Transmita o token devolvido ao elemento. Com o email do comprador, a predefinição cart-scope "shared" mantém um único carrinho em todos os separadores.

// 1. On your server: create a session. The mint secret never leaves the server.
const res = await fetch("https://developers.aditus.com/api/shop/session", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ADITUS_MINT_SECRET}`,
    "Content-Type": "application/json",
  },
  // email comes from your own login session, never from the browser request.
  body: JSON.stringify({ publicKey: "pk_your_site", email: user.email }),
});
const { sessionToken } = await res.json();

<!-- 2. In your page: pass the token from your server to the element. -->
<script src="https://developers.aditus.com/api/embed/v1/aditus-shop.js" defer></script>

<aditus-shop
  public-key="pk_your_site"
  session-token="SESSION_TOKEN_FROM_YOUR_SERVER"
></aditus-shop>

Substitua pk_your_site pela sua chave publicável do admin ADITUS. developers.aditus.com é o endereço de produção do script e da API. Ambos os caminhos são descritos em detalhe mais abaixo.

A tecnologia por trás do micro-frontend

O micro-frontend apresenta todo o processo de compra (eventos, artigos, carrinho, registo, pagamento, conclusão) no DOM da sua página. Usa o layout da página e o seu CSS pode estilizar cada parte.

O seu site é de confiança: o seu servidor autentica o utilizador antes de criar uma sessão identificada. O micro-frontend é apresentado deliberadamente no Light DOM da sua página, sem isolamento iframe. Os scripts da sua página podem aceder ao DOM e ao armazenamento do navegador; por isso, proteja o seu site e os scripts de terceiros. A autorização de origem por chave pública não é uma autenticação do utilizador. Os dados de pagamento só são introduzidos na página externa do prestador de pagamentos.

Segurança dos pagamentos, PCI e CSP

A preparação da compra é apresentada na sua página. O pagamento acontece na página do prestador de pagamentos, pelo que nenhum dado de pagamento passa pela sua página.

Comparação com iframe e shadow DOM

As abordagens comparadas

Alternativa: pacote de código-fonte (distribuição própria)

Em alternativa, descarregue o pacote de código-fonte da sua instância ADITUS e integre-o na sua aplicação (Vite, webpack, Next.js ou Nuxt). A distribuição fica a seu cargo: cada atualização exige reinstalação, build e publicação. Não está no npm público.

Aplicações SSR: Next.js e Nuxt

O micro-frontend é deliberadamente apenas para o cliente. O o respetivo conteúdo é ativo e vinculado à sessão: a disponibilidade, os preços e o carrinho do utilizador existem apenas para uma sessão autenticada no momento da pedido, portanto, não há nada significativo que o seu servidor possa pré-apresentar. mount() cria uma nova raiz React do lado do cliente (createRoot); a marcação apresentada pelo servidor dentro do contêiner não é hidratada. Isso torna a integração SSR simples e previsível: apresente um placeholder no servidor, faça o mount no cliente e reserve o espaço para que nada salte.

// Next.js (App Router): the micro-frontend is deliberately client-only.
"use client";
import { useEffect, useRef } from "react";
import { mount, type ShopHandle } from "@aditus/shop-embed";

export function TicketshopSection({ sessionToken }: { sessionToken: string }) {
  const el = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!el.current) return;
    const handle: ShopHandle = mount(el.current, {
      publicKey: "pk_your_site",
      sessionToken, // issued server-side, passed to the client component as a prop
      cartScope: "shared", // the default in frameworks too; trusted server identity
    });
    return () => handle(); // unmount on route change
  }, [sessionToken]);

  // Server and client render the SAME placeholder and so avoid a hydration mismatch.
  // min-height reserves the space so the page does not jump on mount (CLS).
  return <div id="aditus-shop" ref={el} style={{ minHeight: 560 }} />;
}

O micro-frontend precisa de uma sessão

import { mount } from "@aditus/shop-embed";

const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount target #aditus-shop not found");

// Without a sessionToken the micro-frontend stays inactive: it only shows a
// neutral notice and starts no API calls: no cart, no registration,
// no checkout. Only a session activates the shop.
mount(el, {
  publicKey: "pk_your_site",
  // sessionToken missing -> the shop is not activated.
});

import {
  mount,
  type ShopHandle,
  type AditusShopConfig,
} from "@aditus/shop-embed";

// getElementById can return null. Check it properly in TypeScript instead of using "!".
const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount target #aditus-shop not found");

// AditusShopConfig types every option and gives you autocompletion.
const config: AditusShopConfig = {
  apiBase: "https://developers.aditus.com/api/shop",
  publicKey: "pk_your_site",   // required as soon as a session is involved
  sessionToken,                // issued by your backend, keep it in memory only
  cartScope: "shared",          // default; requires a trusted server identity
};

const handle: ShopHandle = mount(el, config);

// The micro-frontend sends the X-Aditus-Session header with every shop call.
// On logout, revoke the session on the server and remount/update.

Ao recarregar, um apontador válido permite pedir o carrinho do servidor sob o mesmo âmbito autorizado e identidade de confiança. Não autoriza nem garante recuperação após expiração, eliminação do armazenamento ou mudança de utilizador. tab não junta percursos de outros separadores; shared mantém o bloqueio de checkout com um só escritor.

O regresso do pagamento usa aditus-return (um token opaco, curto e vinculado ao servidor) com aditus-pay. Pode regressar no mesmo separador ou num novo, mas o servidor exige cliente/origem autorizado e identidade de confiança correspondente. Os parâmetros de regresso não provam uma compra. O servidor verifica o pagamento e finaliza a tentativa vinculada ao token; um resultado desconhecido permanece bloqueado para esclarecimento, sem repetir cegamente uma nova compra. Regressos expirados ou não autorizados são erros explícitos, não permissão para criar uma encomenda de substituição.

A atribuição de um fornecedor apenas prepara o pagamento: o resumo continua editável. O bloqueio começa no redirecionamento efetivo, após os consentimentos exigidos. Um parâmetro de regresso cancel/error não prova falha: o backend verifica novamente o carrinho; Completed com order.id confirma a conclusão. Só a remoção bem-sucedida e confirmada da atribuição para esse mesmo carrinho permite repetir; resultados ambíguos ficam bloqueados e podem ser verificados novamente. Isto não garante reembolso nem exclui liquidação tardia.

Pagamento por redirecionamento: o que a sua página tem de fazer com a sessão

• Sirva o URL de regresso configurado com o embed montado. Preserve aditus-return e aditus-pay no encaminhamento ou redirecionamentos de login necessários; aditus-pay=success nunca é autorização. Forneça uma sessão válida para a mesma identidade de confiança e publicKey. Mantenha cartScope e não apague o percurso nem inicie outro checkout para contornar um regresso pendente, expirado ou incerto.

Se pretender começar deliberadamente de novo, com um verdadeiro botão «recomeçar», o pacote exporta clearJourney(). Chame esta função antes do mount (ou de um novo mount) para eliminar o registo do percurso guardado localmente para a página atual; o mount seguinte começará de novo no ponto de entrada, em vez de retomar. Apenas é removido o ponteiro de retoma local; o estado do carrinho no servidor não é alterado.

Ponto de entrada: início do evento, artigos ou voucher

O servidor decide o início ao criar a sessão, nunca o navegador. Sem eventSlug aparece a lista de eventos. Com eventSlug, startMode escolhe artigos (predefinição), início ou formulário de voucher; assortment limita os artigos.

A seleção de artigos e a continuação após um voucher seguem o percurso da loja original baseado em recomendações. Sem oferta upsell utilizável nem venda cruzada, avança-se diretamente para a personalização dos bilhetes através das verificações normais de login/sessão; com venda cruzada, mostra-se o carrinho. Uma oferta upsell utilizável abre primeiro o diálogo. Ignorar leva à personalização sem venda cruzada, ou ao carrinho quando existe. Um upgrade confirmado leva ao carrinho; fechar o diálogo mantém a seleção. O percurso nunca grava o registo em segundo plano.

Os sortidos visíveis podem ter acesso direto. Se um sortido estiver fixado, o início mostra apenas a sua ação de bilhetes, não a lista completa nem a ação de voucher.

startMode: "home" abre a página inicial do evento. Aí escolhe-se Comprar bilhetes ou Resgatar voucher; abrir a página não cria carrinho nem resgata código. Comprar bilhetes abre os artigos (limitados por assortment, se definido); Resgatar voucher abre o formulário do código. Sem eventSlug, aparece primeiro a lista de eventos e depois a página inicial do evento escolhido. Um carrinho de voucher preparado ou percurso retomável tem prioridade.

// Server side: use the same session route as above, only the body varies.
// You build user and your backend's login/session route yourself.
// eventSlug sets the event. startMode also works without a slug (event
// selection first, then the mode); only assortment needs the slug
// (otherwise 400 start_option_requires_event_slug).

// 1) Article start (default): the event's article selection
const bodyArticles = { publicKey, email: user.email, eventSlug: "ExperienceDaysv52024" };

// 2) Assortment start: only one assortment (id or exact name, case-insensitive)
const bodyAssortment = {
  publicKey, email: user.email,
  eventSlug: "ExperienceDaysv52024",
  assortment: "Pressetickets",
};

// 3) Voucher start: "Redeem voucher / register ticket" first
const bodyVoucher = {
  publicKey, email: user.email,
  eventSlug: "ExperienceDaysv52024",
  startMode: "voucher" as const,
};

const res = await fetch("https://developers.aditus.com/api/shop/session", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.ADITUS_MINT_SECRET}`, "Content-Type": "application/json" },
  body: JSON.stringify(bodyVoucher),
});
const { sessionToken }: { sessionToken: string } = await res.json();

/* Voucher form: the same tokens and role hooks as the rest of the journey */
.aditus-shop__voucher-panel  { /* panel around hints + form (general panel hook) */ }
.aditus-shop__voucher-hints  { /* the two hint lines */ }
.aditus-shop__voucher-form   { /* form */ }
.aditus-shop__voucher-input  { /* code field (also .aditus-shop__field-input) */ }
.aditus-shop__voucher-redeem { /* "Redeem" button (data-variant="primary") */ }
.aditus-shop__field-error    { /* rejection reason, role="alert" */ }
/* Event home page and event actions: structured expert hooks */
.aditus-shop__home             { /* home page; root data-step="home" */ }
.aditus-shop__home-info        { /* event information */ }
.aditus-shop__home-info-head   { /* heading and logo */ }
.aditus-shop__home-info-name   { /* event name */ }
.aditus-shop__home-info-date   { /* date */ }
.aditus-shop__home-info-venue  { /* venue */ }
.aditus-shop__home-info-desc   { /* description */ }
.aditus-shop__home-actions[data-variant="tiles"] { /* tiles, alternatively compact */ }
.aditus-shop__home-action[data-kind="articles"] { /* buy tickets; also home / voucher / assortment */ }
.aditus-shop__home-action-icon    { /* icon */ }
.aditus-shop__home-action-body    { /* text group */ }
.aditus-shop__home-action-title   { /* label */ }
.aditus-shop__home-action-desc    { /* optional description */ }
.aditus-shop__home-action-chevron { /* arrow */ }
/* Phase hook: [data-step="voucher"] on the root */

Ligações de voucher: resgatar um código a partir do URL

Os vouchers são frequentemente enviados como ligações para a tua página com o código como parâmetro de consulta, p. ex. …/tickets?code=ED24-ADITUS. O micro-frontend pode assumir esse código e resgatá-lo sem que o visitante escreva nada. Existem duas vias de entrega; ambas terminam na mesma chamada de resgate e comportam-se de forma idêntica depois.

// Voucher links point to your site: https://your-site.com/tickets?code=ED24-ADITUS
// The route, request and authentication below are examples for your own website.
// The parameter name is up to you: here "code".

// Option A (browser): the micro-frontend reads the parameter itself.
import { mount } from "@aditus/shop-embed";

mount(document.getElementById("aditus-shop")!, {
  publicKey: "pk_your_site",
  sessionToken,                 // session with eventSlug (article or voucher start)
  voucherCodeParam: "code",     // read ?code=… once, remove it from the address bar, redeem it
});
// Web Component: <aditus-shop public-key="pk_your_site" voucher-code-param="code"></aditus-shop>

// Option B (server): your backend hands the code over when it creates the session.
// (Express example; the code never goes into the session response, only into the session context.)
app.get("/tickets", async (req, res) => {
  const code = typeof req.query.code === "string" ? req.query.code : undefined;
  const r = await fetch("https://developers.aditus.com/api/shop/session", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.ADITUS_MINT_SECRET}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      publicKey: "pk_your_site",
      email: req.user?.email,
      eventSlug: "ExperienceDaysv52024",
      startMode: "voucher",       // or omit: article start, the code lands in the first cart
      voucherCode: code,          // undefined = normal start without a code
    }),
  });
  const { sessionToken }: { sessionToken: string } = await r.json();
  // The page additionally mounts with voucherCodeParam: "code" so that ?code= disappears
  // from the address bar (the session code wins, it is redeemed only once).
  res.render("tickets", { sessionToken });
});

Opcional: reservar o voucher durante a criação da sessão no servidor

Se pretender tratar uma recusa antes de abrir o micro-frontend, defina redeemVoucherOnMint: true no POST /api/shop/session de confiança. Ao contrário da entrega normal do código, isto cria um carrinho para o utilizador autenticado e reserva efetivamente o voucher antes da emissão da sessão; não é uma verificação adicional. Em caso de sucesso, envie apenas o sessionToken ao navegador. O micro-frontend retoma o mesmo carrinho sem o recriar ou resgatar novamente, nos modos voucher e articles. Sem a opção aplica-se a entrega normal de voucherCode.

Este modo requer voucherCode, eventSlug definido, utilizador identificado (email; não anónimo) e cabeçalho Idempotency-Key. Só está disponível com o segredo de mint no servidor, não por POST /shop/embed-session no navegador. Aceita códigos voucher/bilhete, não PromotionCode. O código fica reservado num carrinho, mas o bilhete não está registado nem emitido. Registo e finalização continuam necessários e verificações posteriores podem falhar.

// Server side of your website: one voucher attempt, no additional check call.
// You implement the authentication and storage of this attempt yourself.
// attemptKey is a random id your backend stores durably per logical redemption
// attempt (e.g. crypto.randomUUID()). On network errors, resend the same id
// and the SAME body; never generate a new one before a retry.
async function prepareVoucherSession(
  user: { email: string },
  code: string,
  attemptKey: string,
) {
  const response = await fetch("https://developers.aditus.com/api/shop/session", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ADITUS_MINT_SECRET}`,
      "Content-Type": "application/json",
      "Idempotency-Key": attemptKey,
    },
    body: JSON.stringify({
      publicKey: "pk_your_site",
      email: user.email, // only from your authenticated server session
      eventSlug: "ExperienceDaysv52024",
      startMode: "voucher", // or "articles"
      voucherCode: code,
      redeemVoucherOnMint: true,
    }),
  });
  const result: {
    sessionToken?: string; expiresAt?: number; voucherRedeemed?: boolean;
    error?: string; reason?: string; upstreamStatus?: number;
  } = await response.json();

  if (response.ok && result.sessionToken && result.voucherRedeemed === true) {
    // Only now pass it to the browser and mount the embed.
    return { sessionToken: result.sessionToken, expiresAt: result.expiresAt };
  }
  if (response.status === 422 && result.error === "voucher_rejected") {
    // Your own UI: handle the business rejection using reason, do not open the embed.
    // Translate only documented reason values into your own texts.
    return { rejected: result.reason };
  }
  if (response.status === 409 && result.error === "voucher_preparation_uncertain") {
    // Uncertain stays uncertain; a repeated POST never turns it into a success.
    // If the Shop API cannot provide the cart id, manual clarification is needed.
    throw new Error("Redemption uncertain; clarify with ADITUS, do not book again.");
  }
  if (response.status === 410 && result.error === "voucher_preparation_expired") {
    throw new Error("Prepared session no longer valid; no blind new session.");
  }
  // 400 = invalid request/key, 409 = conflict/attempt in progress,
  // 502/503 voucher_upstream_error = infrastructure, not a business error.
  throw new Error(`Session creation not completed (${response.status})`);
}

422 voucher_rejected com reason higienizado é uma rejeição de negócio: apresente-a no seu site e não inicie o micro-frontend sem token. 400 indica configuração/chave inválida; 409 idempotency_conflict indica a mesma chave com dados diferentes. Uma operação pendente/incerta, 502/503 ou um timeout não indica um voucher inválido. Guarde um Idempotency-Key aleatório por tentativa lógica no servidor e repita apenas com a mesma chave e dados idênticos; pode já existir uma reserva. Não registe códigos, emails, erros brutos ou tokens.

Uma criação de sessão bem-sucedida pode deixar um carrinho reservado mesmo sem abrir a página. A limpeza de carrinhos conhecidos após recusa/revogação é tentada sem garantia; um processo no arranque e a cada 60 segundos repete até 25 registos por ciclo. A mesma chave e os mesmos dados repetem o resultado concluído ainda válido. Se o token original expirou, foi revogado, concluído, eliminado ou transferido, devolve 410 voucher_preparation_expired: não recrie a reserva às cegas. Um sucessor autorizado pode prolongá-la/transferi-la no primeiro acesso ao carrinho. Apagar o URL não liberta a reserva.

Erros exatos: 400 invalid_redeem_voucher_on_mint / voucher_preparation_requires_user_event_code / invalid_idempotency_key (ou validação normal); 422 voucher_rejected inclui reason e upstreamStatus, nunca código ou mensagem bruta do upstream. Motivos possíveis: unknown · articleLimit · exhausted · ownership · used · reserved · limit · cartLimit · locked · canceled · otherEvent · legitimation · rejected · unsupported_code_type.

409 idempotency_conflict indica dados alterados; voucher_preparation_pending inclui Retry-After: 2 segundos, enquanto voucher_preparation_uncertain continua incerto no retry (não há sucesso automático). 410 voucher_preparation_expired impede repetir a preparação original. 502/503 voucher_upstream_error é falha upstream. Se foi criado um carrinho sem devolver o respetivo ID, a API disponível não permite reconciliação nem libertação automáticas: o estado incerto é retido e não é criado outro carrinho no retry. Contacte a ADITUS para esclarecimento manual antes de nova tentativa. Se session-context falhar, o micro-frontend apresenta erro/retry sem criar outro carrinho.

Experimente as três variantes ao vivo no Testador de integração: crie uma sessão com eventSlug, escolha startMode ou um sortido, monte e observe o registo de pedidos. O sistema de demonstração aceita o voucher de teste ED24-ADITUS em ExperienceDaysv52024 (cada resgate reserva o bilhete cerca de 20 minutos; voltar atrás liberta-o). Abrir o Testador de integração

Opcional: navegar anonimamente e iniciar sessão no checkout

Não é necessário conhecer antecipadamente a identidade do utilizador. Faça o mount com uma sessão de convidado e o micro-frontend permitirá a um visitante anónimo consultar eventos, escolher artigos e preencher o carrinho. Só quando avança para além do carrinho (em direção ao registo e ao checkout) é solicitado o utilizador real através do callback onUserRequired. O restante fluxo prossegue sem perder o carrinho.

1. 1

   Faça o mount com uma sessão de convidado

   Um token de sessão ainda é necessário para ativar a loja – mas pode ser uma sessão de convidado: basta criá-lo sem o campo de email, sem necessidade de endereço fictício. O visitante navega e preenche o carrinho nessa sessão.

2. 2

   Deixar o carrinho aciona onUserRequired

   Quando o visitante avança para além do carrinho, o micro-frontend chama o callback uma vez e apresenta um estado neutro de espera. Autentique o utilizador (login/SSO) e crie uma nova sessão associada ao utilizador exatamente como a primeira: entre servidores, com o segredo. A identificação posterior do utilizador também é feita através desta criação de sessão entre servidores. O segredo nunca chega ao navegador e o utilizador nunca é definido no código do cliente. O callback apenas devolve o token opaco resultante. É essencial que o back-end obtenha esta identidade a partir da sua própria sessão autenticada (cookie/JWT); nunca deve aceitar o email ou o ID do utilizador enviados pelo navegador, pois um visitante mal-intencionado poderia pedir a sessão de outra pessoa e aceder aos respetivos dados pessoais através do preenchimento automático.

3. 3

   Devolva o novo token – o carrinho continua

   Devolva o novo sessionToken e o micro-frontend substitui o anterior e associa o utilizador identificado ao carrinho existente. O carrinho, os artigos e quaisquer intervalos horários permanecem inalterados. Em seguida, avança para o registo. Devolva null para cancelar. O visitante permanece simplesmente no carrinho, sem erro.

4. 4

   Omitir onUserRequired para um utilizador fixo

   Se o utilizador deixar o callback de fora, nada muda em relação ao fluxo clássico: faça o mount com uma sessão vinculada ao utilizador e o microfrontend atua como esse utilizador desde a primeira etapa.

import {
  mount,
  type ShopHandle,
  type AditusShopConfig,
} from "@aditus/shop-embed";

const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount target #aditus-shop not found");

// A guest session token is enough to mount: created server-to-server as
// usual, just without the email field (no placeholder address needed). The
// visitor may browse and fill the cart before a specific user is known.
const config: AditusShopConfig = {
  apiBase: "https://developers.aditus.com/api/shop",
  publicKey: "pk_your_site",
  sessionToken: guestSessionToken,

  // Called once as soon as the visitor leaves the cart towards registration.
  // This is where you authenticate the user (login/SSO) and create a new,
  // user-bound session server-to-server.
  // Return the fresh token -> the micro-frontend adopts it and rebuilds the
  // cart under the identified user (articles are kept). Return null to
  // cancel -> the visitor stays in the cart, without an error.
  onUserRequired: async () => {
    // Calls only your backend, with no identity in the payload. Your backend reads
    // the signed-in user from its own session (cookie/JWT) and creates the session
    // server-side for exactly this identity. Never pass the email from the browser,
    // otherwise an attacker could insert someone else's address here and reach
    // that person's personal data through the prefill.
    // host.loginAndMintSession(): Promise<string | null> is your own function.
    // Implement login/SSO + authenticated backend call + server-side session creation on your website.
    // On cancel the function returns null; on failure it throws explicitly.
    return host.loginAndMintSession();
  },
};

const handle: ShopHandle = mount(el, config);

GA4/eventos de comércio eletrónico (opcional)

O micro-frontend pode comunicar o funil de compras ao sistema de analytics, mas apenas se essa opção for configurada. Não inclui gtag, GTM nem o SDK do GA, não carrega recursos, não define cookies e não envia dados autonomamente. Adicione o callback opcional onEvent para receber eventos tipados, já estruturados segundo o esquema Enhanced Ecommerce do GA4. Se omitir onEvent, nada muda. A ferramenta de destino e a validação do consentimento ficam inteiramente a cargo da integração.

import {
  mount,
  type ShopHandle,
  type ShopAnalyticsEvent,
} from "@aditus/shop-embed";

const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount target #aditus-shop not found");

const handle: ShopHandle = mount(el, {
  publicKey: "pk_your_site",
  sessionToken,
  // Optional. If you leave out onEvent, nothing changes: the micro-frontend
  // sends nothing, loads no gtag/GTM/GA SDK and sets no cookies.
  // Tool, consent and mapping stay entirely with you. This example uses GA4 via gtag.
  onEvent: (event: ShopAnalyticsEvent) => {
    // Consent is yours: only send once the user has agreed.
    if (!hasAnalyticsConsent()) return;
    // The events already follow the GA4 schema (name + items/value/currency ...),
    // so pass them to gtag 1:1.
    const { name, ...params } = event;
    window.gtag?.("event", name, params);
  },
});

publicKey vs. sessionToken

Mantenha os dois separados. Eles respondem a perguntas diferentes e estão emparelhados, não intercambiáveis.

Referência de endpoint e resposta

Ambas as chamadas vêm do seu back-end: autentica-se com o mint secret do seu cliente (gerado na consola de administração ADITUS) como token Bearer. Uma sessão por login é o padrão habitual; o navegador só vê o token resultante. Sites sem back-end não usam estes endpoints: o elemento cria a própria sessão de navegador através de POST /api/shop/embed-session, restrito por domínio (public-key com cart-scope="tab").

Pode experimentar este fluxo exato com as suas próprias credenciais notestador de integração. Crie a sessão, efetue o mount e percorra o fluxo.

Criar uma sessão: pedido

Criar uma sessão: resposta (200)

Revogar uma sessão

DELETE /api/shop/session/:token com o mesmo segredo Bearer. O segredo tem de pertencer ao cliente para o qual a sessão foi criada. Chame este endpoint ao terminar sessão para invalidar o token juntamente com a sessão do seu sistema. Resposta: { "revoked": true } (ou false se a sessão já tiver expirado). A revogação é idempotente e pode ser efetuada em modo fire-and-forget.

Leituras servidor a servidor

Um backend que controla o micro-frontend (uma shell de quiosque, uma loja no local) precisa normalmente de dados do tenant antes de criar a sessão: que eventos existem e estão à venda, que idiomas a loja fala, que listas de referência e que branding se aplicam. Quatro endpoints de leitura respondem com as mesmas credenciais da criação (segredo Bearer + cabeçalho X-Aditus-Public-Key, mesmo limite de pedidos, Cache-Control: no-store). São projeções filtradas da Shop API, nunca um reencaminhamento em bruto; ?language= (ou Accept-Language, por defeito de) escolhe o idioma dos nomes. Erros: 400 invalid_public_key, 401 unauthorized, 503 shop_api_not_configured, 502 upstream_error.

Erros são explícitos