Skip to content

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

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

[EXPERIMENTAL] Upsert PartialRoute

Request

[EXPERIMENTAL] Upsert a PartialRoute defined by a business id.

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

Bodyapplication/json
plan_groupstring

The (optional) plan group this PartialRoute belong to. Plan Groups can be used for filtering the data included in a logistical optimization.

Example: "a plan group"
same_route_groupstring

The (optional) route group this PartialRoute belongs to. All PartialRoutes within a same_route_group must share the same executor, ie: they will belong to the same route.

Example: "route-group-01"
requirementsobject(Requirements)

The requirements that need to be fulfilled for this PartialRoute to be considered feasible for an executor in a logistical optimization.

labelsArray of stringsunique

Labels can be used for identifying sets of PartialRoutes, or Orders within these PartialRoutes.

Default []
Example: ["labelA"]
stopsArray of objects(Stop)non-emptyuniquerequired

A Stop has a specific location where one or more pickups or deliveries need to be made, taking into account the timings for a stop.

visit_locationobject(VisitLocation)required

Either address information should be present, or otherwise the geo point. The resolved information will be read-only and be filled out after resolving.

namestring

A name by which to identify this location

Example: "Conundra"
address_linestring

The address line for this location's address.

Example: "Voordries 41"
citystring

The city of this location.

Required when no geo point is provided.

Example: "Oosterzele"
zip_codestring

The zip code of this location.

Required when no geo point is provided.

Example: "9860"
country_codestring(CountryCode)^[A-Z]{2}$

An ISO3166-1 alpha-2 two letter country code.

Required when no geo point is provided.

geo_pointobject(GeoPoint)

The geo point identifying this location. If this is provided, all textual address information is optional.

pickupsArray of objects(PickupActivity)
deliveriesArray of objects(DeliveryActivity)
timingsobjectrequired
arrival_atstring(date-time)required

The planned time of arrival at the Stop

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

The stop time for this Stop.

Must be specified as a valid ISO Duration (see wikipedia ISO-8601 and RFC-3339). Must be non negative.

Example: "PT45M"
breaksArray of objects(Break)
Default []

Responses

PartialRoute created or updated, when the Prefer header was set to return=representation.

Headers
ETagstring

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

Preference-Appliedstring

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

Locationstring

contains the URI to the entity

Bodyapplication/json
business_idstring^[a-zA-Z0-9.~\-_]{1,512}$read-onlyrequired

Unique identifier for this PartialRoute.

Example: "PPT-1"
plan_groupstring

The (optional) plan group this PartialRoute belong to. Plan Groups can be used for filtering the data included in a logistical optimization.

Example: "a plan group"
same_route_groupstring

The (optional) route group this PartialRoute belongs to. All PartialRoutes within a same_route_group must share the same executor, ie: they will belong to the same route.

Example: "route-group-01"
requirementsobject(Requirements)

The requirements that need to be fulfilled for this PartialRoute to be considered feasible for an executor in a logistical optimization.

labelsArray of stringsunique

Labels can be used for identifying sets of PartialRoutes, or Orders within these PartialRoutes.

Default []
Example: ["labelA"]
stopsArray of objects(Stop)non-emptyuniquerequired

A Stop has a specific location where one or more pickups or deliveries need to be made, taking into account the timings for a stop.

visit_locationobject(VisitLocation)required

Either address information should be present, or otherwise the geo point. The resolved information will be read-only and be filled out after resolving.

namestring

A name by which to identify this location

Example: "Conundra"
address_linestring

The address line for this location's address.

Example: "Voordries 41"
citystring

The city of this location.

Required when no geo point is provided.

Example: "Oosterzele"
zip_codestring

The zip code of this location.

Required when no geo point is provided.

Example: "9860"
country_codestring(CountryCode)^[A-Z]{2}$

An ISO3166-1 alpha-2 two letter country code.

Required when no geo point is provided.

geo_pointobject(GeoPoint)

The geo point identifying this location. If this is provided, all textual address information is optional.

