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

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.

Example:

{
  "shop_manager": "John Smith"
}

etagstring(Etag)

Must match header if provided on request.

Example:"W/\"1\""

Payload

{
  "business_id": "transportRequestA",
  "transport_category": "transportCategoryA",
  "client": "companyId",
  "description": "a description",
  "orders": {
    "deliveries": [ … ],
    "pickups": [ … ],
    "pickup_and_deliveries": [ … ]
  },
  "custom_data": {
    "shop_manager": "John Smith"
  },
  "etag": "W/\"1\""
}

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

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)

Bodyapplication/json

dataobject(TransportRequest)

transport request contains orders

Response

{
  "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\"",
    "version": { … }
  }
}