Integrar la tienda de entradas de forma nativa

Inicio rápido

Hay dos caminos hacia una tienda en funcionamiento. Ambos usan el mismo script y el mismo elemento; se diferencian en quién crea la sesión.

Sin backend

El elemento crea él mismo una sesión de navegador para tu publicKey, limitada a los dominios permitidos. Define cart-scope="tab": sin identidad de servidor, el valor por defecto "shared" termina en un error explícito. Cada pestaña tiene entonces su propio carrito. La sesión es anónima: los visitantes exploran y llenan el carrito. Antes del registro, element.config.onUserRequired debe devolver un token de sesión vinculado a un usuario emitido por un servidor; sin él la tienda se detiene en el carrito con un 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>

Con backend

Tu servidor crea la sesión con el mint secret y decide quién es el comprador. Pasa el token devuelto al elemento. Con el email del comprador, el valor por defecto cart-scope "shared" mantiene un único carrito en todas las pestañas.

// 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>

Sustituye pk_your_site por tu clave publicable del admin de ADITUS. developers.aditus.com es la dirección de producción del script y de la API. Ambos caminos se describen en detalle más abajo.

La tecnología detrás del micro-frontend

El micro-frontend muestra todo el proceso de compra (eventos, artículos, carrito, registro, pago, finalización) en el DOM de tu página. Usa el diseño de tu página y tu CSS puede dar estilo a cada parte.

Tu sitio es de confianza: tu servidor autentica al usuario antes de generar una sesión identificada. El micro-frontend se muestra deliberadamente en el Light DOM de tu página, sin aislamiento iframe. Los scripts de tu página pueden acceder al DOM y al almacenamiento del navegador; por eso, protege tu sitio y sus scripts de terceros. La autorización de origen con clave pública no es una autenticación del usuario. Los datos de pago solo se introducen en la página externa del proveedor de pagos.

Seguridad de pagos, PCI y CSP

La preparación de la compra se muestra en tu página. El pago se realiza en la página del proveedor de pagos, así que ningún dato de pago pasa por tu página.

Comparación con iframe y shadow DOM

Los enfoques comparados

Alternativa: paquete fuente (distribuido por ti)

Como alternativa, descarga el paquete fuente de tu instancia ADITUS e intégralo en tu aplicación (Vite, webpack, Next.js o Nuxt). Tú te encargas de distribuirlo: cada actualización exige reinstalar, compilar y desplegar. No está en npm público.

Apps SSR: Next.js y Nuxt

El micro-frontend es deliberadamente client-only. Su contenido está en vivo y ligado a la sesión: disponibilidad, precios y el carrito del usuario existen solo para una sesión autenticada en el momento de la petición, así que no hay nada significativo que tu servidor pudiera pre-renderizar. mount() crea una nueva raíz React del lado del cliente (createRoot); el marcado renderizado en el servidor dentro del contenedor no se hidrata. Eso hace que la integración SSR sea simple y predecible: renderiza un placeholder en el servidor, monta en el cliente y reserva el espacio 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 }} />;
}

El micro-frontend necesita una sesión

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.

Al recargar, un puntero válido permite solicitar el carrito del servidor con el mismo ámbito autorizado e identidad de confianza. No autoriza ni garantiza recuperar tras vencimientos, borrar el almacenamiento o cambiar de usuario. tab no une recorridos de otras pestañas; shared mantiene el bloqueo de checkout con un solo escritor.

El retorno de pago usa aditus-return (un token opaco, breve y vinculado al servidor) junto con aditus-pay. Puede volver en la misma pestaña o en una nueva, pero el servidor exige cliente/origen autorizado e identidad de confianza coincidente. Los parámetros de retorno no prueban una compra. El servidor comprueba el pago y finaliza el intento vinculado al token; un resultado desconocido permanece bloqueado para aclaración, sin repetir a ciegas una nueva compra. Los retornos vencidos o no autorizados son errores explícitos, no permiso para crear un pedido sustituto.

Asignar un proveedor solo prepara el pago: el resumen sigue editable. El bloqueo comienza en la redirección efectiva, tras los consentimientos requeridos. Un parámetro de retorno cancel/error no demuestra un fallo: el backend vuelve a consultar el carrito; Completed con order.id confirma la finalización. Solo eliminar correctamente y con confirmación la asignación del proveedor para ese mismo carrito permite reintentar; los resultados ambiguos siguen bloqueados y pueden volver a comprobarse. Esto no garantiza un reembolso ni excluye una liquidación tardía.

Pago con redirección: qué debe hacer tu página con la sesión

• Sirve la URL de retorno configurada con el embed montado. Conserva aditus-return y aditus-pay al enrutar o redirigir al login; aditus-pay=success nunca es autorización. Proporciona una sesión válida para la misma identidad de confianza y publicKey. Mantén cartScope y no borres el recorrido ni inicies otro checkout para eludir un retorno pendiente, vencido o incierto.

