Kit partner

Documentazione API

Lo Shoppi SDK, l'API JSON e i TagCode: tutto quello che serve a un partner per costruire su un negozio Shoppi.

SDK 2.7.5 JSON API Stripe Checkout TagCodes

Come funziona Installazione Negozio e contenuti — Shoppi.site Carrello — Shoppi.cart Checkout — Shoppi.checkout Account clienti — Shoppi.user Navigazione e traduzioni — Shoppi.router, Shoppi.lang Directory locale — Shoppi.local Email — Shoppi.mailer API JSON TagCode (lato server)Accesso a file e dati

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.
Ogni negozio ha il suo database. I clienti registrati tramite l'SDK stanno nel database del negozio, separati dagli altri negozi.
Versione attuale dell'SDK: 2.7.5. 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
};
</script>
<script src="/shoppi/shoppi-sdk.js?v=2.7.5"></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

Metodo	Restituisce
`Shoppi.site.getInfo()`	Profilo del negozio: nome, logo, descrizione.
`Shoppi.site.getPage(slug)`	Una pagina di contenuto dal suo slug, per esempio `'about-us'`. Restituisce titolo e contenuto HTML.

const info = await Shoppi.site.getInfo();
document.getElementById('store-name').textContent = info.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.

Chiamata	Cosa fa
`Shoppi.cart.add(id, qty, { price, title, image })`	Aggiunge un prodotto (quantità predefinita 1).
`Shoppi.cart.updateQty(id, qty)`	Imposta la quantità; 0 toglie la riga.
`Shoppi.cart.remove(id)`	Toglie una riga.
`Shoppi.cart.clear()`	Svuota il carrello.
`Shoppi.cart.setCountry(code)`	Imposta il paese di spedizione (codice ISO, per esempio `'IT'`).
`Shoppi.cart.data`	Stato attuale: `{ items, count, total, country }`.

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

Metodo	Cosa fa
`Shoppi.checkout.start()`	Crea una sessione Stripe Checkout per il carrello sull'account Stripe del merchant e ci porta il cliente.
`Shoppi.checkout.startDirect(productId, metadata)`	Acquisto in un clic di un solo prodotto, senza carrello (servizi, prenotazioni, download).
`Shoppi.checkout.createOnboardingLink()`	Restituisce il link di onboarding Stripe del negozio, per collegare o completare il suo account Stripe.

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.

Metodo	Cosa fa
`Shoppi.user.register(email, password, firstName, lastName)`	Crea un account ed esegue il login.
`Shoppi.user.login(email, password)`	Esegue il login.
`Shoppi.user.getProfile()`	Profilo del cliente collegato (null se non è collegato).
`Shoppi.user.updateProfile(data)`	Aggiorna i campi del profilo, per esempio `{ phone }`.
`Shoppi.user.saveAddress(type, address)`	Salva un indirizzo; `type` è per esempio `'shipping'`.
`Shoppi.user.logout()`	Chiude la sessione e ricarica la pagina.

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

Metodo	Restituisce
`Shoppi.local.getCities()`	Città disponibili nella directory locale.
`Shoppi.local.getBusinesses(cityId, categoryId)`	Attività di una città, con filtro facoltativo per categoria.

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.

Endpoint	A cosa serve
`GET /api/website/info/json`	Profilo del negozio
`GET /api/website/section/<slug>/json`	Pagina di contenuto
`POST /api/checkout/createStripeSession/json`	Sessione Stripe Checkout da un carrello
`POST /api/checkout/startDirect/json`	Acquisto diretto di un prodotto
`GET /api/checkout/createOnboardingLink/json`	Link di onboarding Stripe
`POST /api/frontend_user/register/json`	Registrazione cliente
`POST /api/frontend_user/login/json`	Login cliente
`GET /api/local/getCities/json`	Directory locale: città

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

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.

TagCode	Output
`{css}` / `{js}`	Fogli di stile e script della pagina e dei suoi plugin
`{page_title}`, `{page_description}`	Titolo e descrizione SEO
`{page_name}`, `{page_logo}`	Nome e logo del negozio
`{locale}`, `{currency}`, `{country}`	Lingua, valuta e paese del visitatore
`{title}`, `{content}`, `{photo}`, `{price}`, `{link}`	Campi del prodotto o dell'articolo corrente
`{cfield:title}`, `{cfield:description}`, `{cfield:cover}`	Campi del profilo del negozio
`{cart:act=drawer}`	Carrello a scomparsa laterale
`{search:nout=true}`	Ricerca, inizializzata senza output predefinito
`{cookieconsent}`	Banner del consenso cookie
`{offers:act=seo}`	Dati strutturati JSON-LD per i prodotti

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.

Domande o un caso che qui non trovi? Prenota una call con il team partner, oppure torna al kit partner.

Soluzioni

Sistema POS Integrato

Fatto per ogni attività

Shoppi a confronto