# Je eerste API-call

Log eerst in op de [console](/account/) en maak een [API-key](/api-keys/) met **API-gebruik lezen**. Bewaar de key in de geheime configuratie van je koppeling. Daarna kun je de onderstaande aanvraag uitvoeren.

## Kies de juiste basis-URL

Alle API-aanvragen gaan naar `https://api.vlows.io`. Het pad bepaalt welke gegevens je opvraagt of aanlevert. De console gebruik je om in te loggen en keys te beheren; je koppeling gebruikt de API-key bij elke aanvraag.

## Authenticatie meesturen

Elke aanvraag met een API-key gebruikt de header `Authorization: Bearer <key>`. Verstuur keys niet als queryparameter. De voorbeelden nemen aan dat je `API_KEY` via je eigen secretconfiguratie hebt ingesteld.

```sh
API_URL=https://api.vlows.io
curl --fail-with-body --silent --show-error \
  "$API_URL/account/v1/usage" \
  -H "Authorization: Bearer $API_KEY"
```

Dit endpoint vereist `usage:read`. Een key die alleen leveringen mag lezen krijgt hier `403`.

## Een antwoord lezen

Succes gebruikt een envelope met `data` en een lege `error`. Een nieuwe organisatie kan nog geen geregistreerd gebruik hebben:

```json
{"data": [], "error": null}
```

Bij fouten is `data` leeg en bevat `error` een code en uitleg. De `request_id` is bruikbaar bij onderzoek. Deel daarbij nooit je volledige sleutel.

```json
{
  "data": null,
  "error": {
    "code": "forbidden_scope",
    "message": "Required permission is missing",
    "request_id": "<request-uuid>"
  }
}
```

## Voorbeeld in Python

Dit voorbeeld gebruikt alleen de standaardbibliotheek en een key met `usage:read`.

```python
import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

base = os.environ.get("API_URL", "https://api.vlows.io")
request = Request(
    base + "/account/v1/usage/requests",
    headers={"Authorization": "Bearer " + os.environ["API_KEY"]},
)
try:
    with urlopen(request, timeout=15) as response:
        rows = json.load(response)["data"]
        for row in rows:
            print(row["route"], row["status"], row["units"])
except HTTPError as error:
    details = json.load(error)["error"]
    print(error.code, details["code"], details.get("request_id"))
```

## Controleer je aanvraag in de console

Open **API-gebruik** in de console. Zoek je aanvraag op tijdstip, keynaam en endpoint. Een gebruiksaanvraag wordt na het ophalen van de gegevens geregistreerd: bij je eerste aanvraag kan `data` dus leeg zijn. Herlaad de gebruikspagina of wacht op de automatische verversing na 60 seconden.

Wil je stoppen met deze koppeling, trek dan de key in onder **API-keys**. Nieuwe aanvragen krijgen daarna `401`; eerdere gebruiksgegevens blijven zichtbaar.

## Betrouwbaar integreren

Gebruik JSON voor requestbodies, met `Content-Type: application/json`. De API wijst onbekende invoervelden af. Houd de body onder de huidige limiet van 2 MiB. Stel een timeout in en behandel fouten bewust.

Nieuwe leveringen, gebeurtenissen en pogingen vereisen een `Idempotency-Key`. Updates aan een levering vereisen een `If-Match`-versie. Deze mechanismen voorkomen dubbele verwerking en onbedoeld overschrijven. Zie [Fouten & opnieuw proberen](/foutmeldingen/).

## Verder bouwen

Gebruik het [endpointoverzicht](/endpoints/) om de juiste route en scope te kiezen. De [OpenAPI-specificatie](/assets/openapi.json) kun je downloaden; de responseschema's zijn in deze pilot nog algemeen. Raadpleeg daarom ook de uitgewerkte voorbeelden en [pakketvelden](/pakketvelden/).