Orders

Beheer orders en orderregels. Orders worden gebruikt voor het uitslag-proces: na het aanmaken van orders worden ze via waves gealloceerd en gepickt.

Endpoints

Alleen orders van de eigen opdrachtgever

Een API key die aan een opdrachtgever gekoppeld is, en een gebruiker van het klantportaal, werken alleen met orders van die opdrachtgever:

• GET /orders toont alleen de orders van die opdrachtgever.
• Elk endpoint op /orders/:id (ophalen, bijwerken, verwijderen, tekorten en de regels) geeft 404 als de order bij een andere opdrachtgever hoort, of geen opdrachtgever heeft. Dat is hetzelfde antwoord als voor een order die niet bestaat.
• Wie een andere client_id meestuurt, in de body of als filter, krijgt 403.

Voor een API key of gebruiker zonder opdrachtgever geldt geen beperking.

Orderstatus

Een order staat in order_status (id en description). Elke wijziging komt ook als webhook order_status binnen, met de omschrijving als old_status en new_status.

Partially Allocated komt op twee momenten voor:

• Bij de allocatie: er was niet genoeg voorraad voor een regel; zie Tekorten van een order.
• Bij het picken (short pick): de picker vindt minder dan verwacht. Wat gevonden is, is gepickt (qty_picked op de regel). Zijn alle andere regels gepickt, dan wordt de order Partially Allocated en niet Picked. Lost het magazijn het tekort op met voorraad van een andere plek, dan wordt de order Picked zodra die rest gepickt is; is er elders minder dan het tekort, dan blijft de rest open staan. Een order van 3 stuks waarvan er 1 gevonden wordt, geeft dus de webhook Allocated → Partially Allocated, en later Partially Allocated → Picked. Een order met een open short pick wordt niet Shipped, ook niet als de rest al geladen is.
• Tekort geaccepteerd: is er geen voorraad, dan kan het magazijn het tekort accepteren (Tekort accepteren). U krijgt dan de webhook order_shortage met order_id, line_id, sku_id, qty_ordered, qty_short, reason en client_id. Daarna wordt de order Picked (of Shipped als de rest al geladen is). Is er van de order niets gepickt, dan blijft hij Partially Allocated.

Order in delen geladen. Een order kan in meer dozen de deur uitgaan, bijvoorbeeld als de eerste doos al geladen wordt terwijl een andere regel nog gepickt moet worden. U krijgt per geladen regel de webhook shipped. De order wordt pas Shipped als alles geladen is (op geaccepteerde tekorten na); pas dan komt de webhook order_shipped, één keer per order, met de doos die als laatste geladen is.

Wijzigen alleen zolang de order Released is. Zodra een order in een wave zit, is het magazijn ermee bezig: er is voorraad gereserveerd, er staan picktaken klaar of er is al gepickt. Een order bijwerken, regels toevoegen, wijzigen of verwijderen en de order verwijderen geeft dan 409 Conflict en er verandert niets. Zet het magazijn de wave terug (reset), dan is de order weer Released en kunt u hem weer wijzigen.

Alle orders ophalen

GET /orders

Query parameters

Response 200 OK

[
  {
    "order_id": "ORD-001",
    "client_id": "CLIENT01",
    "order_date": "2026-03-14",
    "order_status": {
      "id": 1,
      "description": "Released"
    },
    "order_status_description": "Released",
    "customer": {
      "id": "3f2a9c1e-5b7d-4e8a-9c0b-1d2e3f4a5b6c",
      "name": "Bedrijf BV - Amsterdam"
    },
    "ship_by_date": "2026-03-16",
    "carrier": "PostNL",
    "ship_dock": "DOCK-01",
    "creation_datetime": "2026-03-14 10:30:00",
    "created_by": "admin",
    "lines": [
      {
        "order_id": "ORD-001",
        "line": 1,
        "sku_id": "SKU-001",
        "qty": 10,
        "qty_picked": 0,
        "qty_shipped": 0
      }
    ]
  }
]

Een datum die bij de order niet is ingevuld (bijvoorbeeld ship_by_date) is null.

Order aanmaken

POST /orders

Request

Order met regels in één request:

{
  "order_id": "ORD-001",
  "customer_id": "3f2a9c1e-5b7d-4e8a-9c0b-1d2e3f4a5b6c",
  "order_date": "2026-03-14",
  "ship_by_date": "2026-03-16",
  "carrier_id": 1,
  "ship_dock": "DOCK-01",
  "lines": [
    {
      "sku_id": "SKU-001",
      "qty": 10
    },
    {
      "sku_id": "SKU-002",
      "qty": 5
    }
  ]
}

Orderregel velden

Artikelen en regelnummers

