# REST API

> Wat de TradeCatalog REST API dekt, wie er gebruik van kan maken en elk eindpunt op een blik.

De REST API geeft uw eigen systemen dezelfde gegevens als uw medewerkers zien in TradeCatalog: producten, klantprijzen, klanten, bestellingen, prijsveranderingen en de activiteitenlog. Het gebruikt JSON over HTTPS en één API-sleutel per systeem.

## Basis-URL

```text
https://tradecatalog.app/api/v1
```

Elke aanvraag vereist een API-sleutel in de `Authorization` header. Zie [Authenticatie](/docs/api/authentication).

## Wie kan het gebruiken

- **Eigenaren en beheerders** maken en intrekken sleutels. Andere medewerkers en kopers kunnen dit niet.
- De werkruimte moet een **Pro-entiteit** of een **pilot-account** hebben om sleutels te maken.
- **Demo-werkruimtes** kunnen de API helemaal niet gebruiken.
- Wanneer Pro eindigt, keert de werkruimte terug naar Free: bestaande API-sleutels kunnen nog steeds lezen, maar niet schrijven. Cataloguswijzigingen en koperbestellingen in de app blijven werken.

Een sleutel behoort tot één werkruimte. Het werkt met de rechten van de persoon die het heeft gemaakt, dus een eigenaar’s of beheerder’s sleutel kan elke klantprijzen zien. Als die persoon de werkruimte verlaat, stopt de sleutel met werken.

## Eindpunten

| Methode | Pad                                                                     | Wat het doet                                                           | Toegang   |
| ------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------- |
| GET     | [`/workspace`](/docs/api/workspace)                                     | De werkruimte waar deze sleutel toe behoort                            | lezen     |
| GET     | [`/products`](/docs/api/products#list-or-search-products)               | Producten lijsten of zoeken, optioneel met klantprijzen                | lezen     |
| GET     | [`/products/{id}`](/docs/api/products#get-one-product)                  | Een product met zijn prijs                                             | lezen     |
| PUT     | [`/products`](/docs/api/products#create-or-update-products)             | Creëer of update maximaal 100 producten per SKU                        | schrijven |
| GET     | [`/brands`](/docs/api/products#brands-and-categories)                   | Alle merken                                                            | lezen     |
| GET     | [`/categories`](/docs/api/products#brands-and-categories)               | Alle categorieën                                                       | lezen     |
| GET     | [`/prices`](/docs/api/prices)                                           | Wat een klant betaalt voor een SKU, en waarom                          | lezen     |
| GET     | [`/customers`](/docs/api/customers#list-customers)                      | Handelsklanten                                                         | lezen     |
| GET     | [`/customers/{id}`](/docs/api/customers#get-one-customer)               | De voorwaarden, regels, overeengekomen prijzen en kopers van een klant | lezen     |
| PUT     | [`/customers`](/docs/api/customers#create-or-update-customers)          | Creëer of update maximaal 100 klanten                                  | schrijven |
| GET     | [`/orders`](/docs/api/orders#list-orders)                               | Recente bestellingen, nieuwste eerst                                   | lezen     |
| GET     | [`/orders/{id}`](/docs/api/orders#get-one-order)                        | Een bestelling met lijnen en statusgeschiedenis                        | lezen     |
| PATCH   | [`/orders/{id}`](/docs/api/orders#move-an-order-on)                     | Een bestelling verderzetten                                            | schrijven |
| GET     | [`/price-changes`](/docs/api/price-changes#list-price-changes)          | Prijsveranderingen, nieuwste eerst                                     | lezen     |
| GET     | [`/price-changes/{id}`](/docs/api/price-changes#preview-a-price-change) | Een prijsverandering bekijken                                          | lezen     |
| GET     | [`/activity`](/docs/api/activity)                                       | Wie wat heeft gewijzigd                                                | lezen     |

De volledige machine-leesbare beschrijving is te vinden op [`/api/v1/openapi.json`](/docs/api/openapi).

## Voordat u begint met bouwen

- Lees [Conventies](/docs/api/conventions) voor geld, paginering, datums en hoe `PUT` werkt.
- Lees [Fouten](/docs/api/errors) voor statuscodes en herproeven.
- Houd sleutels op uw server. De API stelt geen browser (CORS) aanvragen toe.

## Nog niet in de API

- Webhooks: gebruik in plaats daarvan `GET /orders?status=new`.
- Publiceren, plannen of annuleren van prijsveranderingen: doe dit in de app.
- Kortingsregels en overeengekomen prijzen: lees ze met `GET /customers/{id}`, wijzig ze in de app.
- Verwijderen van producten of klanten, direct uploaden van afbeeldingen, kopers uitnodigen, bestellingen plaatsen als koper.