¿Prefieres un reinicio deliberado con un verdadero botón de «empezar de nuevo»? El paquete exporta clearJourney(): llámalo antes de montar (o volver a montar), y se descarta el registro de recorrido persistido localmente para la página actual, de modo que el siguiente mount arranca desde cero en el punto de entrada. Solo se elimina el puntero de reanudación local; cualquier estado de carrito en el servidor queda intacto.

Punto de entrada: inicio del evento, artículos o vale

Tu servidor decide el inicio al generar la sesión, nunca el navegador. Sin eventSlug aparece la lista de eventos. Con eventSlug, startMode elige artículos (predeterminado), inicio o formulario de vale; assortment limita los artículos.

La selección de artículos y la continuación tras un vale siguen la ruta de la tienda original basada en recomendaciones. Sin oferta upsell utilizable ni venta cruzada, se pasa directamente a la personalización de entradas con las comprobaciones normales de inicio de sesión; con venta cruzada, se muestra el carrito. Una oferta upsell utilizable abre primero su diálogo. Omitir lleva a la personalización sin venta cruzada, o al carrito si la hay. Una mejora confirmada lleva al carrito; cerrar el diálogo mantiene la selección. La ruta nunca guarda el registro en segundo plano.

Los surtidos visibles pueden tener entradas directas. Si se fija un surtido, el inicio muestra solo su acceso a entradas, no la lista completa ni la acción de vale.

startMode: "home" abre la página de inicio del evento. Allí se elige Comprar entradas o Canjear vale; abrirla no crea un carrito ni canjea un código. Comprar entradas abre la selección de artículos (limitada por assortment si está definido); Canjear vale abre el formulario del código. Sin eventSlug aparece primero la lista de eventos y después la página de inicio del evento elegido. Un carrito de vale preparado o un recorrido reanudable tiene prioridad.

// 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 */

Enlaces de vale: canjear un código desde la URL

Los vales suelen enviarse como enlaces a tu página con el código como parámetro de consulta, p. ej. …/tickets?code=ED24-ADITUS. El micro-frontend puede tomar ese código y canjearlo sin que el visitante escriba nada. Hay dos vías de entrega; ambas terminan en la misma llamada de canje y se comportan igual después.

// 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 el vale al generar la sesión en el servidor

Si quieres tratar el rechazo antes de abrir el micro-frontend, pon redeemVoucherOnMint: true en el POST /api/shop/session de confianza. A diferencia de la entrega normal del código, se crea un carrito para el usuario autenticado y se reserva realmente el vale antes de emitir la sesión: no es una comprobación extra. Si funciona, pasa solo sessionToken al navegador. El micro-frontend retoma el mismo carrito sin crearlo ni canjear dos veces, tanto en modo voucher como articles. Sin la opción se aplica la entrega normal de voucherCode.

Este modo requiere voucherCode, eventSlug fijo, un usuario identificado (email; no anónimo) y la cabecera Idempotency-Key. Solo está disponible en el backend con secreto de generación, no en POST /shop/embed-session en el navegador. Admite códigos de vale/entrada, no PromotionCode. El código queda reservado en un carrito; la entrada no está registrada ni emitida. Deben completarse registro y compra, y comprobaciones posteriores pueden fallar.

// 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 con reason saneado es un rechazo de negocio: muéstralo en TU interfaz, no montes el micro-frontend sin token. 400 indica configuración/clave incorrecta; 409 idempotency_conflict es reutilizar la clave con datos diferentes. Un intento pendiente/incierto, 502/503 o un timeout no son un vale inválido. Guarda Idempotency-Key aleatorio por intento lógico en tu servidor; reintenta solo con la misma clave y datos idénticos. Puede existir ya una reserva. No registres códigos, emails, errores sin filtrar ni tokens.

Una sesión emitida puede dejar un carrito reservado aunque nunca se abra la página. La limpieza de carritos conocidos tras rechazo/revocación se intenta sin garantía; un proceso al arrancar y cada 60 segundos reintenta hasta 25 registros por ciclo. La misma clave y los mismos datos repiten el resultado terminado aún válido. Si el token original caducó, se revocó, completó, borró o transfirió, la respuesta es 410 voucher_preparation_expired: no recrees la reserva a ciegas. Un sucesor autorizado puede ampliarla/transferirla al acceder al carrito por primera vez. Borrar la URL no libera nada.

Errores exactos: 400 invalid_redeem_voucher_on_mint / voucher_preparation_requires_user_event_code / invalid_idempotency_key (o validación normal); 422 voucher_rejected contiene reason y upstreamStatus, nunca el código o mensaje bruto upstream. Motivos posibles: unknown · articleLimit · exhausted · ownership · used · reserved · limit · cartLimit · locked · canceled · otherEvent · legitimation · rejected · unsupported_code_type.

409 idempotency_conflict indica datos cambiados; voucher_preparation_pending incluye Retry-After: 2 segundos y voucher_preparation_uncertain sigue incierto tras reintentar (no hay éxito automático). 410 voucher_preparation_expired impide repetir la preparación original. 502/503 voucher_upstream_error significa fallo upstream. Si se creó un carrito pero no se recibió su ID, la API disponible no permite conciliarlo ni liberarlo automáticamente: se guarda el estado incierto y no se crea otro carrito al reintentar. Consulta a ADITUS manualmente antes de iniciar un nuevo intento. Si falla session-context, el micro-frontend muestra error/reintento sin crear un carrito nuevo.

