Partner-Kit

API-Dokumentation

Das Shoppi SDK, die JSON-API und TagCodes: alles, was ein Partner braucht, um auf einem Shoppi-Shop aufzubauen.

SDK 2.7.5 JSON API Stripe Checkout TagCodes
So funktioniert esEinrichtungShop und Inhalte — Shoppi.siteWarenkorb — Shoppi.cartCheckout — Shoppi.checkoutKundenkonten — Shoppi.userNavigation und Übersetzungen — Shoppi.router, Shoppi.langLokales Verzeichnis — Shoppi.localE-Mail — Shoppi.mailerJSON-APITagCodes (serverseitig)Zugriff auf Dateien und Daten

Die Codebeispiele sind auf Englisch, wie die Methodennamen.

So funktioniert es

Jeder Shop auf Shoppi Cloud lässt sich mit dem Shoppi SDK erweitern, einer JavaScript-Bibliothek, die die Plattform auf jeder von Shoppi gehosteten Domain bereitstellt, und mit TagCodes, serverseitigen Platzhaltern, die die Seiten-Engine auflöst, bevor die Seite den Browser erreicht. Beide sprechen mit derselben JSON-API, die auch direkt nutzbar ist.

  • Keine API-Schlüssel im Browser. Der Shop wird an der Domain erkannt, von der die Anfrage kommt: Das SDK funktioniert auf der Shop-Domain ohne Geheimnisse im Code.
  • Zahlungen laufen über Stripe. Checkout-Sitzungen entstehen auf dem eigenen Stripe-Konto des Händlers (Stripe Connect); Shoppi hält nie das Geld der Kunden des Händlers. Auch Erstattungen laufen vollständig über Stripe.
  • Jeder Shop hat seine eigene Datenbank. Über das SDK registrierte Kunden liegen in der Datenbank des Shops, getrennt von anderen Shops.
  • Aktuelle SDK-Version: 2.7.5. Antworten haben immer dieselbe Form: {"result": "ok" | "ko", "feedback": …}.

Einrichtung

Binden Sie das SDK einmal im <head> der Seite ein. Beim Laden entsteht das globale Objekt 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>

Alle Einstellungen sind optional: Ohne ShoppiConfig erkennt das SDK den Shop an der Domain und nutzt EUR. Erhöhen Sie den Parameter ?v=, damit Browser ein neueres SDK laden.

Shop und Inhalte — Shoppi.site

Methode Rückgabe
Shoppi.site.getInfo() Shopprofil: Name, Logo, Beschreibung.
Shoppi.site.getPage(slug) Eine Inhaltsseite über ihren Slug, z. B. 'about-us'. Liefert Titel und HTML-Inhalt. 
const info = await Shoppi.site.getInfo();
document.getElementById('store-name').textContent = info.title;

Warenkorb — Shoppi.cart

Der Warenkorb liegt im Browser (localStorage) und übersteht ein Neuladen. Übergebene Preise und Titel gehen bis zum Checkout, setzen Sie sie also immer.

Aufruf Funktion
Shoppi.cart.add(id, qty, { price, title, image }) Fügt ein Produkt hinzu (Menge standardmäßig 1).
Shoppi.cart.updateQty(id, qty) Setzt die Menge; 0 entfernt die Zeile.
Shoppi.cart.remove(id) Entfernt eine Zeile.
Shoppi.cart.clear() Leert den Warenkorb.
Shoppi.cart.setCountry(code) Setzt das Versandland (ISO-Code, z. B. 'IT').
Shoppi.cart.data Aktueller Stand: { items, count, total, country }.

Ohne JavaScript, mit HTML-Attributen:

<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

Methode Funktion
Shoppi.checkout.start() Erstellt eine Stripe-Checkout-Sitzung für den Warenkorb auf dem Stripe-Konto des Händlers und leitet den Kunden dorthin.
Shoppi.checkout.startDirect(productId, metadata) Kauf eines einzelnen Produkts mit einem Klick, ohne Warenkorb (Dienstleistungen, Buchungen, Downloads).
Shoppi.checkout.createOnboardingLink() Liefert den Stripe-Onboarding-Link des Shops, um sein Stripe-Konto zu verbinden oder zu vervollständigen. 
document.querySelector('#buy').addEventListener('click', () => Shoppi.checkout.start());

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

Jeder Button mit data-shoppi-checkout macht dasselbe wie Shoppi.checkout.start(). Die Zahlungskosten richten sich nach dem Tarif des Shops: Stripe-Gebühren plus die Shoppi-Pay-App-Gebühr von 0,4 % + 1 Cent pro Zahlung. Auch Erstattungen, ganz oder teilweise, online oder an der Kasse, laufen über Stripe.

