# Get a PickupDelivery by business Id

Create or update a PickupDelivery Order.

This endpoint allows you to update (default behaviour) or insert a PickupDelivery Order. The caller is responsible for
providing a unique business identifier for each Order, regardless of order type. If this business identifier can't be found,
a new order will be created. If a PickupDelivery order with the given business identifier can be found then it will be updated.

Endpoint: GET /orders/pickup-deliveries/{business_id}
Version: 1.12.5
Security: clientCredentials

## Path parameters:

  - `business_id` (string, required)
    The business identifier of an entity instance

## Response 200 fields (application/json):

  - `order` (object, required)

  - `order.business_id` (string)
    A unique reference id.
    Example: orderA

  - `order.order_category` (string)
    An optional category for the Order, represented by its code. Defining a category for your Order can help in easy retrieval of the information in the user interface.

Conditionals can be targeted to Orders with a specific category, allowing the planner to create business rules for sets of Orders.
    Example: orderCategoryA

  - `order.description` (string)
    A freeform text description, providing additional details that might be of use for a planner.
    Example: a description

  - `order.capacities` (array, required)
    Required capacity on the executor of this Order. The executor will need to be able to fulfill all capacities specified on this Order in order to execute
it.

  - `order.capacities.type` (string)
    Characterization of a capacity, representing the dimension in which this Capacity is expressed.
    Enum: "volume", "weight", "loadingMeters", "capacity1", "capacity2", "capacity3", "capacity4", "capacity5"

  - `order.capacities.value` (number, required)
    The nominal capacity required of the executor, in the specified dimension.
    Example: 20

  - `order.capacities.description` (string)
    An optional description for this capacity entry.

  - `order.mandatory` (boolean)
    Boolean flag signaling the optimization that this order **must** be executed. If this flag is not provided the order is considered optional and an `outsourcing_cost` needs to be provided.
    Example: true

  - `order.requirements` (object)
    Requirements and constraints that this order enforces of its executor. These properties help the optimization engine in determining which executors could
be used for this Order.

  - `order.requirements.tags` (array)
    Properties that **must** be present on the executor to be allowed to execute this order.
Note: if a tag contains a dash, it will be split into two upon exporting and re-importing the order set in PTV OptiFlow Route Optimization.

  - `order.requirements.forbidden_tags` (array)
    Properties that **must not** be present on the executor to be allowed to execute this order.
Note: if a forbidden tag contains a dash, it will be split into two upon exporting and re-importing the order set in PTV OptiFlow Route Optimization.

  - `order.requirements.combination_strategy` (string)
    Strategy for combining the requirements and constraints of this Order with those on linked Locations or applicable Conditionals.
The strategies have the following consequences:
* `OVERRIDE`
The order takes precedence over both Conditionals and Locations, only the Order's requirements and constraints will be taken into account for the optimization.
* `COMBINE`
The order's requirements and constraints will be combined with all requirements and constraints on the linked Location and applicable Conditionals.
    Enum: "COMBINE", "OVERRIDE"

  - `order.lifo_groups` (array)
    Orders are handled *last-in, first-out* (LIFO) within an optimization. Specifying LIFO-groups will limit this behaviour to only those orders within the
same LIFO group.
An order can be a part of multiple LIFO groups, which will result in the LIFO-constraint being applied within each LIFO group it is a part of.
Note: if a lifo group contains a dash, it will be split into two upon exporting and re-importing the order set in PTV OptiFlow Route Optimization.

  - `order.outsourcing_cost` (number)
    A *fictional* cost for not planning this order in an optimization. This allows the optimization engine to weigh the costs of executing the order versus