Prueba las tres variantes en vivo en el Probador de integración: genera una sesión con eventSlug, elige startMode o un surtido, monta y observa el registro de peticiones. El sistema de demostración acepta el vale de prueba ED24-ADITUS en ExperienceDaysv52024 (cada canje reserva la entrada unos 20 minutos; volver atrás la libera). Abrir el Probador de integración

Opcional: navegar de forma anónima, iniciar sesión en el pago

No tienes que saber de antemano quién es el usuario. Monta con una sesión de invitado y el micro-frontend permite a un visitante anónimo explorar eventos, elegir artículos y llenar el carrito. Solo cuando avanza más allá del carrito (hacia el registro y el pago) te pide definir el usuario real, mediante el callback onUserRequired. El resto del flujo continúa entonces con el carrito preservado.

1. 1

   Montar con una sesión de invitado

   Sigue siendo necesario un token de sesión para activar la tienda, pero puede ser una sesión de invitado: simplemente genérala sin el campo email, sin necesidad de una dirección de marcador de posición. El visitante navega y llena el carrito bajo ella.

2. 2

   Salir del carrito activa onUserRequired

   En el momento en que el visitante avanza más allá del carrito, el micro-frontend llama a tu callback una vez y muestra un estado de espera neutro. Autentica al usuario (login/SSO), luego genera una nueva sesión ligada al usuario exactamente igual que la primera: servidor a servidor con tu secreto. La definición posterior del usuario también pasa por esa creación de sesión entre servidores. El secreto nunca llega al browser y el usuario nunca se define en el código cliente. Tu callback solo retransmite el token opaco resultante. Fundamental: tu backend deriva esa identidad de SU propia sesión autenticada (cookie/JWT); nunca debe aceptar el correo o el identificador de usuario desde el browser, o un visitante malicioso podría solicitar la sesión de otra persona y leer sus datos personales mediante el prellenado.

3. 3

   Devuelve el nuevo token. El carrito se conserva

   Devuelve el nuevo token de sesión y el micro-frontend lo adopta y liga al usuario identificado al carrito existente. El carrito, sus artículos y cualquier franja horaria se conservan sin cambios. Luego pasa al registro. Devuelve null para cancelar. El visitante simplemente permanece en el carrito, sin error.

4. 4

   Omitir onUserRequired para un usuario fijo

   Si omites el callback, nada cambia respecto al flujo clásico: monta con una sesión ligada a un usuario y el micro-frontend actúa como ese usuario desde el primer paso.

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);

Eventos GA4 / e-commerce (opcional)

El micro-frontend puede reportar el embudo de compra a tu analítica, pero solo si se lo pides. No incluye gtag, ni GTM, ni SDK de GA, no carga nada, no establece cookies y no envía nada por su cuenta. Añades un callback opcional, onEvent, y recibes eventos tipados ya formados según el esquema GA4 Enhanced Ecommerce de Google. Omite onEvent y nada cambia. Qué herramienta alimentas, y si tienes consentimiento para enviar, queda enteramente de tu lado.

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

Mantén los dos separados. Responden a preguntas diferentes y se emparejan, no son intercambiables.

Referencia de endpoints y respuestas

Ambas llamadas proceden de tu backend: se autentica con el mint secret de tu cliente (generado en la consola de administración de ADITUS) como token Bearer. Una sesión por inicio de sesión es el patrón normal; el navegador solo ve el token resultante. Los sitios sin backend no usan estos endpoints: el elemento crea su propia sesión de navegador mediante POST /api/shop/embed-session, restringido por dominio (public-key con cart-scope="tab").

Puedes probar este mismo flujo con tus propias credenciales en el probador de integración. Genera una sesión, monta la tienda y sigue el recorrido.

Generar una sesión: petición

Generar una sesión: respuesta (200)

Revocar una sesión

DELETE /api/shop/session/:token con el mismo secreto Bearer. El secreto debe pertenecer al cliente para el que se generó la sesión. Llámalo al cerrar sesión para que el token muera junto con tu propia sesión. Respuesta: { "revoked": true } (o false si la sesión ya había expirado). La revocación es idempotente y se puede enviar en fire-and-forget.

Lecturas servidor a servidor

Un backend que controla el micro-frontend (una shell de quiosco, una tienda in situ) suele necesitar datos del tenant antes de generar la sesión: qué eventos existen y están en venta, qué idiomas habla la tienda, qué listas de referencia y qué branding aplican. Cuatro endpoints de lectura responden con las mismas credenciales que la generación (secreto Bearer + cabecera X-Aditus-Public-Key, mismo límite de peticiones, Cache-Control: no-store). Son proyecciones filtradas de la Shop API, nunca un reenvío en bruto; ?language= (o Accept-Language, por defecto de) elige el idioma de los nombres. Errores: 400 invalid_public_key, 401 unauthorized, 503 shop_api_not_configured, 502 upstream_error.

Los errores son explícitos