Embed SDK

Descripción general

El Komerza Embed SDK te permite integrar de forma transparente nuestra experiencia de pago directamente en tu sitio web. En lugar de redirigir a los clientes a una página de pago separada, el embed crea una superposición modal que mantiene a los usuarios en tu sitio mientras proporciona un flujo de pago seguro y optimizado.

Demo en vivo

Ve el Embed SDK en acción con nuestra demo interactiva

También integra nuestro script de análisis para recuperar análisis de visitantes en tu sitio personalizado para obtener información completa sobre el recorrido del cliente.

Características

Integración transparente

La superposición modal mantiene a los clientes en tu sitio durante el pago

Ligero

Paquete JavaScript mínimo sin dependencias externas

Soporte de temas

Temas claro, oscuro y automático para combinar con el diseño de tu sitio

Compatible con CSP

Soporte completo de política de seguridad de contenido con integración de nonce

Inicio rápido

Agrega el siguiente script al <head> de tu sitio web o antes de la etiqueta de cierre </body>:

<script src="https://checkout.komerza.com/embed/embed.iife.js" defer></script>

Método 1: Atributos de datos (Recomendado para casos simples)

La forma más fácil de agregar botones de pago a tu sitio. Solo agrega atributos de datos a cualquier botón o elemento:

<button
  data-kmrza-product-id="YOUR_PRODUCT_ID"
  data-kmrza-variant-id="YOUR_VARIANT_ID"
  data-kmrza-quantity="1"
  data-kmrza-theme="auto"
>
  Comprar ahora
</button>

<script src="https://checkout.komerza.com/embed/embed.iife.js" defer></script>
<script>
  // Inicializar el embed para vincular todos los botones con atributos de datos
  document.addEventListener("DOMContentLoaded", () => {
    Komerza.init();
  });
</script>

Referencia de atributos de datos

Atributo	Requerido	Descripción	Ejemplo
`data-kmrza-product-id`	✅ Sí	El ID del producto de Komerza	`"0f6294be-25d6-4ced-96df-7d500608c54d"`
`data-kmrza-variant-id`	❌ No	El ID de la variante de Komerza. Omítelo para que el cliente elija - ver abajo	`"96f846e5-5f22-46a2-97b3-a1c88f685577"`
`data-kmrza-quantity`	❌ No	Cantidad a comprar (predeterminado: 1)	`"2"`
`data-kmrza-theme`	❌ No	Modo de tema: `light`, `dark` o `auto` (predeterminado: `auto`)	`"dark"`
`data-kmrza-return-url`	❌ No	URL personalizada de redirección tras el pago	`"https://example.com/gracias"`
`data-kmrza-email`	❌ No	Prerrellenar la dirección de correo del cliente	`"cliente@example.com"`
`data-kmrza-coupon-code`	❌ No	Prerrellenar y aplicar automáticamente un código de cupón	`"SAVE20"`
`data-kmrza-metadata`	❌ No	Cadena JSON de metadatos clave-valor personalizados	`"{"campaign":"summer"}"`

Deja que el cliente elija la variante

data-kmrza-variant-id es opcional. Si lo omites, el checkout se abre con un selector de variante para que el cliente elija antes de pagar.

<button data-kmrza-product-id="YOUR_PRODUCT_ID">Comprar ahora</button>

Útil para un único botón de compra en un producto con varias ediciones, planes o duraciones. Pasa data-kmrza-variant-id cuando quieras que el cliente llegue directamente a una variante concreta.

Método 2: API de JavaScript (Para casos de uso avanzados)

Para mayor control, usa la API de JavaScript para abrir el pago programáticamente:

<button id="checkout-btn">Comprar ahora</button>

<script src="https://checkout.komerza.com/embed/embed.iife.js" defer></script>
<script>
  document.getElementById("checkout-btn").addEventListener("click", () => {
    Komerza.open({
      items: [
        {
          productId: "YOUR_PRODUCT_ID",
          variantId: "YOUR_VARIANT_ID",
          quantity: 1,
        },
      ],
      theme: "auto", // 'light', 'dark' o 'auto'
    });
  });
</script>

Múltiples artículos

Puedes agregar varios productos al pago a la vez:

Komerza.open({
  items: [
    {
      productId: "0f6294be-25d6-4ced-96df-7d500608c54d",
      variantId: "96f846e5-5f22-46a2-97b3-a1c88f685577",
      quantity: 2,
    },
    {
      productId: "54d6adb4-c160-4f73-b9c0-6c16970fff41",
      variantId: "37e70705-c603-4ab2-8a2e-d16e80288c8c",
      quantity: 1,
    },
  ],
  theme: "light",
});

