Borkol Docs startpagina

Aan de slag

Introductie

Wat de Borkol storefront-API is, de base URL en versionering, en een quickstart in drie stappen.

Bekijk als Markdown

De Borkol storefront-API is de publieke HTTP-API van het Borkol-commerceplatform. Hij geeft je programmatische lees- en schrijftoegang tot één winkel (een tenant): de productcatalogus, voorraadniveaus, klanten, bestellingen en custom objects. Je gebruikt hem om custom storefronts, headless frontends, mobiele apps en server-side integraties tegen een Borkol-winkel te bouwen.

De API is een conventionele JSON-over-HTTPS-API. Elke request body en response body is JSON. Authenticatie gebeurt met een tenant-API-key die als bearer token wordt meegestuurd. Er zijn geen cookies, geen sessies en geen OAuth-flows op de storefront-API.

Base URL

Alle requests gaan naar:

text
https://api.borkol.com

De API is geversioneerd in het URL-pad. De huidige en enige versie is v1, dus elke route in deze documentatie begint met /v1. Geauthenticeerde storefront-routes leven onder /v1/api/...; de enige ongeauthenticeerde route is de health check op /v1/ping.

Module-surfaces worden gemount onder /v1/api/{module}:

ModuleMount point
Commerce/v1/api/commerce (plus /v1/api/commerce/configurator)
Stock/v1/api/stock
Customers/v1/api/customers
Objects/v1/api/objects
Forms/v1/api/forms

Een module-surface is alleen bereikbaar wanneer die module voor jouw winkel is ingeschakeld. Het aanroepen van een route van een uitgeschakelde module geeft 403 {"error": "Module not enabled: {key}"} terug. Zie Errors en rate limits voor de volledige errorcatalogus.

Authenticatie in één regel

Elke /v1/api-request stuurt een tenant-API-key mee als bearer token:

text
Authorization: Bearer {api_key}

De key identificeert de winkel, dus een aparte tenant-header is niet nodig. Merchants maken keys aan in het client-dashboard (app.borkol.com) onder Settings > API keys. Elke key draagt een set scopes (bijvoorbeeld commerce:read) die bepalen welke endpoints hij mag aanroepen. Alle details staan op de pagina Authenticatie.

Conventies

Deze gelden voor de hele API:

  • Resource-ID's zijn UUID-strings (API-key-ID's, die alleen voorkomen in de merchant-dashboardflow, zijn integers).
  • Geldbedragen zijn integers in minor units (centen) met een apart ISO 4217 currency-veld. 15900 met "currency": "EUR" betekent EUR 159.00.
  • Timestamps zijn ISO 8601-strings.
  • Lijst-endpoints gebruiken de paginatie-envelope die eenmalig gedocumenteerd is in Errors en rate limits. De basis-endpoints op deze pagina's (/v1/ping, /v1/api/me) geven kale JSON-objecten terug zonder wrapper.

Quickstart

Drie requests brengen je van niets naar je eerste catalogusaanroep.

Stap 1: controleer de connectiviteit. /v1/ping heeft geen credentials nodig en bevestigt dat de base URL en API-versie bereikbaar zijn.

Request
curl https://api.borkol.com/v1/ping
Response
{
  "status": "ok",
  "version": "v1"
}

Stap 2: controleer je API-key. Maak in het client-dashboard (Settings > API keys) een key aan met minimaal de scope commerce:read en roep daarna /v1/api/me aan. Dat geeft de winkel terug waar de key bij hoort en de scopes die de key draagt. Dit endpoint vereist geen scope, alleen een geldige key.

Request
curl https://api.borkol.com/v1/api/me \
  -H "Authorization: Bearer {api_key}"
Response
{
  "tenant": {
    "id": "9c4e7f0a-2b31-4d6e-8f0a-1d2c3b4a5e6f",
    "name": "Example Store",
    "slug": "example-store"
  },
  "scopes": ["tenant:read", "commerce:read"]
}

Stap 3: haal de catalogus op. Vraag met een key die commerce:read draagt de productlijst van de commerce-module op. Deze request faalt met 403 {"error": "Module not enabled: commerce"} als de commerce-module niet is ingeschakeld voor de winkel, en met 403 {"message": "Invalid ability provided."} als de key de scope commerce:read mist.

Request
curl https://api.borkol.com/v1/api/commerce/products \
  -H "Authorization: Bearer {api_key}"

De response is een gepagineerde productlijst; de product-endpoints zijn gedocumenteerd in het hoofdstuk Commerce.

Waar nu naartoe

  • Authenticatie: API keys, scopes, het /v1/api/me endpoint en tenant-suspensie.
  • Errors en rate limits: elke error-envelope, de vorm van de 422-validatiefout, rate limiting en de paginatie-envelope.
  • Webhooks: event-gedreven notificaties voor bestellingen en voorraadwijzigingen.