Maak een transportorder aan

post

https://api.noventra.nl/v1/orders

Maakt één transportorder aan: een rit van een van jouw laadadressen naar een
losadres van je klant, op de opgegeven datums en met de opgegeven lading.

De order komt binnen met status UNASSIGNED en verschijnt direct in de Noventra
planning. Het toewijzen van een vervoerder en de statusovergangen daarna gebeuren
in Noventra zelf, niet via deze API.

Wat je nodig hebt

Je verwijst naar bestaande gegevens met hun ID:

customer_id — de opdrachtgever, uit je klantenbestand in Noventra.
pickup.location_id — een van jouw eigen vestigingen of laadadressen.
delivery.location_id — een losadres dat bij díe klant hoort.

Deze ID's vind je in het dashboard. Verwijst een ID naar iets dat niet bestaat, of
hoort het losadres niet bij de opgegeven klant, dan krijg je een 422 die precies
aangeeft welk veld niet klopt.

Idempotency

Stuur een Idempotency-Key mee. De regels:

Zelfde key, zelfde body → je krijgt het oorspronkelijke antwoord terug,
inclusief dezelfde id en order_number. Er wordt geen tweede order aangemaakt.
De response bevat Idempotent-Replayed: true.
Zelfde key, andere body → 409 Conflict. Een key hoort bij één specifieke
order-poging; hergebruik hem niet voor een andere order.
Zelfde key, terwijl het eerste request nog loopt → 409 Conflict met
type idempotency-request-in-progress. Wacht even en probeer opnieuw; zodra
het eerste request klaar is krijg je het antwoord daarvan.
Een mislukt request laat geen spoor na. Krijg je een 422 of een 500, dan
is je key weer vrij: corrigeer de body en stuur hem opnieuw in met dezelfde key.
Geen key → het request wordt normaal verwerkt. Een retry maakt dan een
tweede order aan.

Keys worden 24 uur bewaard. Daarna is een key weer vrij te gebruiken.

Order eenmaal aangemaakt

Een aangemaakte order pas je niet meer via deze API aan; v1 is create-only.
Wijzigen of annuleren gaat voorlopig via het dashboard of via je contactpersoon.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

De aan te maken transportorder.

Alles wat nodig is om één rit in te plannen: voor wie, van waar naar waar, wanneer,
en wat er mee moet.

customer_id

string

required

length between 1 and 64

ID van de opdrachtgever, uit je klantenbestand in Noventra. Behandel dit als
een ondoorzichtige string: parse er niets uit en ga niet uit van een vaste
lengte of vorm.

pickup

object

required

Waar en wanneer de lading opgehaald wordt.

delivery

object

required

Waar en wanneer de lading afgeleverd wordt.

cargo

object

required

Wat er vervoerd wordt, en waar de planning rekening mee moet houden.

invoice_reference

string

length ≤ 255

Jouw eigen kenmerk voor deze rit — meestal het inkoopordernummer of het
ordernummer uit je eigen systeem. Noventra bewaart het, toont het in de
planning en zet het op de factuur, zodat jij de rit in beide systemen
terugvindt. Ook doorzoekbaar in het dashboard.

remarks

string

length ≤ 4000

Vrije instructies voor de chauffeur: meldprocedures, poortcodes, openingstijden,
waar precies te lossen. Alles wat anders telefonisch geregeld moet worden.

Headers

Idempotency-Key

string

length between 8 and 255

^[A-Za-z0-9_.:-]+$

Unieke waarde per order-poging, zodat een retry na een timeout niet leidt tot een
dubbele order. Gebruik een UUID v4 of iets anders met voldoende willekeur —
genereer hem één keer per order en hergebruik hem bij elke retry van diezelfde
order.

Sterk aanbevolen. Zonder key maakt een retry een tweede order aan.

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

201De order is aangemaakt. Bewaar id aan jouw kant: daarmee koppel je jouw administratie aan die van Noventra. Bij een idempotente replay krijg je dezelfde 201 terug met Idempotent-Replayed: true.

400Het request is niet te verwerken: geen geldige JSON, een verkeerd Content-Type, een veld met het verkeerde type, of een ontbrekende verplichte header.

403Het token is geldig, maar mag deze actie niet uitvoeren. Bijvoorbeeld: een test-token dat een live-order probeert aan te maken, of een token waarvan de rechten zijn ingeperkt.

422De JSON klopt syntactisch, maar de inhoud niet. Kijk in errors welke velden precies fout zijn — daar staat per veld een machineleesbare code en een uitleg.

429Je hebt de rate limit van dit token bereikt. Wacht het aantal seconden uit Retry-After en probeer het opnieuw. Bouw exponentiële backoff in als je veel orders achter elkaar inschiet.

500Er ging iets mis aan onze kant. Het request is mogelijk niet verwerkt. Probeer het opnieuw met dezelfde Idempotency-Key: was de order tóch aangemaakt, dan krijg je die terug in plaats van een duplicaat. Blijft het misgaan, stuur ons dan de request_id.

defaultEen foutantwoord met een statuscode die hierboven niet apart beschreven staat. Het lichaam is altijd een RFC 9457 probleem-document.