Developers

Pakketbezorgd API v1

Koppel je webshop of ERP aan Pakketbezorgd.nl en gebruik automatisch onze vervoerders, tarieven, labels en tracking. Eén integratie, meerdere vervoerders — welke vervoerder wij inkopen bij welke bron blijft aan onze kant.

API-keys aanmaken

1. Log in met je zakelijke account.
2. Ga naar API-keys beheren en voeg je webshop toe als API-klant.
3. Kopieer de key direct: hij wordt alleen bij het aanmaken (of roteren) getoond en daarna uitsluitend als hash bewaard.

Sandbox / testfase

Zolang het platform in testmodus staat, worden zendingen in de testomgeving van de vervoerder aangemaakt: echte ID's en labels, geen kosten. Je gebruikt hiervoor dezelfde key.

Productie

Keys beginnen met pb_live_. Productiezendingen worden pas vrijgegeven na een geslaagde sandboxtest en een actief zakelijk account.

API-keys beheren Inloggen / registreren

Authenticatie

Stuur je key mee als bearer token. Elke key heeft scopes (rates:read, shipments:write, shipments:read, labels:read) en een eigen rate limit per minuut.

Authorization: Bearer pb_test_xxxxxxxxxxxxxxxx
Content-Type: application/json
Idempotency-Key: <unieke sleutel per schrijfactie>

Endpoints

POST/api/public/v1/ratesscope: rates:read

Tarieven opvragen

Geeft de beschikbare vervoerders, services, levertijden en klantprijzen terug. Elk tarief bevat een quote_id dat 15 minuten geldig is. Inkoopprijs, marge en provider zijn nooit onderdeel van de response.

curl -X POST https://pakketbezorgd.nl/api/public/v1/rates \
  -H "Authorization: Bearer $PB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_country": "NL",
    "from_postal_code": "1011AB",
    "to_country": "BE",
    "to_postal_code": "1000",
    "weight_kg": 5,
    "length_cm": 40,
    "width_cm": 30,
    "height_cm": 20,
    "customer_type": "zakelijk"
  }'

POST/api/public/v1/shipmentsscope: shipments:write

Zending aanmaken

Maakt op basis van een quote_id een zending aan. Stuur altijd een Idempotency-Key mee: dezelfde key met dezelfde payload geeft exact dezelfde response, met een andere payload een 409 Conflict. Bij een servicepunt-tarief (requires_service_point) is service_point verplicht.

curl -X POST https://pakketbezorgd.nl/api/public/v1/shipments \
  -H "Authorization: Bearer $PB_API_KEY" \
  -H "Idempotency-Key: order-10231" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "pbq_...",
    "reference": "order-10231",
    "from": { "name": "Webshop BV", "street": "Keizersgracht", "house_number": "1", "postal_code": "1015CJ", "city": "Amsterdam", "country": "NL", "email": "verzend@webshop.nl", "phone": "0201234567" },
    "to":   { "name": "Jan Jansen", "street": "Nieuwstraat", "house_number": "5", "postal_code": "1000", "city": "Brussel", "country": "BE", "email": "jan@example.com", "phone": "0470123456" }
  }'

GET/api/public/v1/shipments/{id}scope: shipments:read

Zending & status ophalen

Geeft status, tracking-nummer en tracking-URL van de zending. Je kunt uitsluitend zendingen van je eigen API-client opvragen; een onbekend of andermans ID geeft 404.

curl https://pakketbezorgd.nl/api/public/v1/shipments/{id} \
  -H "Authorization: Bearer $PB_API_KEY"

GET/api/public/v1/shipments/{id}/labelscope: labels:read

Verzendlabel ophalen

Geeft het PDF-label van de zending. Zolang de zending nog niet is aangemaakt bij de vervoerder, krijg je een duidelijke foutcode.

curl -L https://pakketbezorgd.nl/api/public/v1/shipments/{id}/label \
  -H "Authorization: Bearer $PB_API_KEY" -o label.pdf

GET/api/public/v1/shipments/{id}/trackingscope: shipments:read

Tracking ophalen

Geeft de bekende tracking-events van de zending, nieuwste eerst.

curl https://pakketbezorgd.nl/api/public/v1/shipments/{id}/tracking \
  -H "Authorization: Bearer $PB_API_KEY"

POST/api/public/v1/shipments/{id}/cancelscope: shipments:write

Zending annuleren

Annuleert een zending zolang de vervoerder dat toestaat. Herhaalde aanvragen zijn veilig (idempotent).

curl -X POST https://pakketbezorgd.nl/api/public/v1/shipments/{id}/cancel \
  -H "Authorization: Bearer $PB_API_KEY"

GET/api/public/v1/service-pointsscope: servicepoints:read

Servicepunten ophalen

Geeft de pakketpunten van een vervoerder in de buurt van een postcode, inclusief adres en afstand.

curl "https://pakketbezorgd.nl/api/public/v1/service-points?country=NL&postal_code=1011AB&carrier=dpd" \
  -H "Authorization: Bearer $PB_API_KEY"

Webhooks

Wij sturen statuswijzigingen naar jouw endpoint (zending aangemaakt, label klaar, onderweg, bezorgd, geannuleerd, mislukt). Bezorging gebeurt via een outbox met retries en exponential backoff; elk event wordt maar één keer verstuurd. Verifieer altijd de signature en wijs een timestamp ouder dan 5 minuten af.

X-Pakketbezorgd-Event-Id: evt_...
X-Pakketbezorgd-Timestamp: 1756569600
X-Pakketbezorgd-Signature: sha256=<hex>

signature = HMAC_SHA256(secret, timestamp + "." + event_id + "." + rawBody)

Foutformaat

Alle fouten hebben hetzelfde formaat met een request_id dat je kunt doorgeven aan support. Statuscodes: 400, 401, 403, 404, 409, 422, 429 en 500.

{
  "error": {
    "code": "QUOTE_EXPIRED",
    "message": "Dit tarief is verlopen. Vraag een nieuw tarief op.",
    "request_id": "req_01H..."
  }
}