# Beschikbaarheid

De Voorraad-module stelt read-only beschikbaarheid van Commerce-producten beschikbaar: een batch-endpoint voor overzichtspagina's en een endpoint voor één product dat kan inzoomen op één variant. Beide routes leven onder `/v1/api/stock`, vereisen de scope `stock:read` op je API-key, en vereisen dat de `stock`-module voor je winkel is ingeschakeld (anders `403 {"error":"Module not enabled: stock"}`).

## Het availability-object

| Veld | Type | Beschrijving |
| --- | --- | --- |
| `product_id` | string (uuid) | Het Commerce-product-id. |
| `variant_id` | string (uuid) or null | Alleen op het endpoint voor één product. Echoot de queryparameter `variant_id`; `null` wanneer weggelaten. |
| `tracked` | boolean | `false` wanneer `stock_status` `untracked` is, anders `true`. |
| `available` | number or null | Som van `quantity - reserved` over de actieve voorraadlocaties van de winkel, in de `unit` van het product. Een JSON-getal dat decimalen kan hebben voor producten die per gewicht, lengte, oppervlakte of volume verkocht worden (bijvoorbeeld `47.84`). `null` wanneer untracked. |
| `stock_status` | string | Eén van `untracked`, `in_stock`, `low_stock`, `out_of_stock`, `backorder`. |

`stock_status` wordt als volgt afgeleid:

- Het product heeft `track_stock` op `false` (dat geldt voor al zijn varianten), of er bestaan geen voorraadrijen voor het product (of de variant) op een actieve locatie: `untracked`.
- `available` is 0 of lager: `backorder` als een voorraadrij backorders toestaat, anders `out_of_stock`.
- Een voorraadrij zit op of onder zijn lage-voorraaddrempel: `low_stock`.
- Anders: `in_stock`.

## GET /v1/api/stock/availability

Batch-beschikbaarheid op productniveau voor maximaal 100 producten in één request. De response bevat één entry per bekend product-id; onbekende id's worden stilzwijgend weggelaten (het endpoint retourneert nooit een 404 voor een onbekend id in de batch). Dit endpoint werkt alleen op productniveau en heeft geen variantkeys; gebruik het endpoint voor één product voor beschikbaarheid per variant.

### Query-parameters

| Naam | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- |
| `ids` | array of string (uuid) | Ja | Product-id's, verstuurd als herhaalde `ids[]=...`-parameters. Maximaal 100 entries; elke entry moet een UUID zijn. |

```bash title="Request"
curl --globoff "https://api.borkol.com/v1/api/stock/availability?ids[]=7c1f4b2e-9a3d-4e5f-8b6c-0d1e2f3a4b5c&ids[]=8d2e5c3f-0b4e-4f6a-9c7d-1e2f3a4b5c6d" \
  -H "Authorization: Bearer {api_key}"
```

```javascript title="Request (JS)"
const params = new URLSearchParams();
for (const id of productIds) params.append("ids[]", id);
const res = await fetch(
  `https://api.borkol.com/v1/api/stock/availability?${params}`,
  { headers: { Authorization: `Bearer ${apiKey}` } },
);
const { data } = await res.json();
```

Status: `200 OK`.

```json title="Response"
{
  "data": [
    {
      "product_id": "7c1f4b2e-9a3d-4e5f-8b6c-0d1e2f3a4b5c",
      "tracked": true,
      "available": 42,
      "stock_status": "in_stock"
    },
    {
      "product_id": "8d2e5c3f-0b4e-4f6a-9c7d-1e2f3a4b5c6d",
      "tracked": false,
      "available": null,
      "stock_status": "untracked"
    }
  ]
}
```

### Fouten

- `422` wanneer `ids` ontbreekt, meer dan 100 entries bevat, of een entry geen UUID is. Fouten per entry verschijnen onder gekeyde foutvelden, bijvoorbeeld `errors["ids.0"]`.
- `403` `{"error":"Module not enabled: stock"}` wanneer de Voorraad-module is uitgeschakeld.
- `403` `{"message":"Invalid ability provided."}` wanneer de API-key de scope `stock:read` mist.

## GET /v1/api/stock/products/{productId}

Beschikbaarheid voor één product, optioneel beperkt tot één variant. Wanneer `variant_id` is meegegeven, weerspiegelt de response alleen de voorraadrijen van die variant.

### Path-parameters

| Naam | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- |
| `productId` | string (uuid) | Ja | Een Commerce-product-id. |

### Query-parameters

| Naam | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- |
| `variant_id` | string (uuid) | Nee | Beperk de berekening tot de voorraadrijen van deze variant. Wordt geëchood in de response; `null` wanneer weggelaten. Een onbekende `variant_id` geeft geen 404; die rapporteert gewoon `untracked`. |

```bash title="Request"
curl "https://api.borkol.com/v1/api/stock/products/7c1f4b2e-9a3d-4e5f-8b6c-0d1e2f3a4b5c?variant_id=3a4b5c6d-7e8f-4a1b-9c2d-0e1f2a3b4c5d" \
  -H "Authorization: Bearer {api_key}"
```

Status: `200 OK`.

```json title="Response"
{
  "data": {
    "product_id": "7c1f4b2e-9a3d-4e5f-8b6c-0d1e2f3a4b5c",
    "variant_id": "3a4b5c6d-7e8f-4a1b-9c2d-0e1f2a3b4c5d",
    "tracked": true,
    "available": 3,
    "stock_status": "low_stock"
  }
}
```

### Fouten

- `404` wanneer het product-id niet bestaat voor deze winkel.
- `403` module- en scope-fouten zoals op het batch-endpoint.