• Elk sku_id moet op de site bestaan.
• Heeft de order een opdrachtgever (zie Opdrachtgever van de order), dan moet het artikel bij die opdrachtgever horen. Een artikel zonder opdrachtgever mag op elke order. Een artikel van een andere opdrachtgever wordt gemeld zoals een onbekend artikel.
• Een regelnummer komt binnen een order maar één keer voor. Regels zonder line krijgen het laagste nummer dat nog vrij is: [{ "line": 2 }, {}, {}] geeft de regels 2, 1 en 3.

Klopt een regel niet, dan volgt 400 met een fout op die regel en wordt niets opgeslagen.

Afleveradres meesturen

Met ship_to stuurt u het afleveradres met de order mee, met uw eigen klantcode in address_id. U hoeft dan geen klant-ID's van NextWMS te kennen.

{
  "order_id": "ORD-002",
  "ship_to": {
    "address_id": "KL-0042",
    "name": "J. de Vries",
    "attention": "Afdeling inkoop",
    "address": "Kerkstraat 12",
    "zipcode": "1234 AB",
    "town": "Utrecht",
    "country": "NL",
    "phone": "030-1234567"
  },
  "lines": [{ "sku_id": "SKU-001", "qty": 1 }]
}

• Klantcode bestaat nog niet: NextWMS maakt een nieuwe klant aan.
• Klantcode bestaat al: de klant wordt bijgewerkt naar het meegestuurde adres. Een veld dat u niet meestuurt, wordt leeggemaakt. Stuur dus altijd het volledige adres mee.
• De klant wordt samen met de order opgeslagen: mislukt de order, dan wordt ook de klant niet aangemaakt of gewijzigd.
• De klant is daarna ook te zien in GET /customers, met uw klantcode in address_id.

Opdrachtgever van de order

In een fulfilmentmagazijn hoort elke order bij een opdrachtgever (client_id). Die volgt uit wie de order plaatst:

• Een API key die aan een opdrachtgever gekoppeld is, of een gebruiker van het klantportaal: de order krijgt altijd die opdrachtgever. client_id hoeft niet meegestuurd te worden; wie een andere opdrachtgever meestuurt, krijgt 403.
• Een API key of gebruiker zonder opdrachtgever: de order krijgt de client_id uit het request. Die moet op de site bestaan, anders volgt 400. Zonder client_id heeft de order geen opdrachtgever.

Response 204 No Content

Succesvol aangemaakt. De order en zijn regels worden samen opgeslagen: mislukt er iets, dan wordt niets opgeslagen en kan hetzelfde request opnieuw worden verstuurd.

Response 400 Bad Request

De invoer voldoet niet aan de regels hierboven, client_id of customer_id bestaat niet op de site, een sku_id bestaat niet of hoort niet bij de opdrachtgever, een regelnummer komt dubbel voor, of de klantcode in ship_to hoort bij een leverancier. Er wordt dan niets opgeslagen. errors bevat alle fouten tegelijk, met per fout het veld (regels als lines[0].qty):

{
  "message": "Ongeldige order",
  "errors": [
    { "field": "order_date", "message": "order_date moet een geldige datum zijn (YYYY-MM-DD)" },
    { "field": "lines[0].qty", "message": "qty is verplicht: een geheel getal groter dan 0" },
    { "field": "lines[1].line", "message": "Regelnummer 1 komt meer dan één keer voor" }
  ]
}

Een onbekend artikel, of een artikel van een andere opdrachtgever, geeft bijvoorbeeld { "field": "lines[2].sku_id", "message": "sku_id SKU-999 bestaat niet voor opdrachtgever hollandgold" }. Zonder opdrachtgever luidt de melding sku_id SKU-999 bestaat niet op deze site.

Response 403 Forbidden

De API key of gebruiker hoort bij een andere opdrachtgever dan de meegestuurde client_id:

{
  "message": "Geen toegang tot client andereklant"
}

Response 409 Conflict

Het order_id bestaat al:

{
  "message": "Order with OrderID ORD-001 already exists"
}

Of de klantcode in ship_to kon niet worden aangemaakt omdat hij al in gebruik is; errors[0].field is dan ship_to.address_id.

Specifieke order ophalen

GET /orders/:id

Response 200 OK

Retourneert de order inclusief regels (zelfde formaat als bij lijst).

Response 404 Not Found

De order bestaat niet, of hoort bij een andere opdrachtgever dan de API key of portaalgebruiker (zie Alleen orders van de eigen opdrachtgever):

{
  "message": "Order with OrderID ORD-001 not found"
}

Tekorten van een order

GET /orders/:id/shortages

De orderregels waarvoor bij het starten van een wave niet genoeg voorraad gevonden werd. Een tekort blijft staan tot de wave opnieuw wordt gestart, gealloceerd of gereset; zie Tekorten bij de allocatie.

Response 200 OK

[
  {
    "id": 17,
    "wave_id": 42,
    "line_id": 1,
    "sku_id": "SKU-001",
    "sku_description": "Widget A",
    "qty_requested": 10,
    "qty_allocated": 6,
    "qty_short": 4,
    "created_datetime": "2026-10-15T08:30:00.000Z"
  }
]

