GS-Fulfilment API

Haal de zendingen die wij voor je versturen op in je eigen systemen, met de maten en het gewicht zoals de vervoerder ze echt heeft gemeten.

Voor elke zending krijg je het ordernummer, de trackingcode, de vervoerder, de productregels, het aantal picks en de meting uit het sorteercentrum van DHL of PostNL. Zo kun je je dashboard, je margeberekening of je eigen controle voeden met dezelfde gegevens die wij gebruiken.

Gemeten matenGewicht in gram, lengte, breedte en hoogte in mm, volume in cm³.

Picks per zendingHet aantal gepickte stuks, met de regels per sku.

Alleen wijzigingenVraag op wat er sinds je vorige keer nieuw of veranderd is.

De API is alleen-lezen en geeft uitsluitend jouw eigen zendingen terug, vanaf 1 september 2026. Namen en adressen van je klanten zitten er niet in.

Basis-URL

Productie

https://api.gs-fulfilment.eu

Formaat

Afspraken

# Antwoorden zijn JSON (UTF-8)
# Tijden zijn UTC, ISO 8601
"2026-09-24T15:51:25Z"
# Maten in mm, gewicht in gram

Authenticatie

Elke vraag heeft een API-sleutel nodig. Je krijgt die van GS-Fulfilment via een apart, veilig kanaal. Een sleutel begint met gsf_ en hoort bij precies één klant.

Stuur de sleutel mee in de Authorization-header, als Bearer-token.

Behandel de sleutel als een wachtwoord: niet in de browser, niet in een openbare repository. Gelekt of kwijt? Laat het ons weten, dan trekken we hem in en krijg je een nieuwe.

Zonder geldige sleutel krijg je 401.

Header

HTTP

Authorization: Bearer gsf_jouw-sleutel

Antwoord zonder sleutel

401 Unauthorized

{
  "detail": "Geen geldige sleutel meegestuurd."
}

Synchroniseren

De API werkt met een cursor. Je vraagt steeds op wat er ná je vorige vraag nieuw of gewijzigd is. Zo mis je niets en haal je niets onnodig dubbel op.

Vraag de eerste keer GET /v1/zendingen op, zonder na. Je begint dan bij 1 september 2026.
Bewaar de waarde van volgende uit het antwoord.
Is meer true? Vraag dan meteen opnieuw, met na=<volgende>.
Is meer false? Dan ben je bij. Vraag bijvoorbeeld elk kwartier opnieuw met de bewaarde volgende.

Een zending kan terugkomen

De vervoerder meet een pakket pas in het sorteercentrum, meestal de avond of ochtend na verzending. Wij halen metingen elk uur op. Komt de meting binnen, dan geldt de zending als gewijzigd en krijg je hem opnieuw, nu met gemeten ingevuld.

Sla zendingen daarom op met zending_id als sleutel en overschrijf wat je al had.

Voorbeeld: bijwerken

import requests

URL = "https://api.gs-fulfilment.eu/v1/zendingen"
KOP = {"Authorization": "Bearer gsf_jouw-sleutel"}

def bijwerken(cursor: str) -> str:
    while True:
        antwoord = requests.get(URL, headers=KOP,
                                params={"na": cursor, "limiet": 500})
        antwoord.raise_for_status()
        pagina = antwoord.json()
        for zending in pagina["zendingen"]:
            opslaan(zending)  # op zending_id, overschrijven
        cursor = pagina["volgende"]
        if not pagina["meer"]:
            return cursor  # bewaren voor de volgende keer

const URL = "https://api.gs-fulfilment.eu/v1/zendingen";
const KOP = { Authorization: "Bearer gsf_jouw-sleutel" };

async function bijwerken(cursor = "") {
  while (true) {
    const params = new URLSearchParams({ na: cursor, limiet: "500" });
    const res = await fetch(`${URL}?${params}`, { headers: KOP });
    if (!res.ok) throw new Error(`API gaf ${res.status}`);
    const pagina = await res.json();
    for (const zending of pagina.zendingen) {
      await opslaan(zending); // op zending_id, overschrijven
    }
    cursor = pagina.volgende;
    if (!pagina.meer) return cursor; // bewaren voor de volgende keer
  }
}

