Kit de partners

Documentación API

El Shoppi SDK, la API JSON y los TagCodes: todo lo que un partner necesita para construir sobre una tienda Shoppi.

SDK 2.7.5 JSON API Stripe Checkout TagCodes
Cómo funcionaInstalaciónTienda y contenidos — Shoppi.siteCarrito — Shoppi.cartCheckout — Shoppi.checkoutCuentas de clientes — Shoppi.userNavegación y traducciones — Shoppi.router, Shoppi.langDirectorio local — Shoppi.localEmail — Shoppi.mailerAPI JSONTagCodes (lado servidor)Acceso a archivos y datos

Los ejemplos de código están en inglés, como los nombres de los métodos.

Cómo funciona

Cada tienda en Shoppi Cloud se amplía con el Shoppi SDK, una librería JavaScript que la plataforma sirve en cada dominio alojado por Shoppi, y con los TagCodes, marcadores del lado del servidor que el motor de páginas resuelve antes de que la página llegue al navegador. Ambos hablan con la misma API JSON, que también se puede usar directamente.

  • Sin claves API en el navegador. La tienda se reconoce por el dominio desde el que sale la petición: el SDK funciona en el dominio de la tienda sin secretos en el código.
  • Los pagos pasan por Stripe. Las sesiones de checkout se crean en la cuenta Stripe del comerciante (Stripe Connect); Shoppi nunca retiene el dinero de sus clientes. Los reembolsos también pasan íntegramente por Stripe.
  • Cada tienda tiene su propia base de datos. Los clientes registrados con el SDK se guardan en la base de datos de la tienda, separados de las demás tiendas.
  • Versión actual del SDK: 2.7.5. Las respuestas tienen siempre la misma forma: {"result": "ok" | "ko", "feedback": …}.

Instalación

Incluye el SDK una sola vez, en el <head> de la página. Al cargar crea el objeto global window.Shoppi.

<script>
window.ShoppiConfig = {
    pageId:        "%_ID%",  // store id; the page engine fills it in (use %_ID% inside JS, not {id})
    currency:      "EUR",    // default currency for cart and checkout
    defaultLocale: "it",     // language used when the URL has no /xx/ prefix
    baseUrl:       ""        // leave empty: API calls go to the same origin
};
</script>
<script src="/shoppi/shoppi-sdk.js?v=2.7.5"></script>

Todos los ajustes son opcionales: sin ShoppiConfig el SDK reconoce la tienda por el dominio y usa el euro. Sube el parámetro ?v= para que los navegadores descarguen un SDK más reciente.

Tienda y contenidos — Shoppi.site

Método Devuelve
Shoppi.site.getInfo() Perfil de la tienda: nombre, logo, descripción.
Shoppi.site.getPage(slug) Una página de contenido por su slug, por ejemplo 'about-us'. Devuelve título y contenido HTML. 
const info = await Shoppi.site.getInfo();
document.getElementById('store-name').textContent = info.title;

Carrito — Shoppi.cart

El carrito vive en el navegador (localStorage) y sobrevive a la recarga. Los precios y títulos que pases llegan hasta el checkout, así que indícalos siempre.

Llamada Qué hace
Shoppi.cart.add(id, qty, { price, title, image }) Añade un producto (cantidad 1 por defecto).
Shoppi.cart.updateQty(id, qty) Fija la cantidad; 0 quita la línea.
Shoppi.cart.remove(id) Quita una línea.
Shoppi.cart.clear() Vacía el carrito.
Shoppi.cart.setCountry(code) Fija el país de envío (código ISO, por ejemplo 'IT').
Shoppi.cart.data Estado actual: { items, count, total, country }.

Sin JavaScript, con atributos HTML:

<button data-shoppi-add="10034"
        data-shoppi-price="29.90"
        data-shoppi-title="Leather wallet"
        data-shoppi-image="/img/wallet.jpg">Add to cart</button>

<span class="shoppi-cart-count"></span>   <!-- item count, updated automatically -->
<span class="shoppi-cart-total"></span>   <!-- total, formatted in the store currency -->

<select data-shoppi-country>              <!-- shipping country -->
  <option value="IT">Italia</option>
  <option value="DE">Deutschland</option>
</select>

<button data-shoppi-checkout>Checkout</button>

Checkout — Shoppi.checkout

Método Qué hace
Shoppi.checkout.start() Crea una sesión de Stripe Checkout para el carrito en la cuenta Stripe del comerciante y lleva al cliente a ella.
Shoppi.checkout.startDirect(productId, metadata) Compra en un clic de un solo producto, sin carrito (servicios, reservas, descargas).
Shoppi.checkout.createOnboardingLink() Devuelve el enlace de onboarding de Stripe de la tienda, para conectar o completar su cuenta Stripe. 
document.querySelector('#buy').addEventListener('click', () => Shoppi.checkout.start());

