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.
GET /openapi/v1.jsonSnelstart
Drie stappen naar je eerste cataloguslezing:
- 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.
- Stuur ze mee in de header X-Api-Key bij elk verzoek — je tenant wordt uit de sleutel afgeleid, nooit uit de host.
- 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:readPaginering
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.