Naar de hoofdinhoud springen

Ontwikkelaars

Merchant-API

Een read-only REST-API voor je VeeBoost-winkel: één gepubliceerd contract, sleutelgebaseerde authenticatie en voorspelbare paginering — gebouwd voor integraties die synchroon blijven.

Eén contract, gepubliceerd als de enige bron van waarheid

Je winkel publiceert het volledige machineleesbare contract (OpenAPI 3.1): elk endpoint, elke parameter, respons en foutcode van de merchant-API. Deze pagina ernaar linkt en herhaalt nooit endpointtabellen — het contract kan niet afdrijven, en jouw integratie evenmin.

Gepubliceerd contractGET /openapi/v1.json

Snelstart

Drie stappen naar je eerste cataloguslezing:

  1. Maak een API-sleutel in je admin (sectie Ontwikkelaars) met de leesscopes die je nodig hebt. Ze begint met vbk_ en wordt maar één keer getoond.
  2. Stuur ze mee in de header X-Api-Key bij elk verzoek — je tenant wordt uit de sleutel afgeleid, nooit uit de host.
  3. Roep je eerste endpoint aan, bijvoorbeeld GET /products, en volg daarna voor alles het contract.

Authenticatie

Elk verzoek draagt je sleutel in de header X-Api-Key. v1 biedt exact vier leesscopes — producten, bestellingen, klanten en webhook-bezorgingen. Een ontbrekende scope antwoordt met 403; een ingetrokken sleutel wordt direct geweigerd. Bewaar sleutels server-side: ze horen nooit in een browser of een publieke repository.

products:readorders:readcustomers:readwebhooks:read

Paginering

Lijstendpoints pagineren: doorloop ze met de parameter page en lees de envelop die bij elke collectie terugkomt — die toont waar je zit, zodat je integratie kan hersynchroniseren zonder gokken. De exacte parameters per endpoint staan in het contract.

Fouten en rate-limieten

Fouten geven een gestructureerde JSON-body die je kunt parsen, nooit een alinea om te schrapen. Een 429-respons is een stabiel contract: elke keer dezelfde vorm, met de headers X-RateLimit-* en een Retry-After die precies zegt wanneer je terugkomt. Forceren ontgrendelt geen data — ga in backoff.

Sandbox-sleutels

Tijdens de pre-launchfase worden sandbox-sleutels uitgegeven na validatie door ons team en draaien ze met een eigen rate-limitbudget, gescheiden van productiesleutels — verken de API op je winkel zonder live verkeer of quota te raken.

Voorbeelden per taal

Eén snippet per platform, alleen leesscopes: elk haalt je productcatalogus op. Vervang <api-base> door de API-host van je winkel uit de admin → sectie Ontwikkelaars.

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 is bewust read-only: products:read, orders:read, customers:read en webhooks:read zijn de enige bestaande scopes. Schrijscopes zouden een expliciet gedocumenteerde v1.x-beslissing zijn — niets wordt in stilte gepland.