Documentazione API

Gli esempi di codice sono in inglese, come i nomi dei metodi.

Come funziona

Ogni negozio su Shoppi Cloud si estende con lo Shoppi SDK, una libreria JavaScript servita dalla piattaforma su ogni dominio ospitato da Shoppi, e con i TagCode, segnaposto lato server che il motore delle pagine risolve prima che la pagina arrivi al browser. Entrambi parlano con la stessa API JSON, usabile anche direttamente.

• Nessuna chiave API nel browser. Il negozio si riconosce dal dominio da cui parte la richiesta: l'SDK funziona sul dominio del negozio senza segreti nel codice.
• I pagamenti passano da Stripe. Le sessioni di checkout nascono sull'account Stripe del merchant (Stripe Connect); Shoppi non tocca mai i soldi dei clienti del merchant. Anche i rimborsi passano tutti da Stripe.
• Due database. Il catalogo si legge dal database Shoppi, quello che il merchant gestisce dall'app; ogni dominio di negozio ha anche un database suo. Scegli tu da quale legge ogni API (vedi Catalogo). Gli account dei clienti stanno sempre nel database del dominio del negozio, separati dagli altri negozi.
• Versione attuale dell'SDK: 2.9.0. Le risposte hanno sempre la stessa forma: {"result": "ok" | "ko", "feedback": …}.

Installazione

Includi l'SDK una volta, nel <head> della pagina. Al caricamento crea l'oggetto globale 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
    sources:       "shoppi"  // catalog database: "shoppi" (default) or "local"
};
</script>
<script src="/shoppi/shoppi-sdk.js?v=2.9.0"></script>

Tutte le impostazioni sono facoltative: senza ShoppiConfig l'SDK riconosce il negozio dal dominio e usa l'euro. Aumenta il parametro ?v= quando vuoi che i browser scarichino un SDK più recente.

Negozio e contenuti — Shoppi.site

const info = await Shoppi.site.getInfo();
document.getElementById('store-name').textContent = info.title;

Catalogo — Shoppi.catalog

Prodotti, categorie, foto e ricerca: i dati che il merchant gestisce dall'app Shoppi, pronti per costruire una vetrina. Ogni articolo arriva nella stessa forma, qualunque sia il tipo:

{
  id: 9610389, type: 'products',          // products | services | files | offers
  slug: 'curtirisorisobasmati2×500g',
  title: 'Curtiriso Riso Basmati 2 × 500 g',
  description: '', content: 'Basmati',    // content may contain HTML
  price: 4.79, currency: 'EUR', price_format: '4,79 €',
  photo: 'https://storage.shoppi.app/…', photo_hires: '…', photos: ['…'],
  quantity: 5, in_stock: true, ship_cost: 0, code: 'CX-DIS-000001',
  category: 'Dispensa', keywords: ['dispensa'], link: '…', date: 1791312283
}

const page = await Shoppi.catalog.products({ limit: 12 });
const cats = await Shoppi.catalog.categories();           // [{ id: 600, slug: 'dispensa', title: 'Dispensa' }, …]
const food = await Shoppi.catalog.products({ category: 'dispensa' });
const one  = await Shoppi.catalog.product(9610389);       // or by slug
const hits = await Shoppi.catalog.search('riso');         // { items, count, suggestions }

Quale database: per API, per chiamata

'shoppi' (predefinito) legge il database Shoppi, dove il merchant gestisce i prodotti dall'app. 'local' legge il database del dominio del negozio, vuoto finché non ci scrivi. Scegli per API in ShoppiConfig.sources, a runtime con Shoppi.catalog.use() o per una sola chiamata con { source }. Una sorgente può anche essere l'URL base di un altro host o una funzione che restituisce dati tuoi. Carrello, checkout, account clienti ed email girano sempre sul dominio del negozio.

window.ShoppiConfig = {
    pageId:  "%_ID%",
    sources: { products: 'shoppi', categories: 'local' }   // or one value: 'local'
};

Shoppi.catalog.use('search', 'local');                          // at runtime, one API
await Shoppi.catalog.products({ limit: 12 }, { source: 'local' }); // for one call

Rendering ed eventi