resolved_addressobject(ResolvedAddress)read-only

The resolved address is geocoded based on the given address, with the quality of the resolving being specified by the field score.

Addresses are only resolved when no geo point is provided on the provided address.

pickupsArray of objects(PickupActivity)
deliveriesArray of objects(DeliveryActivity)
timingsobjectrequired
arrival_atstring(date-time)required

The planned time of arrival at the Stop

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

The stop time for this Stop.

Must be specified as a valid ISO Duration (see wikipedia ISO-8601 and RFC-3339). Must be non negative.

Example: "PT45M"
breaksArray of objects(Break)
Default []
Response
application/json
{
  "business_id": "PPT-1",
  "plan_group": "a plan group",
  "same_route_group": "route-group-01",
  "requirements": {
    "tags": [],
    "forbidden_tags": []
  },
  "labels": [],
  "stops": [
    { … }
  ],
  "breaks": []
}

[EXPERIMENTAL] Get PartialRoute

Request

[EXPERIMENTAL] Get a PartialRoute by a business id.

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

The business identifier of an entity instance

Responses

OK

Headers
ETagstring

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

Bodyapplication/json
business_idstring^[a-zA-Z0-9.~\-_]{1,512}$read-onlyrequired

Unique identifier for this PartialRoute.

Example: "PPT-1"
plan_groupstring

The (optional) plan group this PartialRoute belong to. Plan Groups can be used for filtering the data included in a logistical optimization.

Example: "a plan group"
same_route_groupstring

The (optional) route group this PartialRoute belongs to. All PartialRoutes within a same_route_group must share the same executor, ie: they will belong to the same route.

Example: "route-group-01"
requirementsobject(Requirements)

The requirements that need to be fulfilled for this PartialRoute to be considered feasible for an executor in a logistical optimization.

labelsArray of stringsunique

Labels can be used for identifying sets of PartialRoutes, or Orders within these PartialRoutes.

Default []
Example: ["labelA"]
stopsArray of objects(Stop)non-emptyuniquerequired

A Stop has a specific location where one or more pickups or deliveries need to be made, taking into account the timings for a stop.

visit_locationobject(VisitLocation)required

Either address information should be present, or otherwise the geo point. The resolved information will be read-only and be filled out after resolving.

namestring

A name by which to identify this location

Example: "Conundra"
address_linestring

The address line for this location's address.

Example: "Voordries 41"
citystring

The city of this location.

Required when no geo point is provided.

Example: "Oosterzele"
zip_codestring

The zip code of this location.

Required when no geo point is provided.

Example: "9860"
country_codestring(CountryCode)^[A-Z]{2}$

An ISO3166-1 alpha-2 two letter country code.

Required when no geo point is provided.

geo_pointobject(GeoPoint)

The geo point identifying this location. If this is provided, all textual address information is optional.

resolved_addressobject(ResolvedAddress)read-only

The resolved address is geocoded based on the given address, with the quality of the resolving being specified by the field score.

Addresses are only resolved when no geo point is provided on the provided address.

pickupsArray of objects(PickupActivity)
deliveriesArray of objects(DeliveryActivity)
timingsobjectrequired
arrival_atstring(date-time)required

The planned time of arrival at the Stop

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

The stop time for this Stop.

Must be specified as a valid ISO Duration (see wikipedia ISO-8601 and RFC-3339). Must be non negative.

Example: "PT45M"
breaksArray of objects(Break)
Default []
Response
application/json
{
  "business_id": "PPT-1",
  "plan_group": "a plan group",
  "same_route_group": "route-group-01",
  "requirements": {
    "tags": [],
    "forbidden_tags": []
  },
  "labels": [],
  "stops": [
    { … }
  ],
  "breaks": []
}

[EXPERIMENTAL] Delete PartialRoute

Request

[EXPERIMENTAL] Delete a PartialRoute by a business id.

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

Responses

Deletion has succeeded and body is empty

Response
No content
Company
PTV Logistics
Copyright © Conundra BV - PTV Logistics GmbH. All right reserved.