Geen tekorten, of een onbekende order, geeft een lege lijst. Een API key of portaalgebruiker met opdrachtgever krijgt voor een onbekende order of een order van een andere opdrachtgever 404.

Order bijwerken

PUT /orders/:id

Request

{
  "customer_id": "3f2a9c1e-5b7d-4e8a-9c0b-1d2e3f4a5b6c",
  "order_date": "2026-03-14",
  "ship_by_date": "2026-03-17",
  "carrier_id": 2,
  "ship_dock": "DOCK-02"
}

Alleen de velden die u meestuurt, worden gewijzigd; de andere blijven zoals ze waren. Alleen { "ship_by_date": "2026-03-18" } sturen wijzigt dus alleen de verzenddatum. De velden en hun regels zijn dezelfde als bij Order aanmaken. Stuurt u ship_dock leeg (null of ""), dan krijgt de order de standaard verzendlocatie van de site.

De opdrachtgever van een order wijzigt niet via dit endpoint; client_id in het request wordt genegeerd, net als andere velden. Met een API key of portaalgebruiker die aan een opdrachtgever gekoppeld is, geeft een andere client_id 403.

Response 204 No Content

Response 400 Bad Request

Er is geen van de vijf velden meegestuurd, een waarde klopt niet, of customer_id bestaat niet:

{
  "message": "Ongeldige order",
  "errors": [{ "field": "ship_by_date", "message": "ship_by_date moet een geldige datum zijn (YYYY-MM-DD)" }]
}

Response 409 Conflict

De order zit al in een wave en kan niet meer worden gewijzigd (zie Orderstatus):

{
  "message": "Order ORD-001 kan niet meer worden gewijzigd of verwijderd: hij zit al in een wave (status Allocated).",
  "order_status": "Allocated"
}

Order verwijderen

DELETE /orders/:id

Verwijdert de order inclusief alle orderregels.

Response 204 No Content

Response 409 Conflict

De order zit al in een wave en kan niet meer worden verwijderd (zie Orderstatus):

{
  "message": "Order ORD-001 kan niet meer worden gewijzigd of verwijderd: hij zit al in een wave (status Allocated).",
  "order_status": "Allocated"
}

Orderregels toevoegen

POST /orders/:id/lines

Request

Enkele regel:

{
  "sku_id": "SKU-003",
  "qty": 20
}

Of meerdere regels als array:

[
  { "sku_id": "SKU-003", "qty": 20 },
  { "sku_id": "SKU-004", "qty": 15 }
]

Elk sku_id moet bestaan en bij de opdrachtgever van de order horen, zoals bij het aanmaken (zie Artikelen en regelnummers).

Response 204 No Content

Response 400 Bad Request

Een regel klopt niet; er wordt niets opgeslagen. Bij een array heet het veld naar de positie in de array ([1].sku_id), bij één regel alleen naar het veld (sku_id):

{
  "message": "Ongeldige orderregels",
  "errors": [
    { "field": "[0].line", "message": "Regel 2 bestaat al op deze order" },
    { "field": "[1].sku_id", "message": "sku_id SKU-999 bestaat niet voor opdrachtgever hollandgold" }
  ]
}

Ook een lege array of een regel zonder sku_id geeft 400.

Response 404 Not Found

De order bestaat niet, of hoort bij een andere opdrachtgever dan die van uw API key.

Response 409 Conflict

De order zit al in een wave en kan niet meer worden gewijzigd (zie Orderstatus):

{
  "message": "Order ORD-001 kan niet meer worden gewijzigd of verwijderd: hij zit al in een wave (status Allocated).",
  "order_status": "Allocated"
}

Orderregel bijwerken

PUT /orders/:id/lines/:line_id

Request

{
  "sku_id": "SKU-003",
  "qty": 25
}

Stuur sku_id, qty of allebei; wat u niet meestuurt, blijft zoals het was. qty is een geheel getal groter dan 0. Een gewijzigd sku_id moet bestaan en bij de opdrachtgever van de order horen.

Response 204 No Content

Response 400 Bad Request

{
  "message": "Ongeldige orderregel",
  "errors": [{ "field": "sku_id", "message": "sku_id SKU-999 bestaat niet voor opdrachtgever hollandgold" }]
}

Response 409 Conflict

De order zit al in een wave en kan niet meer worden gewijzigd (zie Orderstatus):

{
  "message": "Order ORD-001 kan niet meer worden gewijzigd of verwijderd: hij zit al in een wave (status Allocated).",
  "order_status": "Allocated"
}

Orderregel verwijderen

DELETE /orders/:id/lines/:line_id

Response 204 No Content

Response 409 Conflict

De order zit al in een wave en kan niet meer worden gewijzigd (zie Orderstatus):

{
  "message": "Order ORD-001 kan niet meer worden gewijzigd of verwijderd: hij zit al in een wave (status Allocated).",
  "order_status": "Allocated"
}