Shoppi.render(target, items, template) riempie un elemento con una lista: il template è una funzione, una stringa Handlebars, oppure niente per la scheda integrata con il pulsante aggiungi al carrello. Gli elementi con data-shoppi-list si riempiono da soli al caricamento della pagina; gli altri attributi data-shoppi-* sono le opzioni del metodo corrispondente. Eventi su document: shoppi:cart:added, shoppi:cart:updated, shoppi:checkout:started, shoppi:rendered.

const r = await Shoppi.catalog.products({ limit: 12 });
Shoppi.render('grid', r);                       // built-in card with add-to-cart button
Shoppi.render('grid', r, p => `<h3>${p.title}</h3><p>${p.price_format}</p>`);

<div data-shoppi-list="products" data-shoppi-limit="12" data-shoppi-category="dispensa">
  <template><div class="card"><img src="{{photo}}"><h3>{{title}}</h3>
    <button data-shoppi-add="{{id}}" data-shoppi-price="{{price}}"
            data-shoppi-title="{{title}}" data-shoppi-image="{{photo}}">Add</button></div></template>
</div>

document.addEventListener('shoppi:cart:added', e => console.log(e.detail.title));

Carrello — Shoppi.cart

Il carrello vive nel browser (localStorage) e resta dopo il ricaricamento. Prezzi e titoli che passi arrivano fino al checkout, quindi impostali sempre.

Senza JavaScript, con gli attributi 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

document.querySelector('#buy').addEventListener('click', () => Shoppi.checkout.start());

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

Ogni pulsante con data-shoppi-checkout fa la stessa cosa di Shoppi.checkout.start(). I costi dei pagamenti seguono il piano del negozio: commissioni Stripe più l'app fee Shoppi Pay dello 0,4% + 1 centesimo per pagamento. Anche i rimborsi, totali o parziali, online o al POS, passano da Stripe.

Account clienti — Shoppi.user

Account per i clienti del negozio, salvati nel database del negozio. Dopo il login il token di sessione resta nel browser e viaggia con ogni richiesta dell'SDK nell'header X-User-Token. Gli account sono legati al dominio del negozio: due negozi non vedono mai i clienti l'uno dell'altro.

Navigazione e traduzioni — Shoppi.router, Shoppi.lang

Gli URL seguono lo schema /<language>/<page>, per esempio /it/contatti. Shoppi.router.navigate(slug, locale) carica una pagina senza ricaricare tutto e la mostra in <main>; i link con data-shoppi-link fanno lo stesso.

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

Shoppi.lang.load(locale) carica le traduzioni del negozio; Shoppi.lang.t(key, vars) restituisce una stringa e sostituisce i segnaposto scritti come %_NAME%.

Directory locale — Shoppi.local

Email — Shoppi.mailer

Invia un'email transazionale dal negozio, per esempio da un modulo di contatto. Limite: 10 email al giorno per 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

Ogni metodo dell'SDK è una chiamata all'API JSON, che puoi usare direttamente con Shoppi.call(endpoint, params, method) o con un semplice fetch: lo schema è /api/<module>/<method>/json, sul dominio del negozio.

const res  = await fetch('/api/website/info/json', { credentials: 'include' });
const data = await res.json();   // { "result": "ok", ... }  or  { "result": "ko", "feedback": "reason" }

Gli endpoint del catalogo rispondono sul dominio del negozio (il suo database) e su https://shoppi.app (il database Shoppi). Per la sorgente 'shoppi' l'SDK chiama shoppi.app con l'id del negozio: un id che non appartiene al dominio chiamante viene rifiutato. Shoppi.call(endpoint, params, method, { base }) sceglie l'host.

Shoppi.call() restituisce la parte utile di una risposta ok e lancia un Error con il messaggio feedback quando la risposta è ko.

TagCode (lato server)

I TagCode sono segnaposto nei template HTML del negozio, risolti sul server prima di inviare la pagina: il contenuto sta nell'HTML che vedono i motori di ricerca.

Dentro un oggetto JavaScript usa %_ID% per l'id del negozio: lì le graffe verrebbero lette come TagCode.

Accesso a file e dati

I file di ogni negozio sono raggiungibili via WebDAV (anche con l'app desktop Shoppi Go) e i dati restano esportabili: template HTML standard, il database del negozio e l'API JSON qui sopra. Le credenziali di accesso sono nel pannello account del negozio.