Kundenkonten — Shoppi.user

Konten für die Kunden des Shops, gespeichert in der Datenbank des Shops. Nach dem Login bleibt das Sitzungstoken im Browser und wird mit jeder SDK-Anfrage im Header X-User-Token gesendet.

Methode Funktion
Shoppi.user.register(email, password, firstName, lastName) Legt ein Konto an und meldet an.
Shoppi.user.login(email, password) Meldet an.
Shoppi.user.getProfile() Profil des angemeldeten Kunden (null, wenn abgemeldet).
Shoppi.user.updateProfile(data) Aktualisiert Profilfelder, z. B. { phone }.
Shoppi.user.saveAddress(type, address) Speichert eine Adresse; type ist z. B. 'shipping'.
Shoppi.user.logout() Beendet die Sitzung und lädt die Seite neu.

URLs folgen dem Muster /<language>/<page>, z. B. /it/contatti. Shoppi.router.navigate(slug, locale) lädt eine Seite ohne komplettes Neuladen und zeigt sie in <main>; Links mit data-shoppi-link tun dasselbe.

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

Shoppi.lang.load(locale) lädt die Übersetzungen des Shops; Shoppi.lang.t(key, vars) liefert einen Text und ersetzt Platzhalter der Form %_NAME%.

Lokales Verzeichnis — Shoppi.local

Methode Rückgabe
Shoppi.local.getCities() Im lokalen Verzeichnis verfügbare Städte.
Shoppi.local.getBusinesses(cityId, categoryId) Betriebe einer Stadt, optional nach Kategorie gefiltert.

E-Mail — Shoppi.mailer

Sendet eine Transaktions-E-Mail aus dem Shop, z. B. aus einem Kontaktformular. Begrenzt auf 10 E-Mails pro Tag und Gerät.

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

JSON-API

Jede SDK-Methode ist ein Aufruf der JSON-API, die Sie direkt mit Shoppi.call(endpoint, params, method) oder einfachem fetch nutzen können: Das Muster ist /api/<module>/<method>/json, auf der Domain des Shops.

Endpunkt Zweck
GET /api/website/info/json Shopprofil
GET /api/website/section/<slug>/json Inhaltsseite
POST /api/checkout/createStripeSession/json Stripe-Checkout-Sitzung aus einem Warenkorb
POST /api/checkout/startDirect/json Direktkauf eines Produkts
GET /api/checkout/createOnboardingLink/json Stripe-Onboarding-Link
POST /api/frontend_user/register/json Kundenregistrierung
POST /api/frontend_user/login/json Kundenlogin
GET /api/local/getCities/json Lokales Verzeichnis: Städte 
const res  = await fetch('/api/website/info/json', { credentials: 'include' });
const data = await res.json();   // { "result": "ok", ... }  or  { "result": "ko", "feedback": "reason" }

Shoppi.call() liefert den nützlichen Teil einer ok-Antwort und wirft bei ko einen Error mit der feedback-Meldung.

TagCodes (serverseitig)

TagCodes sind Platzhalter in den HTML-Templates des Shops, die auf dem Server aufgelöst werden, bevor die Seite gesendet wird: Der Inhalt steht im HTML, das Suchmaschinen sehen.

TagCode Ausgabe
{css} / {js} Stylesheets und Skripte der Seite und ihrer Plugins
{page_title}, {page_description} SEO-Titel und -Beschreibung
{page_name}, {page_logo} Shopname und Logo
{locale}, {currency}, {country} Aktive Sprache, Währung, Land des Besuchers
{title}, {content}, {photo}, {price}, {link} Felder des aktuellen Produkts oder Artikels
{cfield:title}, {cfield:description}, {cfield:cover} Felder des Shopprofils
{cart:act=drawer} Seitlicher Warenkorb
{search:nout=true} Suche, ohne Standardausgabe initialisiert
{cookieconsent} Cookie-Einwilligungsbanner
{offers:act=seo} Strukturierte JSON-LD-Daten für Produkte

Innerhalb eines JavaScript-Objekts verwenden Sie %_ID% für die Shop-ID: Geschweifte Klammern würden dort als TagCode gelesen.

Zugriff auf Dateien und Daten

Die Dateien jedes Shops sind per WebDAV erreichbar (auch über die Desktop-App Shoppi Go), und die Daten bleiben exportierbar: Standard-HTML-Templates, die eigene Datenbank des Shops und die JSON-API oben. Die Zugangsdaten stehen im Kontobereich des Shops.

Fragen oder ein Fall, der hier fehlt? Termin buchen mit dem Partnerteam, oder zurück zum Partner-Kit.