Developers

Voeg pakketverzending toe aan je eigen website of software

Koppel je webshop, koeriersbedrijf of platform aan Pakketbezorgd.nl en gebruik onze vervoerders, tarieven, labels en tracking onder je eigen merk. Eén integratie, meerdere vervoerders — welke vervoerder wij waar inkopen blijft aan onze kant.

Koeriersbedrijf

Bied normale pakketverzending aan zonder ieder pakket zelf te rijden. Je houdt je eigen klant en je eigen website.

Webshop

Toon verzendopties en tarieven in je eigen checkout en maak direct labels aan.

Softwareplatform

Integreer verzenden in je eigen systeem of ERP en verwerk status en tracking terug.

Wat je vandaag via de API kunt doen

Tarieven en levertijden opvragen
Zendingen aanmaken met idempotentie
Verzendlabel (PDF) ophalen
Status en tracking ophalen
Zending annuleren
Servicepunten in de buurt opzoeken
Webhooks met signature ontvangen

API-toegang wordt handmatig vrijgegeven: je vraagt een key aan, test in de sandbox en wij zetten productie aan na een geslaagde test.

API-toegang aanvragen Voor koeriersbedrijven

Technische documentatie

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

Met een sandbox-key worden zendingen in de testomgeving van de vervoerder aangemaakt: echte ID's en labels, geen verzendkosten. Ideaal om je koppeling end-to-end te testen.

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. Webhookafleveringen kunnen bij time-outs of fouten opnieuw worden aangeboden: gebruik X-Pakketbezorgd-Event-Id / event_id om events idempotent te verwerken en duplicaten te negeren. 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..."
  }
}