Zum Hauptinhalt springen

Entwickler

Merchant-API

Eine read-only REST-API für deinen VeeBoost-Shop: ein publizierter Vertrag, schlüsselbasierte Authentifizierung und vorhersagbare Pagination — gebaut für Integrationen, die synchron bleiben.

Ein Vertrag, publiziert als single source of truth

Dein Shop publiziert den vollständigen maschinenlesbaren Vertrag (OpenAPI 3.1): jeden Endpoint, jeden Parameter, jede Response und jeden Fehlercode der Merchant-API. Diese Seite verlinkt ihn und wiederholt nie die Endpoint-Tabellen — der Vertrag kann nicht abweichen, deine Integration ebenso wenig.

Publizierter VertragGET /openapi/v1.json

Schnellstart

Drei Schritte zu deinem ersten Katalog-Lesezugriff:

  1. Erstelle im Admin (Bereich Entwickler) einen API-Schlüssel mit den benötigten Read-Scopes. Er beginnt mit vbk_ und wird nur einmal angezeigt.
  2. Sende ihn bei jeder Anfrage im Header X-Api-Key — dein Tenant wird aus dem Schlüssel aufgelöst, nie aus dem Host.
  3. Rufe deinen ersten Endpoint auf, zum Beispiel GET /products, und folge danach für alles Weitere dem Vertrag.

Authentifizierung

Jede Anfrage trägt deinen Schlüssel im Header X-Api-Key. v1 liefert genau vier Read-Scopes — Produkte, Bestellungen, Kunden und Webhook-Zustellungen. Ein fehlender Scope antwortet mit 403, ein wiederrufener Schlüssel wird sofort abgelehnt. Bewahre Schlüssel serverseitig auf: Sie gehören nie in einen Browser oder ein öffentliches Repository.

products:readorders:readcustomers:readwebhooks:read

Pagination

Listen-Endpoints paginieren: durchlaufe sie mit dem Parameter page und lies das Envelope, das mit jeder Collection zurückkommt — es zeigt, wo du stehst, damit deine Integration ohne Raten resynchronisieren kann. Die genauen Parameter jedes Endpoints stehen im Vertrag.

Fehler und Rate-Limits

Fehler liefern einen strukturierten JSON-Body, den du parsen kannst — nie einen Absatz zum Screen-Scraping. Eine 429-Antwort ist ein stabiler Vertrag: jedes Mal dieselbe Body-Form, mit den Headern X-RateLimit-* und einem Retry-After, der genau sagt, wann du zurückkommen sollst. Druck erhöhen schaltet keine Daten frei — geh zurück und wartee ab.

Sandbox-Schlüssel

Während der Pre-Launch-Phase werden Sandbox-Schlüssel nach Validierung durch unser Team ausgegeben und laufen mit einem dedizierten Rate-Limit-Budget, getrennt von Produktionsschlüsseln — erkunde die API auf deinem Shop, ohne Live-Traffic oder Quotas zu berühren.

Beispiele je Sprache

Ein Snippet pro Plattform, nur Read-Scopes: jedes holt deinen Produktkatalog. Ersetze <api-base> durch den API-Host deines Shops aus dem Admin → Bereich Entwickler.

curl

curl -H "X-Api-Key: vbk_your_key" \
  "https://<api-base>/products?page=1"

JavaScript

async function listProducts(page = 1) {
  const res = await fetch("https://<api-base>/products?page=" + page, {
    headers: { "X-Api-Key": "vbk_your_key" },
  });
  if (res.status === 429) {
    // Structured contract: honor Retry-After, never screen-scrape.
    const wait = Number(res.headers.get("Retry-After")) * 1000;
    await new Promise((done) => setTimeout(done, wait));
    return listProducts(page);
  }
  if (!res.ok) throw new Error("products:read failed with " + res.status);
  return res.json();
}

Python

import requests

def list_products(page=1):
    res = requests.get(
        "https://<api-base>/products",
        params={"page": page},
        headers={"X-Api-Key": "vbk_your_key"},
        timeout=10,
    )
    res.raise_for_status()
    return res.json()

v1 ist bewusst read-only: products:read, orders:read, customers:read und webhooks:read sind die einzigen existierenden Scopes. Write-Scopes wären eine explizit dokumentierte v1.x-Entscheidung — nichts wird stillschweigend geplant.