// Stripe onboarding for the merchant
const url = await Shoppi.checkout.createOnboardingLink();
window.location.href = url;

Cualquier botón con data-shoppi-checkout hace lo mismo que Shoppi.checkout.start(). Los costes de pago siguen el plan de la tienda: comisiones de Stripe más la tarifa de aplicación Shoppi Pay del 0,4 % + 1 céntimo por pago. Los reembolsos, totales o parciales, online o en el TPV, también pasan por Stripe.

Cuentas de clientes — Shoppi.user

Cuentas para los clientes de la tienda, guardadas en su base de datos. Tras el login, el token de sesión queda en el navegador y viaja con cada petición del SDK en la cabecera X-User-Token.

Método Qué hace
Shoppi.user.register(email, password, firstName, lastName) Crea una cuenta e inicia sesión.
Shoppi.user.login(email, password) Inicia sesión.
Shoppi.user.getProfile() Perfil del cliente conectado (null si no ha iniciado sesión).
Shoppi.user.updateProfile(data) Actualiza campos del perfil, por ejemplo { phone }.
Shoppi.user.saveAddress(type, address) Guarda una dirección; type es por ejemplo 'shipping'.
Shoppi.user.logout() Cierra la sesión y recarga la página.

Las URL siguen el esquema /<language>/<page>, por ejemplo /it/contatti. Shoppi.router.navigate(slug, locale) carga una página sin recargar todo y la muestra en <main>; los enlaces con data-shoppi-link hacen lo mismo.

<a href="/it/contatti" data-shoppi-link="contatti">Contatti</a>

Shoppi.lang.load(locale) carga las traducciones de la tienda; Shoppi.lang.t(key, vars) devuelve un texto y sustituye los marcadores escritos como %_NAME%.

Directorio local — Shoppi.local

Método Devuelve
Shoppi.local.getCities() Ciudades disponibles en el directorio local.
Shoppi.local.getBusinesses(cityId, categoryId) Negocios de una ciudad, con filtro opcional por categoría.

Email — Shoppi.mailer

Envía un email transaccional desde la tienda, por ejemplo desde un formulario de contacto. Límite: 10 emails al día por dispositivo.

await Shoppi.mailer.send({
    to:      '[email protected]',
    subject: 'New request from the website',
    body:    '<p>Hello!</p>',
    replyTo: '[email protected]'   // optional
});

Shoppi.mailer.remaining();   // emails left today on this device

API JSON

Cada método del SDK es una llamada a la API JSON, que puedes usar directamente con Shoppi.call(endpoint, params, method) o con un simple fetch: el esquema es /api/<module>/<method>/json, en el dominio de la tienda.

Endpoint Para qué sirve
GET /api/website/info/json Perfil de la tienda
GET /api/website/section/<slug>/json Página de contenido
POST /api/checkout/createStripeSession/json Sesión de Stripe Checkout desde un carrito
POST /api/checkout/startDirect/json Compra directa de un producto
GET /api/checkout/createOnboardingLink/json Enlace de onboarding de Stripe
POST /api/frontend_user/register/json Registro de cliente
POST /api/frontend_user/login/json Login de cliente
GET /api/local/getCities/json Directorio local: ciudades 
const res  = await fetch('/api/website/info/json', { credentials: 'include' });
const data = await res.json();   // { "result": "ok", ... }  or  { "result": "ko", "feedback": "reason" }

Shoppi.call() devuelve la parte útil de una respuesta ok y lanza un Error con el mensaje feedback cuando la respuesta es ko.

TagCodes (lado servidor)

Los TagCodes son marcadores en las plantillas HTML de la tienda, resueltos en el servidor antes de enviar la página: el contenido está en el HTML que ven los buscadores.

TagCode Salida
{css} / {js} Hojas de estilo y scripts de la página y sus plugins
{page_title}, {page_description} Título y descripción SEO
{page_name}, {page_logo} Nombre y logo de la tienda
{locale}, {currency}, {country} Idioma, moneda y país del visitante
{title}, {content}, {photo}, {price}, {link} Campos del producto o artículo actual
{cfield:title}, {cfield:description}, {cfield:cover} Campos del perfil de la tienda
{cart:act=drawer} Carrito lateral
{search:nout=true} Búsqueda, inicializada sin salida por defecto
{cookieconsent} Banner de consentimiento de cookies
{offers:act=seo} Datos estructurados JSON-LD para productos

Dentro de un objeto JavaScript usa %_ID% para el id de la tienda: allí las llaves se leerían como TagCode.

Acceso a archivos y datos

Los archivos de cada tienda son accesibles por WebDAV (también con la app de escritorio Shoppi Go) y los datos siguen siendo exportables: plantillas HTML estándar, la base de datos de la tienda y la API JSON de arriba. Las credenciales están en el panel de cuenta de la tienda.

¿Dudas o un caso que no aparece aquí? Reserva una llamada con el equipo de partners, o vuelve al kit de partners.