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\""

curl -i -X PUT \
  'https://developer.conundra.eu/_mock/apis/order-book/order-book-api/transport-requests/{business_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'If-Match: string' \
  -H 'Prefer: string' \
  -d '{
    "business_id": "transportRequestA",
    "transport_category": "transportCategoryA",
    "client": "companyId",
    "description": "a description",
    "orders": {
      "deliveries": [
        {
          "order": {
            "business_id": "orderA",
            "order_category": "orderCategoryA",
            "description": "a description",
            "capacities": [
              {
                "type": "volume",
                "value": 20,
                "description": "string"
              }
            ],
            "mandatory": true,
            "requirements": {
              "tags": [
                "tagX"
              ],
              "forbidden_tags": [
                "tagY"
              ],
              "combination_strategy": "COMBINE"
            },
            "lifo_groups": [
              "lifo_group"
            ],
            "outsourcing_cost": 0,
            "custom_data": {
              "shop_manager": "John Smith"
            },
            "plan_group": "a plan group",
            "max_time_in_vehicle": {
              "max_time": "PT5M",
              "penalty": 1000
            }
          },
          "delivery": {
            "site_location": {
              "location_id": "locationA"
            },
            "visit_location": {
              "name": "PTV Logistics",
              "address_line": "Voordries 41",
              "city": "Oosterzele",
              "zip_code": "9860",
              "country_code": "BE",
              "geo_point": {
                "latitude": 50.9514048,
                "longitude": 3.8067878
              },
              "labels": [
                "warehouse"
              ]
            },
            "stop_time": {
              "value": "PT5M",
              "combination_strategy": "HIGHEST"
            },
            "service_time": "PT5M",
            "sequence": 1,
            "time_frame": {
              "absolute": [
                {}
              ],
              "windowed": [
                {}
              ],
              "type": "SERVICE_ARRIVAL"
            },
            "color": "red",
            "labels": [
              "labelA"
            ],
            "custom_data": {
              "shop_manager": "John Smith"
            }
          }
        }
      ],
      "pickups": [
        {
          "order": {
            "business_id": "orderA",
            "order_category": "orderCategoryA",
            "description": "a description",
            "capacities": [
              {
                "type": "volume",
                "value": 20,
                "description": "string"
              }
            ],
            "mandatory": true,
            "requirements": {
              "tags": [
                "tagX"
              ],
              "forbidden_tags": [
                "tagY"
              ],
              "combination_strategy": "COMBINE"
            },
            "lifo_groups": [
              "lifo_group"
            ],
            "outsourcing_cost": 0,
            "custom_data": {
              "shop_manager": "John Smith"
            },
            "plan_group": "a plan group",
            "max_time_in_vehicle": {
              "max_time": "PT5M",
              "penalty": 1000
            }
          },
          "pickup": {
            "site_location": {
              "location_id": "locationA"
            },
            "visit_location": {
              "name": "PTV Logistics",
              "address_line": "Voordries 41",
              "city": "Oosterzele",
              "zip_code": "9860",
              "country_code": "BE",
              "geo_point": {
                "latitude": 50.9514048,
                "longitude": 3.8067878
              },
              "labels": [
                "warehouse"
              ]
            },
            "stop_time": {
              "value": "PT5M",
              "combination_strategy": "HIGHEST"
            },
            "service_time": "PT5M",
            "sequence": 1,
            "time_frame": {
              "absolute": [
                {}
              ],
              "windowed": [
                {}
              ],
              "type": "SERVICE_ARRIVAL"
            },
            "color": "red",
            "labels": [
              "labelA"
            ],
            "custom_data": {
              "shop_manager": "John Smith"
            }
          }
        }
      ],
      "pickup_and_deliveries": [
        {
          "order": {
            "business_id": "orderA",
            "order_category": "orderCategoryA",
            "description": "a description",
            "capacities": [
              {
                "type": "volume",
                "value": 20,
                "description": "string"
              }
            ],
            "mandatory": true,
            "requirements": {
              "tags": [
                "tagX"
              ],
              "forbidden_tags": [
                "tagY"
              ],
              "combination_strategy": "COMBINE"
            },
            "lifo_groups": [
              "lifo_group"
            ],
            "outsourcing_cost": 0,
            "custom_data": {
              "shop_manager": "John Smith"
            },
            "plan_group": "a plan group",
            "max_time_in_vehicle": {
              "max_time": "PT5M",
              "penalty": 1000
            }
          },
          "delivery": {
            "site_location": {
              "location_id": "locationA"
            },
            "visit_location": {
              "name": "PTV Logistics",
              "address_line": "Voordries 41",
              "city": "Oosterzele",
              "zip_code": "9860",
              "country_code": "BE",
              "geo_point": {
                "latitude": 50.9514048,
                "longitude": 3.8067878
              },
              "labels": [
                "warehouse"
              ]
            },
            "stop_time": {
              "value": "PT5M",
              "combination_strategy": "HIGHEST"
            },
            "service_time": "PT5M",
            "sequence": 1,
            "time_frame": {
              "absolute": [
                {}
              ],
              "windowed": [
                {}
              ],
              "type": "SERVICE_ARRIVAL"
            },
            "color": "red",
            "labels": [
              "labelA"
            ],
            "custom_data": {
              "shop_manager": "John Smith"
            }
          },
          "pickup": {
            "site_location": {
              "location_id": "locationA"
            },
            "visit_location": {
              "name": "PTV Logistics",
              "address_line": "Voordries 41",
              "city": "Oosterzele",
              "zip_code": "9860",
              "country_code": "BE",
              "geo_point": {
                "latitude": 50.9514048,
                "longitude": 3.8067878
              },
              "labels": [
                "warehouse"
              ]
            },
            "stop_time": {
              "value": "PT5M",
              "combination_strategy": "HIGHEST"
            },
            "service_time": "PT5M",
            "sequence": 1,
            "time_frame": {
              "absolute": [
                {}
              ],
              "windowed": [
                {}
              ],
              "type": "SERVICE_ARRIVAL"
            },
            "color": "red",
            "labels": [
              "labelA"
            ],
            "custom_data": {
              "shop_manager": "John Smith"
            }
          }
        }
      ]
    },
    "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": { … }
  }
}