# Introductie

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:

```
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}`:

| Module | Mount 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](./errors-and-rate-limits) voor de volledige errorcatalogus.

## Authenticatie in één regel

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

```
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](./authentication).

## 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](./errors-and-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.

```bash title="Request"
curl https://api.borkol.com/v1/ping
```

```json title="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.

```bash title="Request"
curl https://api.borkol.com/v1/api/me \
  -H "Authorization: Bearer {api_key}"
```

```json title="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.

```bash title="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](./authentication): API keys, scopes, het `/v1/api/me` endpoint en tenant-suspensie.
- [Errors en rate limits](./errors-and-rate-limits): elke error-envelope, de vorm van de 422-validatiefout, rate limiting en de paginatie-envelope.
- [Webhooks](/nl/webhooks/index): event-gedreven notificaties voor bestellingen en voorraadwijzigingen.