Guía de implementación completa

Configuración HTML

Aquí hay un ejemplo completo de página HTML:

<!DOCTYPE html>
<html lang="es">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Mi Tienda</title>

    <!-- Encabezado CSP (recomendado) -->
    <meta
      http-equiv="Content-Security-Policy"
      content="frame-src https://checkout.komerza.com; script-src 'self' 'nonce-abc123' https://checkout.komerza.com;"
    />
  </head>
  <body>
    <div class="product-container">
      <h1>Producto increíble</h1>
      <p>Precio: 29,99 €</p>

      <!-- Tu botón de compra -->
      <button id="buy-now" class="buy-button">Comprar ahora</button>
    </div>

    <!-- Komerza Embed SDK -->
    <script
      src="https://checkout.komerza.com/embed/embed.iife.js"
      nonce="abc123"
    ></script>

    <script nonce="abc123">
      // Tu código de integración aquí
    </script>
  </body>
</html>

Integración JavaScript

Integración básica
Integración avanzada
Integración React

document.addEventListener('DOMContentLoaded', function() {
  Komerza.init();
  
  document.getElementById('buy-now').addEventListener('click', function() {
    Komerza.open({
      items: [{ productId: 'prod_123', variantId: 'var_456', quantity: 1 }]
    });
  });
});

class CheckoutManager {
  constructor() {
    this.isInitialized = false;
    this.init();
  }
  
  init() {
    Komerza.init({ nonce: this.getCSPNonce() });
    this.isInitialized = true;
    this.bindEvents();
  }
  
  bindEvents() {
    document.querySelectorAll('[data-buy-button]').forEach(button => {
      button.addEventListener('click', (e) => { e.preventDefault(); this.handlePurchase(button); });
    });
    document.addEventListener('keydown', (e) => { if (e.key === 'Escape') Komerza.close(); });
  }
  
  handlePurchase(button) {
    const { productId, variantId } = button.dataset;
    const quantity = parseInt(button.dataset.quantity) || 1;
    if (!productId || !variantId) { console.error('Falta ID de producto o variante'); return; }
    try {
      Komerza.open({ items: [{ productId, variantId, quantity }], theme: this.getTheme() });
    } catch (error) {
      console.error('No se pudo abrir el pago:', error);
      window.location.href = `https://checkout.komerza.com/product/${productId}/${variantId}?qty=${quantity}`;
    }
  }
  
  getTheme() { return window.matchMedia?.('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'; }
  getCSPNonce() { return document.querySelector('script[nonce]')?.getAttribute('nonce') ?? null; }
}

document.addEventListener('DOMContentLoaded', () => new CheckoutManager());

import React, { useEffect, useState } from 'react';

const ProductPage: React.FC = () => {
  const [isEmbedReady, setIsEmbedReady] = useState(false);
  
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://checkout.komerza.com/embed/embed.iife.js';
    script.onload = () => { window.Komerza.init(); setIsEmbedReady(true); };
    document.head.appendChild(script);
    return () => document.head.removeChild(script);
  }, []);
  
  const handleBuyClick = () => {
    if (!isEmbedReady) return;
    window.Komerza.open({
      items: [{ productId: 'prod_123', variantId: 'var_456', quantity: 1 }],
      theme: 'auto'
    });
  };
  
  return (
    <div className="product-page">
      <h1>Producto increíble</h1>
      <p>Precio: 29,99 €</p>
      <button onClick={handleBuyClick} disabled={!isEmbedReady} className="buy-button">
        {isEmbedReady ? 'Comprar ahora' : 'Cargando...'}
      </button>
    </div>
  );
};

export default ProductPage;

Referencia de API

`Komerza.init(options?)`

Inicializa el embed y vincula automáticamente todos los elementos con atributos data-kmrza-*.

Komerza.init({
  nonce: "TU_NONCE_CSP", // Opcional: para política de seguridad de contenido
});

`Komerza.open(options)`

Abre la modal de pago programáticamente.

Komerza.open({
  items: [{ productId: string, variantId: string, quantity?: number }],
  theme?: 'light' | 'dark' | 'auto',
  affiliateCode?: string,
  returnUrl?: string,
  email?: string,
  couponCode?: string,
  metadata?: Record<string, string>
});

`Komerza.close()`

Cierra la modal de pago programáticamente.

Komerza.close();

Integración Next.js