outsourcing it to a (*potentially fictitious*) third party.
    Example: 0

  - `order.plan_group` (string)
    The plan group this `Order` belongs to. Plan groups signify the group of orders that are supposed to be planned together.
    Example: a plan group

  - `order.client` (string)
    An optional reference, by business_id, to a Company that is known in Order Book. Conditionals can target Orders
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

  - `order.max_time_in_vehicle` (object)
    Constrains the maximum time this order's cargo may spend on a vehicle. If the constraint is violated, a penalty cost is incurred in the optimization.

  - `order.max_time_in_vehicle.max_time` (string, required)
    An ISO-formatted Duration, see [wikipedia ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Durations) and [RFC-3339](https://datatracker.ietf.org/doc/html/rfc3339)
    Example: PT5M

  - `order.max_time_in_vehicle.penalty` (number, required)
    An indication for the penalty that is counted when exceeding the maximum time an order can be on a vehicle. The applied penalty is calculated as follows:
`applied penalty = penalty * (amount_max_time_exceeded)² / (15_minutes)²`
    Example: 1000

  - `delivery` (object, required)
    Properties specific to the activity that needs to be executed for fulfilling this order. In case of a PickupDelivery Order, these are two separate activities
with their own settings.

  - `delivery.site_location` (object)

  - `delivery.site_location.location_id` (string)
    A `business_id` of a known `Location`.
    Example: locationA

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

  - `delivery.visit_location.name` (string)
    A name by which to identify this location
    Example: PTV Logistics

  - `delivery.visit_location.address_line` (string)
    The address line for this location's address.
    Example: Voordries 41

  - `delivery.visit_location.city` (string)
    The city of this location.

Required when no geo point is provided.
    Example: Oosterzele

  - `delivery.visit_location.zip_code` (string)
    The zip code of this location.

Required when no geo point is provided.
    Example: 9860

  - `delivery.visit_location.country_code` (string)
    An ISO3166-1 alpha-2 two letter country code
    Example: BE

  - `delivery.visit_location.geo_point` (object)

  - `delivery.visit_location.geo_point.latitude` (number, required)
    Example: 50.9514048

  - `delivery.visit_location.geo_point.longitude` (number, required)
    Example: 3.8067878

  - `delivery.visit_location.resolved_address` (object)
    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.

  - `delivery.visit_location.resolved_address.address_line` (string)
    Example: Voordries 41

  - `delivery.visit_location.resolved_address.city` (string)
    Example: Oosterzele

  - `delivery.visit_location.resolved_address.zip_code` (string)
    Example: 9860

  - `delivery.visit_location.resolved_address.score` (integer)
    This score ranges from 0 to 9, with 0 being the worst and 9 a perfectly geocoded address.
    Example: 9

  - `delivery.visit_location.labels` (array)
    Labels associated with this visit location.
Note: if a label contains a dash, it will be split into two upon exporting and re-importing the order set in PTV OptiFlow Route Optimization.

  - `delivery.stop_time` (object)
    The time that needs to be taken into account for stopping at the Order's location.

  - `delivery.stop_time.combination_strategy` (string)
    The `combination_strategy` determines how the application will resolve `stop_time` information during the consolidation of an `Order`:
* `HIGHEST`: *(default)*
Pick the highest of the available stop times from the Order, Location and/or Conditional(s).
* `CUMULATIVE`:
Add all available stop times from the Order, Location and/or Conditional(s).
* `OVERRIDE`:
Use the stop time defined on the order. Ignore stop times from the Location and/or Conditional(s).
    Enum: "HIGHEST", "CUMULATIVE", "OVERRIDE"

  - `delivery.service_time` (string)
    The non-negative duration required for executing this activity in the order.
Needs to be an ISO-formatted Duration, see [wikipedia ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Durations) and [RFC-3339](https://datatracker.ietf.org/doc/html/rfc3339)
    Example: PT5M

  - `delivery.sequence` (integer)
    The sequence of this activity of the Order within a Route.

Note: The sequence is applied to a route, not to trips within a route.
    Example: 1

  - `delivery.time_frame` (object, required)
    Supports two ways to specify when an order can be delivered:
* `windowed` intervals are used in conjunction with a (site) Location's (planning) time windows or Conditionals. The windowed intervals will be limited to
the smallest common intersection between all applicable time windows from these.
* `absolute` intervals are absolute date times that will be used to plan the order.

Using both `windowed` and `absolute` intervals in conjunction can solve many complicated cases, especially when taking the flexibility of Conditionals into
account.
**At least one timerange is required, either absolute or windowed.**

  - `delivery.time_frame.absolute` (array)
    A set of date-time intervals within which this activity of the Order can be executed. 

Absolute timeframes will always be retained on the Order after consolidation.

  - `delivery.time_frame.absolute.start_at` (string, required)
    The start of the datetime interval, provided as an ISO-8601 formatted datetime.
    Example: 2021-01-01T10:15:30Z

  - `delivery.time_frame.absolute.end_at` (string)
    The end of the datetime interval, provided as an ISO-8601 formatted datetime.
When no `end_at` is provided, the value is defaulted to the `start_at` + 14 days.
    Example: 2021-01-01T10:15:30Z

  - `delivery.time_frame.absolute.cost` (number)
    An optional cost for executing the activity within this datetime interval. This (potentially fictional) cost can be used to steer the optimization. A
higher cost will be less likely to result in this interval being chosen, though this is still possible if it leads to an overall lower cost on of the
optimization.
**Note:** It's recommended to use integer values as decimal precision is not guaranteed.
    Example: 42

  - `delivery.time_frame.windowed` (array)
    A set of date-time intervals within which this activity of the Order can be executed. These intervals will be intersected with the (planning) opening 
hours of a linked (site) location and/or timewindows defined on applicable Conditionals.

  - `delivery.time_frame.windowed.start_at` (string, required)
    The start of the datetime interval, provided as an ISO-8601 formatted datetime.
    Example: 2021-01-01T10:15:30Z

  - `delivery.time_frame.windowed.end_at` (string)
    The end of the datetime interval, provided as an ISO-8601 formatted datetime.
When no `end_at` is provided, the value is defaulted to the `start_at` + 14 days.
    Example: 2021-01-01T10:15:30Z

  - `delivery.time_frame.type` (string)
    The type of the resulting time window after the order has been consolidated.
When omitted, defaults to SERVICE_ARRIVAL.
    Enum: "SERVICE_ARRIVAL", "ARRIVAL_DEPARTURE", "SERVICE_START", "LOCATION_ARRIVAL"

  - `delivery.color` (string)
    This property can be used to differentiate between orders visually. The orders within a planning will be shown in this color.
The color can be provided both as a CSS color name or using a hexadecimal color code (eg: `#123DEF`).
    Example: red

  - `delivery.labels` (array)
    Labels can be used for identifying sets of Orders. When starting an optimization, labels can be used for filtering the Order space and limiting the
optimization to specific subsets.
Labels can also be used as filters in select Order Book features or rules in `Plan profiles`.
Note: if a label contains a dash, it will be split into two upon exporting and re-importing the order set in PTV OptiFlow Route Optimization.

## Response 404 fields (application/problem+json):

  - `type` (string)
    An absolute URI that identifies the problem type.  When dereferenced,
it SHOULD provide human-readable documentation for the problem type
(e.g., using HTML).
    Example: https://api.conundra.eu/problem/constraint-violation

  - `title` (string)
    A short, summary of the problem type. Written in english and readable
for engineers (usually not suited for non technical stakeholders and
not localized); example: Service Unavailable
    Example: Invalid ...

  - `status` (integer)
    The HTTP status code generated by the origin server for this occurrence
of the problem.
    Example: 400

  - `detail` (string)
    A human readable explanation specific to this occurrence of the
problem.
    Example: string

  - `instance` (string)
    An absolute URI that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.
    Example: https://api.conundra.eu/orderbook/v1/orders/deliveries/chilled

  - `violations` (array)

  - `violations.field` (string)
    A reference to the field in the request that triggered this violation.
    Example: class.field

  - `violations.message` (string)
    A message explaining the violation in the referenced field.
    Example: a violation message

## Response default fields (application/problem+json):

  - `type` (string)
    An absolute URI that identifies the problem type.  When dereferenced,
it SHOULD provide human-readable documentation for the problem type
(e.g., using HTML).
    Example: https://api.conundra.eu/problem/constraint-violation

  - `title` (string)
    A short, summary of the problem type. Written in english and readable
for engineers (usually not suited for non technical stakeholders and
not localized); example: Service Unavailable
    Example: Invalid ...

  - `status` (integer)
    The HTTP status code generated by the origin server for this occurrence
of the problem.
    Example: 400

  - `detail` (string)
    A human readable explanation specific to this occurrence of the
problem.
    Example: string

  - `instance` (string)
    An absolute URI that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.
    Example: https://api.conundra.eu/orderbook/v1/orders/deliveries/chilled

  - `violations` (array)

  - `violations.field` (string)
    A reference to the field in the request that triggered this violation.
    Example: class.field

  - `violations.message` (string)
    A message explaining the violation in the referenced field.
    Example: a violation message