# Categorieën

Categorieën vormen per tenant een zelfrefererende boom. Elke categorie heeft een slug die uniek is binnen de tenant en automatisch wordt gegenereerd uit de naam. Categorieslugs zijn de waarden die de queryparameter `filter[category]` van de productlijst accepteert; die matcht een categorie en al haar actieve afstammelingen.

## GET /v1/api/commerce/categories

Geeft de volledige categorieboom van de tenant terug als geneste JSON. Alleen actieve categorieën worden opgenomen, op elk niveau geordend op `position`. Een inactieve parent verbergt zijn hele subboom: kinderen van een inactieve parent vallen buiten het resultaat, ook als ze zelf actief zijn. De response is niet gepagineerd.

### Parameters

Geen. Geen pad-, query- of bodyparameters.

### Responsevelden

Elke node in de `data`-array (en recursief in elke `children`-array):

| Naam | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- |
| id | string (uuid) | altijd | Categorie-ID. |
| name | string | altijd | Categorienaam. |
| slug | string | altijd | URL-slug, uniek per tenant. Gebruik hem als `filter[category]`-waarde op het productlijst-endpoint. |
| description | string of null | altijd | Categoriebeschrijving. |
| children | array | altijd | Kindcategorieën, zelfde nodevorm, geordend op positie. Lege array voor bladcategorieën. |

```bash title="Request"
curl "https://api.borkol.com/v1/api/commerce/categories" \
  -H "Authorization: Bearer {api_key}" \
  -H "Accept: application/json"
```

```javascript title="Request (JS)"
const res = await fetch("https://api.borkol.com/v1/api/commerce/categories", {
  headers: {
    Authorization: `Bearer ${apiKey}`,
    Accept: "application/json",
  },
});
const { data } = await res.json();
```

```json title="Response"
{
  "data": [
    {
      "id": "7a1b3c5d-2e4f-4a6b-8c0d-1e2f3a4b5c6d",
      "name": "Furniture",
      "slug": "furniture",
      "description": "All furniture",
      "children": [
        {
          "id": "8b2c4d6e-3f5a-4b7c-9d1e-2f3a4b5c6d7e",
          "name": "Chairs",
          "slug": "chairs",
          "description": null,
          "children": []
        }
      ]
    },
    {
      "id": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
      "name": "Verandas",
      "slug": "verandas",
      "description": null,
      "children": []
    }
  ]
}
```

### Errors

| Status | Body | Oorzaak |
| --- | --- | --- |
| 401 | `{"message":"Unauthenticated."}` | Ontbrekende of ongeldige API-key. |
| 403 | `{"message":"Invalid ability provided."}` | Key heeft noch de scope `catalog:read` noch `commerce:read`. |
| 403 | `{"error":"Module not enabled: catalog"}` | Tenant heeft de catalog-module niet ingeschakeld. Let op de `error`-key in plaats van `message`. |
| 403 | `{"message":"Tenant suspended.","code":"tenant_suspended"}` | Tenant-account is geschorst. |
| 429 | `{"message":"Too Many Attempts."}` | Rate limit van 120 requests per minuut overschreden. |