ReDoc documentation

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.

Find out more

Get a list of all transport requests by ids

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.

Securitykeycloak
Request
query Parameters
ids
required
Array of strings [ 1 .. 100 ] items

A comma-separated list of Transport Request business IDs.

Responses
200

a list of transport requests

get/transport-requests
Response samples
application/json
{
  • "data": [
    ],
  • "errors": []
}

Get a list of transport request by filter criteria

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.

Securitykeycloak
Request
query Parameters
start_at
string <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_at
string <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.

cursor
string

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.

limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Number of results per page.

Responses
200

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

get/transport-requests/by
Response samples
application/json
{
  • "data": [
    ],
  • "cursor": {
    }
}

Get a transport request with specified business id

Retrieve a single Transport Request by its business id.

Securitykeycloak
Request
path Parameters
business_id
required
string

The business identifier of an entity instance

header Parameters
X-Conundra-Unwrap
string

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

Responses
200

OK

404

The entity is not found

default

General error payload

get/transport-requests/{business_id}
Response samples
application/json
{
  • "data": {
    }
}

Upsert a Transport Request with specified business id

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.

Securitykeycloak
Request
path Parameters
business_id
required
string

The business identifier of an entity instance

header Parameters
If-Match
string

weak Etag as optimistic locking check

Prefer
Array 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).
Request Body schema: application/json
required

Transport Request to be updated

business_id
required
string

Unique reference ID

transport_category
string

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.

client
string

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.

description
string

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

object (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.

object (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.

etag
string (Etag)

Must match header if provided on request.

Responses
201

Transport Request updated

Response body contains updated Transport Request

204

Transport Request updated

Response body is empty

404

The entity is not found

409

Response status code indicates a request conflict with current state of the server.

412

Client error response code indicates that access to the target resource has been denied. This happens with conditional requests on methods other than GET or HEAD when the condition defined by the If-Unmodified-Since, If-Match or If-None-Match headers is not fulfilled. This is typically the case when the entity was updated by someone else before you commit your request. In that case, the request, usually a modification of a resource, cannot be executed and this error response is sent back.

default

General error payload

put/transport-requests/{business_id}
Request samples
application/json
{
  • "business_id": "transportRequestA",
  • "transport_category": "transportCategoryA",
  • "client": "companyId",
  • "description": "a description",
  • "orders": {
    },
  • "custom_data": {
    },
  • "etag": "W/\"1\""
}
Response samples
application/json
{
  • "data": {
    }
}

Delete a transport request with specified Id

This endpoint allows you to delete the information about a given TransportRequest. Deleting a Transport Request will also delete all orders within it.

Securitykeycloak
Request
path Parameters
business_id
required
string

The business identifier of an entity instance

header Parameters
If-Match
string

weak Etag as optimistic locking check

Responses
204

Deletion has succeeded, but body is empty

404

The entity is not found

default

General error payload

delete/transport-requests/{business_id}
Response samples
application/problem+json
{}
➔ Next to Companies