Zendingen ophalen

GET/v1/zendingen

Geeft de zendingen die ná de cursor nieuw of gewijzigd zijn, de oudste wijziging eerst.

Queryparameters

Parameter	Omschrijving
nastring, optioneel	De waarde van `volgende` uit het vorige antwoord. Leeg of weggelaten: vanaf het begin.
limietinteger, 1 tot 1000	Maximaal aantal zendingen per antwoord. Standaard 500.

Antwoord

Veld	Omschrijving
zendingenarray	Lijst van zending-objecten.
volgendestring	Cursor voor je volgende vraag. Zonder nieuwe zendingen blijft hij gelijk aan wat je meestuurde.
meerboolean	`true` als er direct nog een pagina klaarstaat.

Vraag

curl "https://api.gs-fulfilment.eu/v1/zendingen?limiet=500" \
  -H "Authorization: Bearer gsf_jouw-sleutel"

import requests

antwoord = requests.get(
    "https://api.gs-fulfilment.eu/v1/zendingen",
    headers={"Authorization": "Bearer gsf_jouw-sleutel"},
    params={"limiet": 500},
)
pagina = antwoord.json()

const res = await fetch(
  "https://api.gs-fulfilment.eu/v1/zendingen?limiet=500",
  { headers: { Authorization: "Bearer gsf_jouw-sleutel" } }
);
const pagina = await res.json();

Antwoord 200

application/json

{
  "zendingen": [
    {
      "zending_id": "3f1c9e2a-7b44-4d0e-9a51-2c8e6d0b7a13",
      "ordernummer": "346399",
      "tracking": "JVGL06249163000072276669",
      "vervoerder": "dhl",
      "methode": "DHLForYou",
      "land": "NL",
      "aangemaakt_op": "2026-09-24T15:51:25Z",
      "picks": 3,
      "regels": [
        { "sku": "ABC-1", "aantal": 2, "soort": "normal" },
        { "sku": "XYZ-9", "aantal": 1, "soort": "normal" }
      ],
      "gemeten": {
        "gewicht_gram": 1050,
        "lengte_mm": 400,
        "breedte_mm": 310,
        "hoogte_mm": 190,
        "volume_cm3": 23560,
        "bron": "DHL",
        "opgehaald_op": "2026-09-25T12:14:42Z"
      },
      "gewijzigd_op": "2026-09-25T12:14:42Z"
    }
  ],
  "volgende": "2026-09-25T12:14:42Z|3f1c9e2a-7b44-4d0e-9a51-2c8e6d0b7a13",
  "meer": false
}

Zending opzoeken

GET/v1/zendingen/{tracking}

Geeft één zending op trackingcode, in dezelfde vorm als een zending-object. Handig om een losse zending te controleren, bijvoorbeeld bij een vraag van een klant.

Padparameter

Parameter	Omschrijving
trackingstring	De trackingcode van de vervoerder, bijvoorbeeld `JVGL06249163000072276669`.

Hoort de trackingcode niet bij jouw zendingen, of bestaat hij niet, dan krijg je 404.

Vraag

cURL

curl "https://api.gs-fulfilment.eu/v1/zendingen/JVGL06249163000072276669" \
  -H "Authorization: Bearer gsf_jouw-sleutel"

Niet gevonden 404

application/json

{
  "detail": "Geen zending met deze trackingcode gevonden."
}

Zending

Eén pakket dat GS-Fulfilment voor je heeft verstuurd.

Veld	Omschrijving
zending_idstring	Vast, uniek id van de zending. Gebruik dit als sleutel bij het opslaan.
ordernummerstring	Het ordernummer uit je webshop of marktplaats.
trackingstring	Trackingcode van de vervoerder.
vervoerderstring	In kleine letters, meestal `dhl` of `postnl`.
methodestring	De verzendmethode, bijvoorbeeld `DHLForYou`.
landstring	Bestemmingsland, ISO-code van twee letters (`NL`, `BE`).
aangemaakt_opstring, UTC	Moment waarop de zending is aangemaakt.
picksinteger	Aantal gepickte stuks. Zie Regel en picks.
regelsarray	De productregels in dit pakket.
gemetenobject of null	De gemeten maten, of `null` zolang er nog geen meting is.
gewijzigd_opstring, UTC	Laatste moment waarop de zending of de meting veranderde.

