# Conundra Order Book API Order Book provides ready-to-run domain-specific logistic data governance for your route optimization. Version: 1.6.1 ## Servers Order Book API Production ``` https://api.conundra.eu/orderbook/v1 ``` ## Security ### clientCredentials This API uses OAuth2 with the Client Credentials flow for M2M communication. Client ID and secret should be provided as a HTTP Basic Auth header. Type: oauth2 ## Download OpenAPI description [Conundra Order Book API](https://developer.conundra.eu/_bundle/apis/order-book/order-book-api.yaml) ## Health check Miscellaneous endpoints for general API functionality ### Ping - [GET /ping](https://developer.conundra.eu/apis/order-book/order-book-api/health/ping.md): The ping-endpoint can be used for validating a connection with the application. It will authenticate the caller and respond pong if everything is set-up correctly. ## Pickup Orders Pickup orders represent an order where the executor needs to pick up cargo at a certain stop. ### Get a Pickup by business id for a given TransportRequest - [GET /transport-requests/{business_id}/orders/pickups/{order_id}](https://developer.conundra.eu/apis/order-book/order-book-api/pickups/getpickupbytransportrequestidandorderid.md): This endpoint allows you to get the information about a given pickup that is contained in a TransportRequest. Note: It is not possible to retrieve pickups within TransportRequests directly through the _Get a Pickup by business Id_ endpoint. ### Upsert a Pickup by business id for a given TransportRequest - [PUT /transport-requests/{business_id}/orders/pickups/{order_id}](https://developer.conundra.eu/apis/order-book/order-book-api/pickups/upsertpickupbytransportrequestidandorderid.md): Upsert pickup information. When if-match is not specified, then no optimistic protection is applied, ie: the last update wins. Note: It is not possible to update pickups within TransportRequests directly through the _Upsert a Pickup by business Id_ endpoint. ### Delete a Pickup by business id for a given TransportRequest - [DELETE /transport-requests/{business_id}/orders/pickups/{order_id}](https://developer.conundra.eu/apis/order-book/order-book-api/pickups/deletepickupbytransportrequestidandorderid.md): This endpoint allows you to delete a given pickup within a transport request. Note: It is not possible to delete pickups within TransportRequests directly through the _Delete a Pickup by business Id_ endpoint. ### Get a Pickup by business Id - [GET /orders/pickups/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/pickups/getpickupbyid.md): Retrieve a single Pickup order by its business id. ### Upsert a Pickup by business Id - [PUT /orders/pickups/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/pickups/upsertpickupbyid.md): Create or update a Pickup Order. This endpoint allows you to update (default behaviour) or insert a Pickup Order. The caller is responsible for providing a unique business identifier for each Order, regardless of order type. If this business identifier can't be found, a new order will be created. If a Pickup order with the given business identifier can be found then it will be updated. ### Delete a Pickup by business Id - [DELETE /orders/pickups/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/pickups/deletepickupbyid.md): This endpoint allows you to delete the information about a given pickup. ## Delivery Orders Delivery orders represent an order where the executor needs to drop off cargo at a certain stop. ### Get a Delivery by business id for a given TransportRequest - [GET /transport-requests/{business_id}/orders/deliveries/{order_id}](https://developer.conundra.eu/apis/order-book/order-book-api/deliveries/getdeliverybytransportrequestidandorderid.md): This endpoint allows you to get the information about a given delivery. Note: It is not possible to retrieve deliveries within TransportRequests directly through the _Get a Delivery by business Id_ endpoint. ### Upsert a Delivery by business id for a given TransportRequest - [PUT /transport-requests/{business_id}/orders/deliveries/{order_id}](https://developer.conundra.eu/apis/order-book/order-book-api/deliveries/upsertdeliverybytransportrequestidandorderid.md): Upsert delivery information. When if-match is not specified, then no optimistic protection is applied, ie: the last update wins. Note: It is not possible to update deliveries within TransportRequests directly through the _Upsert a Delivery by business Id_ endpoint. ### Delete an Delivery by business id for a given TransportRequest - [DELETE /transport-requests/{business_id}/orders/deliveries/{order_id}](https://developer.conundra.eu/apis/order-book/order-book-api/deliveries/deletedeliverybytransportrequestidandorderid.md): This endpoint allows you to delete a given delivery within a transport request. Note: It is not possible to delete deliveries within TransportRequests directly through the _Delete a Delivery by business Id_ endpoint. ### Get a Delivery by business id - [GET /orders/deliveries/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/deliveries/getdeliverybyid.md): Retrieve a single Delivery Order by its business id. ### Upsert a Delivery by business Id - [PUT /orders/deliveries/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/deliveries/upsertdeliverybyid.md): Create or update a Delivery Order. This endpoint allows you to update (default behaviour) or insert a Delivery Order. The caller is responsible for providing a unique business identifier for each Order, regardless of order type. If this business identifier can't be found, a new order will be created. If a Delivery order with the given business identifier can be found then it will be updated. ### Delete a Delivery with specified business Id - [DELETE /orders/deliveries/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/deliveries/deletedeliverybyid.md): This endpoint allows you to delete the information about a given Delivery. ## PickupDelivery Orders PickupDelivery orders represent an order where the executor needs to pick up cargo at a certain stop and deliver it at another stop. ### Get a PickupDelivery by business id for a given TransportRequest - [GET /transport-requests/{business_id}/orders/pickup-deliveries/{order_id}](https://developer.conundra.eu/apis/order-book/order-book-api/pickupdeliveries/getpickupdeliverybytransportrequestidandorderid.md): This endpoint allows you to get the information about a given PickupDelivery. Note: It is not possible to retrieve pickupDeliveries within TransportRequests directly through the _Get a PickupDelivery by business Id_ endpoint. ### Upsert a PickupDelivery by business id for a given TransportRequest - [PUT /transport-requests/{business_id}/orders/pickup-deliveries/{order_id}](https://developer.conundra.eu/apis/order-book/order-book-api/pickupdeliveries/upsertpickupdeliverybytransportrequestidandorderid.md): Upsert PickupDelivery information. When if-match is not specified, then no optimistic protection is applied, ie: the last update wins. Note: It is not possible to update pickupDeliveries within TransportRequests directly through the _Upsert a PickupDelivery by business Id_ endpoint. ### Delete a PickupDelivery by business id for a given TransportRequest - [DELETE /transport-requests/{business_id}/orders/pickup-deliveries/{order_id}](https://developer.conundra.eu/apis/order-book/order-book-api/pickupdeliveries/deletepickupdeliverybytransportrequestidandorderid.md): This endpoint allows you to delete a given pickupDelivery within a transport request. Note: It is not possible to delete pickupDeliveries within TransportRequests directly through the _Delete a PickupDelivery by business Id_ endpoint. ### Get a PickupDelivery by business Id - [GET /orders/pickup-deliveries/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/pickupdeliveries/getpickupdeliverybyid.md): Create or update a PickupDelivery Order. This endpoint allows you to update (default behaviour) or insert a PickupDelivery Order. The caller is responsible for providing a unique business identifier for each Order, regardless of order type. If this business identifier can't be found, a new order will be created. If a PickupDelivery order with the given business identifier can be found then it will be updated. ### Upsert a PickupDelivery by business Id - [PUT /orders/pickup-deliveries/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/pickupdeliveries/upsertpickupdeliverybyid.md): Upsert PickupDelivery information. ### Delete a PickupDelivery by business Id - [DELETE /orders/pickup-deliveries/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/pickupdeliveries/deletepickupdeliverybyid.md): This endpoint allows you to delete the information about a given PickupDelivery. ## Consolidated Orders Orders are being consolidated by the application to enrich them with captured domain knowledge through Conditionals and/or Locations. These endpoints provide insights into and discoverability of the results of this consolidation. ### Get a cursor paged list of consolidated orders - [GET /consolidated-orders](https://developer.conundra.eu/apis/order-book/order-book-api/consolidated-orders/getconsolidatedorders.md): This endpoint allows you to retrieve a cursor paged list of information on consolidated orders, based on their _plannability_. We currently only support returning information on Orders that have become unplannable after consolidating the orders' timeframes with their Location and applicable Conditionals. You can find out more about how to use cursors in our developer portal. ## Category Management **[EXPERIMENTAL]** Endpoints for managing Categories. *Experimental Status:* These endpoints have an experimental status since their complexity was impacted by a removed feature. We intend at the very least to vastly simplify these endpoints by removing the `code`-subresource. ### [EXPERIMENTAL] Get list of all categories of an entity - [GET /categories/{entity}](https://developer.conundra.eu/apis/order-book/order-book-api/categories/getcategoriesofentity.md): [EXPERIMENTAL] This endpoint allows you to retrieve list of categories of an entity. ### [EXPERIMENTAL] Get a category of an entity with specified code - [GET /categories/{entity}/{code}](https://developer.conundra.eu/apis/order-book/order-book-api/categories/getcategoryofentitybycode.md): [EXPERIMENTAL] This endpoint allows you to get the category of an entity with a given code, including the ETag header for optimistic locking purpose ### [EXPERIMENTAL] Create or Update a category of an entity with specified code - [PUT /categories/{entity}/{code}](https://developer.conundra.eu/apis/order-book/order-book-api/categories/createorupdatetypeofentity.md): [EXPERIMENTAL] This endpoint allows you to create or update an existing category of an entity. When the code does not exist, a new category will be created for the entity. No ETag header is required yet. For a given code, the properties will be overwritten and then an ETag header is required. Do remark that the code in the body of the request, must correspond with the code in the path identifier ### [EXPERIMENTAL] Delete an existing category of entity with specified code - [DELETE /categories/{entity}/{code}](https://developer.conundra.eu/apis/order-book/order-book-api/categories/deleteentitycategorytype.md): [EXPERIMENTAL] This endpoint allows you to delete an existing category of an entity A category can only be deleted when no active entities are still using it. ## Transport Requests Transport Requests can be used to group Orders that share some administrative context. They can serve as a way of targeting Orders through conditionals, by providing context on the client companies for which those orders are being executed. ### Get a list of all transport requests by ids - [GET /transport-requests](https://developer.conundra.eu/apis/order-book/order-book-api/transport-request/getlistoftransportrequests.md): This is an endpoint that allows you to retrieve a list of Transport Requests in bulk. The Transport Requests are identified by their business id, provided in the query. When one or more transport requests could not be found, this will be indicated in the errors-section of the response. ### Get a list of transport request by filter criteria - [GET /transport-requests/by](https://developer.conundra.eu/apis/order-book/order-book-api/transport-request/getcursorpagedtransportrequests.md): Retrieve a list of Transport Requests in bulk, identified by the query parameters defined in the request. Providing no query parameters will return all known Transport Requests. Providing any additional filter will return the matching subset of Transport Requests. When providing multiple filter parameters, all filters must match for a Transport Request to be included in the response. Since Transport Requests are volatile data, this endpoints returns a cursor-based paged list. Paging through the results requires you to call the API using the prev, self or next values in the cursor. These will return the next batch of up to limit results. You can find out more about how to use cursors in our developer portal. ### Get a transport request with specified business id - [GET /transport-requests/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/transport-request/gettransportrequestbyid.md): Retrieve a single Transport Request by its business id. ### Upsert a Transport Request with specified business id - [PUT /transport-requests/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/transport-request/upserttransportrequestbyid.md): Create or update a Transport Request. This endpoint allows you to update (default behaviour) or insert a new transport request. The caller is responsible for providing a unique business identifier for each Transport Request. If this business identifier can't be found, a new transport request will be created. If a transport request with the given business identifier can be found then it will be updated. When you specify an 'if-match' header with a weak ETAG representing the version, optimistic locking will be applied to your operation. Should a conflict be detected, a 412 PreconditionFailed response is returned. ### Delete a transport request with specified Id - [DELETE /transport-requests/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/transport-request/deletetransportrequestbyid.md): This endpoint allows you to delete the information about a given TransportRequest. Deleting a Transport Request will also delete all orders within it. ## Companies Companies can be managed in Order Book and used as clients for Transport Requests. This allows you to target Conditionals to Orders contained within Transport Requests for select clients. ### Get a Company with specified business id - [GET /companies/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/companies/getcompanybyid.md): Retrieve a single Company by its business id. ### Upsert a company by Id - [PUT /companies/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/companies/updatecompanybyid.md): This endpoint allows you to update (default behaviour) or insert a new Company. You are responsible to give a unique business identifier with your company. If this business identifier can't be found then a new company will be created. If a company with the given business identifier can be found then it will be updated. When you specify 'if-match', which is filled in with a weak ETAG representing a version, then you can protect yourself from updates by someone else before committing your updates. (see also Optimistic locking). When such a conflict is detected, a 412 PreconditionFailed response is returned. ### Delete a company by Id - [DELETE /companies/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/companies/deletecompanybyid.md): This endpoint allows you to delete a given company ## Locations Locations can be managed separately in Order Book, which allows the user to capture their related business rules in a reusable manner. This is especially valuable in business cases where a select set of Locations is reused across many orders. Typical use cases include capturing regular opening hours or requirements tied to a specific Location. ### Get a list of all locations by ids - [GET /locations](https://developer.conundra.eu/apis/order-book/order-book-api/locations/getpagedlocations.md): This is an endpoint that allows you to retrieve a list of Locations in bulk. The locations are identified by their business id, provided in the query. When one or more locations could not be found, this will be indicated in the errors-section of the response. ### Get a list of locations by filter criteria - [GET /locations/by](https://developer.conundra.eu/apis/order-book/order-book-api/locations/getpagedlocationsby.md): Retrieve a list of Locations in bulk, identified by the query parameters defined in the request. The query requires at least a page and page size, in which case all Locations will be returned in a paged format. Providing any additional filter will return the matching subset of Locations. When providing multiple filter parameters, all filters must match for a Location to be included in the response. The returned list can be empty, but the request will not fail if no results are found. ### Get a location with specified business Id - [GET /locations/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/locations/getlocationbyid.md): Retrieve a single location by its business id. ### Upsert a location with specified business Id - [PUT /locations/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/locations/upsertlocationbyid.md): Create of update a location. The caller is responsible for providing a unique business id for each Location to retain consistency. If a call is made using an unknown business id, a new Location will be created, otherwise an update will be applied to the existing Location. Locations are versioned and the ETag-header will represent the type of operation that was executed. Conversely, adding an If-Match header to requests can protect the caller against unintended operations by acting as an optimistic lock. ### Delete a location with specified business id. - [DELETE /locations/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/locations/deletelocationbyid.md): This endpoint allows you to delete a location. Locations can only be deleted if they are no longer in use by future orders or conditionals. ## Conditionals Conditionals allow you to capture business rules in Order Book. You can target Orders based on several attributes or create time-based rules, and apply mutations to this order set enriching for your optimization. ### Create a new conditional - [POST /conditionals](https://developer.conundra.eu/apis/order-book/order-book-api/conditionals/createconditional.md): This endpoint allows you to create a new conditional. The application will assign a generated ID to the conditional, that can be used for retrieving, updating or deleting the conditional. This generated ID is returned in the Location header and (_optional_) response body. ### Get a conditional by Id - [GET /conditionals/{id}](https://developer.conundra.eu/apis/order-book/order-book-api/conditionals/getconditionalbyid.md): This endpoint allows you to get the information about a given conditional. ### Update an existing conditional by Id - [PUT /conditionals/{id}](https://developer.conundra.eu/apis/order-book/order-book-api/conditionals/updateconditionalbyid.md): This endpoint updates a given conditional. ### Delete a conditional by Id - [DELETE /conditionals/{id}](https://developer.conundra.eu/apis/order-book/order-book-api/conditionals/deleteconditionalbyid.md): This endpoint allows you to delete a given conditional ## Partial Routes [EXPERIMENTAL] **[EXPERIMENTAL]** **[UNDER DEVELOPMENT]** Endpoints for managing preplanned `PartialRoutes`. ### [EXPERIMENTAL] Upsert PartialRoute - [PUT /preplanned/partial-routes/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/partial-routes/upsertpartialroute.md): [EXPERIMENTAL] Upsert a PartialRoute defined by a business id. ### [EXPERIMENTAL] Get PartialRoute - [GET /preplanned/partial-routes/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/partial-routes/getpartialroute.md): [EXPERIMENTAL] Get a PartialRoute by a business id. ### [EXPERIMENTAL] Delete PartialRoute - [DELETE /preplanned/partial-routes/{business_id}](https://developer.conundra.eu/apis/order-book/order-book-api/partial-routes/deletepartialroute.md): [EXPERIMENTAL] Delete a PartialRoute by a business id.