# Endpointoverzicht

De basis-URL voor alle aanvragen is `https://api.vlows.io`. Gebruik een API-key uit de [console](/api-keys/) en stuur die mee als `Authorization: Bearer <jouw-api-key>`.

Onderstaande routes zijn bedoeld voor je softwarekoppeling. De scope in de tabel moet op je key zijn aangevinkt. Inloggen en keys beheren doe je in de [console](/account/).

Zoek je de benodigde velden? Begin bij [Welke velden vul ik waar in?](/velden-per-handeling/) of open de veldgids naast de betreffende route. [Aanvragen opbouwen](/aanvragen-opbouwen/) legt headers, JSON en URL-parameters uit.

## Gebruik & organisatiegegevens

[Lees de handleiding](/api-gebruik/).

| Methode | Route | Scope | Werking en invoer |
| --- | --- | --- | --- |
| `GET` | `/account/v1/couriers` | `deliveries:read` | Geregistreerde vervoerders opvragen. [Veldgids](/leveringen/#gebruik-een-geregistreerde-vervoerder). |
| `GET` | `/account/v1/overview` | `deliveries:read` | Aantallen binnen je eigen organisatie opvragen. [Veldgids](/velden-per-handeling/#gegevens-lezen-zonder-extra-invoervelden). |
| `GET` | `/account/v1/usage` | `usage:read` | Gebruiksdagtotalen over 30 dagen. [Veldgids](/api-gebruik/). |
| `GET` | `/account/v1/usage/requests` | `usage:read` | Laatste 100 gebruiksverzoeken binnen 30 dagen. [Veldgids](/api-gebruik/). |

## Leveringen, adressen & oracle

[Lees de handleiding](/leveringen/).

| Methode | Route | Scope | Werking en invoer |
| --- | --- | --- | --- |
| `GET` | `/deliveries/v1/parcels` | `deliveries:read` | Leveringenlijst met cursorpaginering. [Veldgids](/leveringen/#lijstfilters-en-paginering). |
| `POST` | `/deliveries/v1/parcels` | `deliveries:write` | Levering aanmaken; Idempotency-Key verplicht. [Veldgids](/leveringen/#een-levering-aanmaken). |
| `GET` | `/deliveries/v1/parcels/{id}` | `deliveries:read` | Eén levering lezen, inclusief ETag. [Veldgids](/leveringen/#een-levering-opvragen). |
| `PATCH` | `/deliveries/v1/parcels/{id}` | `deliveries:write` | Levering wijzigen; actuele If-Match verplicht. [Veldgids](/leveringen/#een-levering-wijzigen). |
| `GET` | `/deliveries/v1/parcels/{id}/events` | `deliveries:read` | Maximaal 1000 gebeurtenissen voor een levering. [Veldgids](/gebeurtenissen/#geschiedenis-uitlezen). |
| `POST` | `/deliveries/v1/parcels/{id}/events` | `deliveries:write` | Status 0–3 melden; Idempotency-Key verplicht. [Veldgids](/gebeurtenissen/#velden-voor-een-gebeurtenis). |
| `GET` | `/deliveries/v1/parcels/{id}/attempts` | `deliveries:read` | Pogingen voor een levering lezen. [Veldgids](/gebeurtenissen/#geschiedenis-uitlezen). |
| `POST` | `/deliveries/v1/parcels/{id}/attempts` | `deliveries:write` | Bezorgpoging melden; Idempotency-Key verplicht. [Veldgids](/gebeurtenissen/#velden-voor-een-bezorgpoging). |
| `POST` | `/deliveries/v1/address/validate` | `deliveries:write` | Een Nederlands adres controleren. [Veldgids](/adressen/#invoervelden). |
| `GET` | `/deliveries/v1/reference` | `deliveries:read` | Statussen, eenheden en referentiecodes. [Veldgids](/pakketvelden/#service--en-locatiecodes). |
| `GET` | `/deliveries/v1/oracle/{metric}` | `oracle:read` | Aggregatie activity/planned of coverage-metadata. [Veldgids](/oracle/#invoervelden). |

## Een aanvraag doen

```sh
API_URL=https://api.vlows.io
# Gebruik een key met usage:read uit je geheime configuratie.
curl --fail-with-body --silent --show-error \
  "$API_URL/account/v1/usage" \
  -H "Authorization: Bearer $API_KEY"
```

De paden die met `/account/v1/` beginnen geven hier gebruiksgegevens, vervoerders en een organisatieoverzicht terug. Ze zijn geen inlogstappen voor je koppeling.

## Invoer en fouten

Gebruik `Content-Type: application/json` wanneer je JSON verstuurt. Aanmaken van leveringen, gebeurtenissen en pogingen vereist een `Idempotency-Key`. Leveringen wijzigen vereist de actuele `If-Match`. Lees [Je eerste API-call](/api-snelstart/) en [Fouten & opnieuw proberen](/foutmeldingen/) voor voorbeelden en herhaalgedrag.

## Machineleesbare specificatie

Download [OpenAPI JSON](/assets/openapi.json) om je client in te richten. Deze specificatie bevat de klantendpoints voor API-keys, met `https://api.vlows.io` als basisadres. De responseschema's zijn nog algemeen; gebruik ook de uitgewerkte voorbeelden en [pakketvelden](/pakketvelden/).