Changelog

Elke wijziging in de publieke API, nieuwste eerst. Wijzigingen binnen v1 voegen alleen toe; een verwijdering of onverenigbare wijziging kondigen we hier minstens 12 maanden van tevoren aan. Zie Versies en uitfasering.

21 oktober 2026: een ingepakte order kan terug naar packing

• Corrigeert een inpakker een inpakfout, dan gaat een packed order terug naar packing, om opnieuw te worden ingepakt. GET /api/v1/orders/changes meldt dat als een order.status_changed naar packing. Verder verandert er niets: packing was al een van de statussen. Zie Wat er daarna in het magazijn gebeurt.

18 oktober 2026: wanneer de klant bestelde

• POST /api/v1/orders neemt een optionele ordered_at: wanneer de klant de order plaatste, als ISO 8601-datum-tijd met offset, of als losse datum (YYYY-MM-DD) als je alleen de dag weet. Picked bewaart het, toont het op de orderpagina en dateert de pakbon ermee. Zonder het veld verandert er niets: de order komt binnen zoals voorheen.

18 oktober 2026: een order kan terug naar pending

• Een order waarvan de pickronde voor het einde stopt, gaat van picking terug naar pending, om opnieuw te worden ingepland. GET /api/v1/orders/changes meldt dat als een order.status_changed naar pending, en de order houdt zijn picked_quantity. Verder verandert er niets: pending was al een van de statussen. Zie Wat er daarna in het magazijn gebeurt.

18 oktober 2026: de referentie beschrijft elke fout

• Elke 4xx en 5xx in de API-referentie noemt nu de foutvorm die je al krijgt: message en een vaste code, plus het veld errors bij een 422. Op de lijn verandert niets; een client die uit de specificatie is gegenereerd, kan nu code lezen.
• De specificatie noemt haar tags en een supportcontact, en beschrijft elke operatie.

18 oktober 2026: links op elk antwoord

• Elke v1-resource en -pagina draagt _links in HAL-stijl, een veld dat er alleen bij komt. Een resource met een eigen GET linkt naar zichzelf: een ontvangst, een procesrun, een voorraadstand, de nodecatalogus. Een pagina linkt naar zichzelf en de pagina's ernaast (_links.next, _links.prev), met je filters erin: GET /api/v1/locations, GET /api/v1/stock/changes, en GET /api/v1/stock met changed_since. GET /api/v1/stock/changes/feed linkt zijn volgende lezing zolang hasMore waar is. GET /api/v1/warehouses en een skus-lezing van GET /api/v1/stock linken naar zichzelf.
• POST /api/v1/receipts en POST /api/v1/processes/{process}/runs antwoorden een nieuwe ontvangst of run met een Location-header waar je hem terugleest. Een dry run, en een antwoord dat een eerder gemaakte teruggeeft, hebben er geen.

17 oktober 2026: orderwijzigingen volgen

• GET /api/v1/orders/changes?after={cursor} leest elke wijziging van je orders na een cursor, oudste eerst: een order die een status krijgt (order.status_changed), en een zending die wordt aangemaakt, naar een andere vervoerder gaat, een label krijgt, aan de vervoerder wordt meegegeven, wordt bezorgd, mislukt of terugkomt (shipment.created, shipment.carrier_changed, shipment.label_created, shipment.dispatched, shipment.delivered, shipment.failed, shipment.returned). Elke wijziging bevat de order zoals hij nu is, en de pagina linkt _links.next zolang er meer wacht. Daarvoor is orders:read nodig. Zie Orderwijzigingen volgen.

17 oktober 2026: een order teruglezen

• GET /api/v1/orders/{id} leest een order terug: de status; per regel picked_quantity, shipped_quantity en closed_short_quantity (de eerste twee null, dus niet geteld, zolang het magazijn voor de order niets telt); en de zendingen met vervoerder, trackingnummer, de trackinglink van de vervoerder, en elk pakket onder parcels als hij in meerdere de deur uitging. Daarvoor is het nieuwe recht orders:read nodig. De naam en het adres van de klant staan er nooit in. Zie Volg de order tot hij verzonden is.
• POST /api/v1/orders antwoordt op een nieuwe order met een Location-header en _links.order, waar je hem terugleest. Antwoorden krijgen HAL-achtige _links: een veld dat er alleen bijkomt, dus niets wat je nu leest verschuift.

15 oktober 2026: een antwoord gebruiken in latere stappen

