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.
GET /openapi/v1.jsonSchnellstart
Drei Schritte zu deinem ersten Katalog-Lesezugriff:
- Erstelle im Admin (Bereich Entwickler) einen API-Schlüssel mit den benötigten Read-Scopes. Er beginnt mit vbk_ und wird nur einmal angezeigt.
- Sende ihn bei jeder Anfrage im Header X-Api-Key — dein Tenant wird aus dem Schlüssel aufgelöst, nie aus dem Host.
- 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:readPagination
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.