Skip to content
/
Get a transport request w...

Conundra Order Book API (1.6.1)

Order Book provides ready-to-run domain-specific logistic data governance for your route optimization.

Download OpenAPI description
order-book-api.json
order-book-api.yaml
Overview
URL
https://servicedesk.conundra.eu
Servers
Mock server
https://developer.conundra.eu/_mock/apis/order-book/order-book-api
Order Book API Production
https://api.conundra.eu/orderbook/v1

Health check

Miscellaneous endpoints for general API functionality

Operations

Pickup Orders

Pickup orders represent an order where the executor needs to pick up cargo at a certain stop.

Operations

Delivery Orders

Delivery orders represent an order where the executor needs to drop off cargo at a certain stop.

Operations

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.

Operations

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.

Operations

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.

Operations

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.

Operations

Get a list of transport request by filter criteria

Request

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.

Security
clientCredentials
Query
start_atstring(date-time)

An ISO-8601 formatted date, that acts as the lower bound for which the Transport Request must be applicable, ie: earliest_start_at must be equal to or larger than start_at.

end_atstring(date-time)

An ISO-8601 formatted date, that acts as the lower bound for which the Transport Request must be applicable, ie: earliest_start_at must be smaller than end_at.

cursorstring

Cursor of the page to retrieve. Can be left blank initially to retrieve the first page. Paging through the results requires passing in the cursor from a previous response.

limitinteger(int32)[ 1 .. 1000 ]

Number of results per page.

Default 100

Responses

A cursor-based paged set of Transport Requests. The set might be empty if no Transport Requests match the query.

Bodyapplication/json
dataArray of objects(TransportRequest)required

Subset of Transport Requests matching the provided query, limited to the size specified in the request.

business_idstring^[a-zA-Z0-9.~\-_]{1,512}$required

Unique reference ID

Example: "transportRequestA"
transport_categorystring

An optional category for the Transport Request, represented by its code. This category can be used for filtering in the user interface but is not exposed as a filter in the API's filter endpoints. There is no integration between Conditionals and Transport Request categories.

Example: "transportCategoryA"
clientstring

An optional reference, by business_id, to a Company that is known in Order Book. Conditionals can target Orders contained within a TransportRequest with a certain Company as its client, thus providing the planner a way for applying business rules to all Orders for certain customers.

Example: "companyId"
earliest_start_atstring(date-time)read-only

A calculated field that is the earliest start_at of all contained Orders.

Example: "2021-01-01T10:15:30Z"
descriptionstring

A freeform text description of the Transport Request, providing additional details that might be of use for a planner.

Example: "a description"
ordersobject(Orders)

Orders contain all orders related to a TransportRequest. Due to de difference in optimization, the orders can contain either pickupAndDeliveries or separate pickups and deliveries.

custom_dataobject(CustomData)

Custom data allows you te enrich a TransportRequest with relevant information for the planner that is not part of the Order Book domain. Custom data on a TransportRequest does not propagate to its Orders.

etagstring(Etag)

Must match header if provided on request.

cursorobject(Cursor)required
selfstring

The cursor for this page. Not present when the result contains no data.

Example: "c2VsZl9fcGFnZQ"
prevstring

The cursor for the previous page. Not present when fetching data for the first page.

Example: "cHJldmlvdXNfX3BhZ2U"
nextstring

The cursor for the next page. Not present when fetching data for the last page.

Example: "bmV4dF9fcGFnZQ"
Response
application/json
{
  "data": [
    { … }
  ],
  "cursor": {
    "self": "c2VsZl9fcGFnZQ",
    "prev": "cHJldmlvdXNfX3BhZ2U",
    "next": "bmV4dF9fcGFnZQ"
  }
}

Get a transport request with specified business id

Request

Retrieve a single Transport Request by its business id.

Security
clientCredentials
Path
business_idstring^[a-zA-Z0-9.~\-_]{1,512}$required

The business identifier of an entity instance

Headers
X-Conundra-Unwrapstring

When set to true, the response will not be wrapped in a data property.

Responses

OK

Headers
ETagstring

weak Etag (ex W/<etag_value>) which contains the (updated) version of the entity

Bodyapplication/json
dataobject(TransportRequest)

transport request contains orders

Response
application/json
{
  "data": {
    "business_id": "transportRequestA",
    "transport_category": "transportCategoryA",
    "client": "companyId",
    "earliest_start_at": "2021-01-01T10:15:30Z",
    "description": "a description",
    "orders": { … },
    "custom_data": { … },
    "etag": "W/\"1\""
  }
}

Upsert a Transport Request with specified business id

Request

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.

Security
clientCredentials
Path
business_idstring^[a-zA-Z0-9.~\-_]{1,512}$required

The business identifier of an entity instance

Headers
If-Matchstring

weak Etag as optimistic locking check

PreferArray of strings

The RFC7240 Prefer header indicates that a particular server behavior is preferred by the client but is not required for successful completion of the request (see RFC 7240).

The following behavior is supported by this API:

  • return=<minimal|representation> is used to suggest the server to return using status code 204 without a resource in the response body (minimal) or using status codes 200 or 201 with the resource in the response body on success (representation).
Bodyapplication/jsonrequired

Transport Request to be updated

business_idstring^[a-zA-Z0-9.~\-_]{1,512}$required

Unique reference ID

Example: "transportRequestA"
transport_categorystring

An optional category for the Transport Request, represented by its code. This category can be used for filtering in the user interface but is not exposed as a filter in the API's filter endpoints. There is no integration between Conditionals and Transport Request categories.

Example: "transportCategoryA"
clientstring

An optional reference, by business_id, to a Company that is known in Order Book. Conditionals can target Orders contained within a TransportRequest with a certain Company as its client, thus providing the planner a way for applying business rules to all Orders for certain customers.

Example: "companyId"
descriptionstring

A freeform text description of the Transport Request, providing additional details that might be of use for a planner.

Example: "a description"
ordersobject(Orders)

Orders contain all orders related to a TransportRequest. Due to de difference in optimization, the orders can contain either pickupAndDeliveries or separate pickups and deliveries.

custom_dataobject(CustomData)

Custom data allows you te enrich a TransportRequest with relevant information for the planner that is not part of the Order Book domain. Custom data on a TransportRequest does not propagate to its Orders.

etagstring(Etag)

Must match header if provided on request.

Responses

Transport Request updated

Response body contains updated Transport Request

Headers
Locationstring

contains the URI, with the ID of the created Transport Request ex /transport-requests ETag: $ref:

Preference-Appliedstring

to indicate whether a preference has been applied. (ex Preference-Applied: return=representation)

Bodyapplication/json
dataobject(TransportRequest)

transport request contains orders

Response
application/json
{
  "data": {
    "business_id": "transportRequestA",
    "transport_category": "transportCategoryA",
    "client": "companyId",
    "earliest_start_at": "2021-01-01T10:15:30Z",
    "description": "a description",
    "orders": { … },
    "custom_data": { … },
    "etag": "W/\"1\""
  }
}

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.

Operations

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.

Operations

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.

Operations

Partial Routes [EXPERIMENTAL]

[EXPERIMENTAL] [UNDER DEVELOPMENT] Endpoints for managing preplanned PartialRoutes.

Operations
Company
PTV Logistics
Copyright © Conundra BV - PTV Logistics GmbH. All right reserved.