// components/CheckoutButton.jsx
"use client";

import Script from "next/script";

export default function CheckoutButton({ productId, variantId, quantity = 1 }) {
  const handleClick = () => {
    if (window.Komerza) {
      window.Komerza.open({ items: [{ productId, variantId, quantity }] });
    }
  };

  return (
    <>
      <Script
        src="https://checkout.komerza.com/embed/embed.iife.js"
        strategy="lazyOnload"
      />
      <button onClick={handleClick}>Comprar ahora</button>
    </>
  );
}

Solución de problemas

El pago no se abre

Asegúrate de que el script está cargado (se recomienda el atributo defer)
Revisa la consola del navegador para ver errores
Verifica que tus IDs de producto y variante sean correctos
Si usas atributos de datos, asegúrate de que Komerza.init() se llama después de que el DOM esté cargado

El modal usa un z-index alto (9999). Si sigue detrás de otros elementos, revisa tu CSS para valores z-index competidores.

Afiliados

El Komerza Embed SDK admite el seguimiento de afiliados de forma nativa. El parámetro de consulta ?ref se admite automáticamente y la cookie kmrza_affiliate se lee automáticamente.

Política de seguridad de contenido (CSP)

Content-Security-Policy:
  frame-src https://checkout.komerza.com;
  script-src 'self' 'nonce-TU_NONCE' https://checkout.komerza.com;
  style-src 'self' 'nonce-TU_NONCE';

Komerza.init({ nonce: "TU_NONCE" });

Mejores prácticas

Rendimiento

Carga el script del SDK de forma asíncrona cuando sea posible
Inicializa el SDK temprano pero abre los modales solo con la interacción del usuario
Implementa estados de carga adecuados para los botones de compra

Experiencia de usuario

Proporciona indicadores de carga claros - Maneja los errores de red graciosamente con URLs de respaldo - Admite la navegación por teclado (Esc para cerrar)

Seguridad

Usa siempre encabezados CSP en producción
Valida los IDs de producto y variante antes de abrir el pago
Nunca expongas datos sensibles en el código del lado del cliente

Soporte

¿Necesitas ayuda con la integración?

Página de demo

Demo interactiva con ejemplos de código fuente

Soporte para desarrolladores

Obtén soporte técnico para problemas de integración

Empezar

Configuración de la Tienda

Guías de Integración

Configuración de Pagos

Descripción general

Demo en vivo

Características

Integración transparente

Ligero

Soporte de temas

Compatible con CSP

Inicio rápido

Método 1: Atributos de datos (Recomendado para casos simples)

Referencia de atributos de datos

Deja que el cliente elija la variante

Método 2: API de JavaScript (Para casos de uso avanzados)

Múltiples artículos

Guía de implementación completa

Configuración HTML

Integración JavaScript

Referencia de API

`Komerza.init(options?)`

`Komerza.open(options)`

`Komerza.close()`

Integración Next.js

Solución de problemas

El pago no se abre

Afiliados

Política de seguridad de contenido (CSP)

Mejores prácticas

Soporte

Página de demo

Soporte para desarrolladores

​Descripción general

Demo en vivo

​Características

Integración transparente

Ligero

Soporte de temas

Compatible con CSP

​Inicio rápido

​Método 1: Atributos de datos (Recomendado para casos simples)

​Referencia de atributos de datos

​Deja que el cliente elija la variante

​Método 2: API de JavaScript (Para casos de uso avanzados)

​Múltiples artículos

​Guía de implementación completa

​Configuración HTML

​Integración JavaScript

​Referencia de API

​Komerza.init(options?)

​Komerza.open(options)

​Komerza.close()

​Integración Next.js

​Solución de problemas

​El pago no se abre

​El modal aparece detrás de otros elementos

​Afiliados

​Política de seguridad de contenido (CSP)

​Mejores prácticas

​Soporte

Página de demo

Soporte para desarrolladores

Descripción general

Características

Inicio rápido

Método 1: Atributos de datos (Recomendado para casos simples)

Referencia de atributos de datos

Deja que el cliente elija la variante

Método 2: API de JavaScript (Para casos de uso avanzados)

Múltiples artículos

Guía de implementación completa

Configuración HTML

Integración JavaScript

Referencia de API

`Komerza.init(options?)`

`Komerza.open(options)`

`Komerza.close()`

Integración Next.js

Solución de problemas

El pago no se abre

El modal aparece detrás de otros elementos

Afiliados

Política de seguridad de contenido (CSP)

Mejores prácticas

Soporte