Zending zonder meting

JSON

{
  "zending_id": "8d0b5c61-...",
  "ordernummer": "347163",
  "tracking": "3SGSF0123456789",
  "vervoerder": "postnl",
  "land": "BE",
  "picks": 1,
  "gemeten": null,
  ...
}

Regel en picks

Elke regel is één product in het pakket.

Veld	Omschrijving
skustring	Je eigen artikelcode.
aantalinteger	Aantal stuks.
soortstring	`normal`: gewoon product. `parent`: een samengesteld product (bundel). `child`: een onderdeel van die bundel.

Zo tellen we picks

picks is de som van alle aantallen, behalve de regels met soort parent. Een bundel wordt niet als geheel uit het schap gepakt; de onderdelen wel. Een set van drie producten telt dus als drie picks.

Voorbeeld: een bundel

JSON

"regels": [
  { "sku": "GIFTSET", "aantal": 1, "soort": "parent" },
  { "sku": "THEE-A",  "aantal": 2, "soort": "child" },
  { "sku": "MOK-1",   "aantal": 1, "soort": "child" },
  { "sku": "KAART",   "aantal": 1, "soort": "normal" }
],
"picks": 4   // 2 + 1 + 1, de GIFTSET-regel telt niet

Gemeten maten

De maten en het gewicht zoals de sorteermachine van de vervoerder ze heeft gemeten. Dit is ook de basis waarop de vervoerder factureert.

Veld	Omschrijving
gewicht_graminteger	Gewicht in gram.
lengte_mminteger	Lengte in millimeter.
breedte_mminteger	Breedte in millimeter.
hoogte_mminteger	Hoogte in millimeter.
volume_cm3integer	Volume in cm³. Delen door 1.000 geeft liters.
bronstring	Welke vervoerder mat: `DHL` of `PostNL`.
opgehaald_opstring, UTC	Wanneer wij de meting bij de vervoerder ophaalden.

Wanneer is er geen meting?

gemeten is null zolang het pakket nog niet door het sorteercentrum is gegaan. Voor zendingen die Bol zelf vervoert en voor enkele kleine vervoerders komt er geen meting.

DHL rondt maten af op hele centimeters, PostNL meet op de millimeter. Je ziet beide in millimeters.

Gemeten

JSON

"gemeten": {
  "gewicht_gram": 1050,
  "lengte_mm": 400,
  "breedte_mm": 310,
  "hoogte_mm": 190,
  "volume_cm3": 23560,
  "bron": "DHL",
  "opgehaald_op": "2026-09-25T12:14:42Z"
}

Foutcodes en limieten

Code	Betekenis
200	Gelukt.
401	Geen sleutel, een onbekende sleutel of een ingetrokken sleutel.
404	Zending niet gevonden, of niet van jou.
422	Ongeldige parameter, bijvoorbeeld een `limiet` boven 1000.
429	Te veel vragen deze minuut. Wacht even en probeer opnieuw.

Limiet

Maximaal 60 vragen per minuut per sleutel. Voor bijwerken is één ronde per kwartier ruim genoeg; de metingen komen toch per uur binnen.

Fout-antwoord

429 Too Many Requests

{
  "detail": "Te veel vragen deze minuut; probeer het zo opnieuw."
}

Wijzigingen

Versie	Wat
1.025 september 2026	Eerste versie: zendingen ophalen en opzoeken, met gemeten maten en picks.

Nieuwe velden kunnen erbij komen zonder nieuwe versie. Negeer dus velden die je niet kent. Wat bestaat, veranderen we niet zonder het vooraf te melden.

Contact

Vragen over de API, een nieuwe sleutel nodig of iets gezien dat niet klopt? Mail naar info@gs-fulfilment.nl en vermeld je bedrijfsnaam. Stuur nooit je sleutel mee.

Wil je de API eerst uitproberen? Op de testpagina vul je je sleutel in en doe je direct een vraag.