• Een stap die wacht op een signaal of een callback kan velden uit zijn payload of data in outputs zetten die latere stappen tonen en gebruiken. POST /api/v1/process-runs/callbacks/{token} antwoordt 422 als data zo'n veld mist of er een van een ander type heeft, en het werk blijft wachten. Een signaal naar POST /api/v1/process-events/{eventKey} dat er een mist, maakt die stap niet wakker. Zie Gebruik het antwoord in latere stappen.
• Een signaal dat binnenkomt nadat Opgeven na van een stap voorbij is, maakt niets meer wakker: de stap gaat verder met timed_out, wanneer Picked er ook aan toekomt. Eerder kon een signaal in de minuut na de time-out nog winnen.

15 oktober 2026: een antwoord van je eigen systeem

• POST /api/v1/process-runs/callbacks/{token} beantwoordt een stap die je systeem aanroept: de stap roept je endpoint aan met een callback_url voor eenmalig gebruik, en terugbellen maakt dat ene stuk werk wakker met je outcome en data. Er is geen API-token nodig. Zie Laat je systeem over een stap beslissen.

15 oktober 2026: een correctie in hoe orderregels hun product vinden

• POST /api/v1/orders vergelijkt de product_external_ref van een regel alleen met producten die je in Picked beheert. Een product dat een gekoppeld ERP of een gekoppelde webshop heeft geïmporteerd, draagt het id van dat systeem als referentie, en een orderregel kon zo het verkeerde product noemen. Zo'n product wordt nu op de SKU of barcode van de regel gevonden, en een regel die nergens bij past krijgt een tijdelijk product, vermeld in provisioned_products. De external_ref van zo'n tijdelijk product is leeg als de referentie van de regel zijn SKU was of de referentie van een ander product: koppel het aan je regel via sku. Dit geldt meteen, een uitzondering op de 12 maanden aankondiging hierboven: de oude vergelijking kon het verkeerde product laten versturen, en nog geen enkele koppeling rekende erop. Zie Orders doorsturen.

14 oktober 2026: een procesrun starten

• POST /api/v1/processes/{process}/runs start een run van een proces, aangewezen met zijn publieke id, met de variables waarmee hij start: hij komt op de vloer klaar om opgepakt te worden, zoals een geplande run. GET /api/v1/process-runs/{id} leest hem terug. Beide hebben het nieuwe recht process-runs:write nodig. Zie Een procesrun starten vanuit een ander systeem.
• De Idempotency-Key-header: bij POST /processes/{process}/runs geeft een herhaling met dezelfde sleutel binnen 24 uur het eerste antwoord terug, en opent er niets. Zie Idempotentie.
• Picked-Dry-Run: true werkt ook bij het starten van een run.

13 oktober 2026: magazijn- en locatie-id's, en antwoorden in het Engels

• GET /api/v1/warehouses geeft je magazijnen met de warehouse_id die orders en ontvangsten nodig hebben, en GET /api/v1/locations je locaties met de location_id waarop voorraadwijzigingen filteren. Elk API-token mag beide aanroepen, met welke rechten ook. Zie Aan de slag.
• Elk antwoord van /api/v1 is in het Engels, ook de foutmelding in message en de validatiefouten in errors, in welke taal de server ook draait.

13 oktober 2026: voorraadniveaus die sinds een moment veranderden

• GET /api/v1/stock neemt changed_since: de niveaus van elk product waarvan de voorraad, de orderclaims of de locaties sindsdien veranderden, per pagina. Orderclaims stonden nooit in /stock/changes, dus zo merkt een webshop dat een order voorraad nam. Het antwoord heeft de vorm van een skus-aanvraag, met pagination erbij. Zie De voorraad in je webshop bijhouden.

13 oktober 2026: een cursor op voorraadwijzigingen

• GET /api/v1/stock/changes/feed?after=<cursor>: de voorraadwijzigingen na een cursor, oudste eerst, met de nextCursor om daarna te sturen en hasMore. Een wijziging die binnenkomt terwijl je leest, sla je niet over en lees je niet dubbel. GET /api/v1/stock/changes geeft nog steeds pagina's, ongewijzigd. Zie Voorraadwijzigingen doorbladeren.

13 oktober 2026: de basis van v1

Deze vermelding legt de v1-API vast zoals hij erbij stond toen deze handleidingen verschenen. Elke latere wijziging staat erboven.

Endpoints

Gedrag

• Eén foutmelding voor elke mislukking, met een vaste code.
• Rate limits van 200 verzoeken per minuut voor de voorraad-endpoints en 60 voor de rest, per werkruimte, met X-RateLimit-Limit en X-RateLimit-Remaining op elk antwoord op een geauthenticeerde aanroep.
• Idempotente orderimports op external_id, en leveringsaanmeldingen op reference.
• Proefruns met de header Picked-Dry-Run op POST /api/v1/orders en POST /api/v1/receipts.