openapi: 3.1.0
info:
  x-api-id: 4e80c7a2-27c3-47ed-b48e-35e62ed402c2
  x-audience:
    - external-partner
  title: Conundra Order Book API
  version: 1.6.1
  description: >
    Order Book provides ready-to-run domain-specific logistic data governance
    for your route optimization.
  contact:
    name: API support
    url: https://servicedesk.conundra.eu
servers:
  - url: https://api.conundra.eu/orderbook/v1
    description: Order Book API Production
security:
  - clientCredentials: []
tags:
  - name: health
    x-displayName: Health check
    description: Miscellaneous endpoints for general API functionality
  - name: categories
    x-displayName: Category Management
    description: >
      **[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.
  - name: locations
    x-displayName: Locations
    description: >
      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.
    externalDocs:
      description: Find out more
      url: >-
        https://developer.conundra.eu/developer-portal/order-book/domain/#location
  - name: transport request
    x-displayName: Transport Requests
    description: >
      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.
    externalDocs:
      description: Find out more
      url: >-
        https://developer.conundra.eu/developer-portal/order-book/domain/#transport-request
  - name: pickups
    x-displayName: Pickup Orders
    description: >
      Pickup orders represent an order where the executor needs to pick up cargo
      at a certain stop.
    externalDocs:
      description: Find out more
      url: https://developer.conundra.eu/developer-portal/order-book/domain/#order
  - name: deliveries
    x-displayName: Delivery Orders
    description: >
      Delivery orders represent an order where the executor needs to drop off
      cargo at a certain stop.
    externalDocs:
      description: Find out more
      url: https://developer.conundra.eu/developer-portal/order-book/domain/#order
  - name: pickupdeliveries
    x-displayName: PickupDelivery Orders
    description: >
      PickupDelivery orders represent an order where the executor needs to pick
      up cargo at a certain stop and deliver it at another stop.
    externalDocs:
      description: Find out more
      url: https://developer.conundra.eu/developer-portal/order-book/domain/#order
  - name: consolidated orders
    x-displayName: Consolidated Orders
    description: >
      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.
    externalDocs:
      description: Find out more
      url: >-
        https://developer.conundra.eu/developer-portal/order-book/domain/#consolidation
  - name: conditionals
    x-displayName: Conditionals
    description: >-
      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.
    externalDocs:
      description: Find out more
      url: >-
        https://developer.conundra.eu/developer-portal/order-book/domain/#consolidation
  - name: companies
    x-displayName: Companies
    description: >-
      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.
    externalDocs:
      description: Find out more
      url: >-
        https://developer.conundra.eu/developer-portal/order-book/domain/#company
  - name: partial routes
    x-displayName: Partial Routes [EXPERIMENTAL]
    description: |
      **[EXPERIMENTAL]** 
      **[UNDER DEVELOPMENT]** 
      Endpoints for managing preplanned `PartialRoutes`.
x-tagGroups:
  - name: Health
    tags:
      - health
  - name: Order Management
    tags:
      - pickups
      - deliveries
      - pickupdeliveries
      - consolidated orders
      - categories
  - name: Grouping Orders
    tags:
      - transport request
      - companies
  - name: Extending Orders
    tags:
      - locations
      - conditionals
  - name: Preplanned
    tags:
      - partial routes
paths:
  /ping:
    get:
      tags:
        - health
      summary: Ping
      description: >
        The `ping`-endpoint can be used for validating a connection with the
        application. It will authenticate the caller and respond `pong` if
        everything is set-up correctly.
      operationId: ping
      responses:
        '200':
          description: pong
          content:
            text/plain:
              schema:
                type: string
  /locations:
    get:
      tags:
        - locations
      summary: Get a list of all locations by ids
      description: >
        This is an endpoint that allows you to retrieve a list of Locations in
        bulk. The locations are identified by their business id, provided in the
        query. 


        When one or more locations could not be found, this will be indicated in
        the errors-section of the response.
      operationId: getPagedLocations
      parameters:
        - name: ids
          in: query
          description: A comma-separated list of Location business IDs.
          required: true
          schema:
            type: array
            items:
              type: string
            minItems: 1
            maxItems: 100
          style: form
          explode: false
      responses:
        '200':
          description: |
            a list of locations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkLocationResponse'
  /locations/by:
    get:
      tags:
        - locations
      summary: Get a list of locations by filter criteria
      description: >
        Retrieve a list of Locations in bulk, identified by the query parameters
        defined in the request. The query requires at least a page and page
        size, in 

        which case all Locations will be returned in a paged format. Providing
        any additional filter will return the matching subset of Locations. When
        providing 

        multiple filter parameters, all filters must match for a Location to be
        included in the response.


        The returned list can be empty, but the request will not fail if no
        results are found.
      operationId: getPagedLocationsBy
      parameters:
        - name: location_category
          in: query
          description: Filter results based on category
          schema:
            type: string
        - name: country_code
          in: query
          description: Filter results based on country identifier (ISO3166-1 alpha-2).
          schema:
            $ref: '#/components/schemas/CountryCode'
        - name: zip_code
          in: query
          description: Filter results based on ZIP code
          schema:
            type: string
        - name: city
          in: query
          description: Filter results based on city
          schema:
            type: string
        - name: address_line
          in: query
          description: collection filtered on address line
          schema:
            type: string
        - $ref: '#/components/parameters/page-index'
        - $ref: '#/components/parameters/page-size'
      responses:
        '200':
          description: a list of locations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Locations'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /locations/{business_id}:
    get:
      tags:
        - locations
      summary: Get a location with specified business Id
      description: |
        Retrieve a single location by its business id.
      operationId: getLocationById
      parameters:
        - $ref: '#/components/parameters/business_id'
        - $ref: '#/components/parameters/X-Conundra-Unwrap'
      responses:
        '200':
          description: OK
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleLocationLookupResponse'
        '404':
          $ref: '#/components/responses/404NotFound'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    put:
      tags:
        - locations
      summary: Upsert a location with specified business Id
      description: >
        Create of update a location. 


        The caller is responsible for providing a unique business id for each
        Location to retain consistency. If a call is made using an unknown
        business id, a 

        new Location will be created, otherwise an update will be applied to the
        existing Location. Locations are versioned and the ETag-header will
        represent the 

        type of operation that was executed. Conversely, adding an If-Match
        header to requests can protect the caller against unintended operations
        by acting as

        an optimistic lock.
      operationId: upsertLocationById
      parameters:
        - $ref: '#/components/parameters/business_id'
        - $ref: '#/components/parameters/if-match'
        - $ref: '#/components/parameters/prefer'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Location'
      responses:
        '201':
          description: >
            Indicates the locations is created or updated.


            The response body contains the location, since Prefer is set to
            return=representation.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleLocationLookupResponse'
        '204':
          description: >
            Indicates the locations is created or updated.


            The response body will be empty, this is the default behaviour or
            the case when the Prefer-header is set to return=minimal.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
        '404':
          description: >-
            Indicates the entity could not be found. This will occur when trying
            to update a Location, using an If-Match header, that has not been
            created before.
          $ref: '#/components/responses/404NotFound'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    delete:
      tags:
        - locations
      summary: |
        Delete a location with specified business id.
      description: >
        This endpoint allows you to delete a location.


        Locations can only be deleted if they are no longer in use by future
        orders or conditionals.
      operationId: deleteLocationById
      parameters:
        - $ref: '#/components/parameters/business_id'
        - $ref: '#/components/parameters/if-match'
      responses:
        '204':
          description: Deletion has succeeded, but body is empty
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409Conflict'
          description: >
            Typically indicates that this Location is still in use by an Order
            that is executable in the future.
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /transport-requests:
    get:
      tags:
        - transport request
      summary: Get a list of all transport requests by ids
      description: >
        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.
      operationId: getListOfTransportRequests
      parameters:
        - name: ids
          in: query
          description: |
            A comma-separated list of Transport Request business IDs.
          required: true
          schema:
            type: array
            items:
              type: string
            minItems: 1
            maxItems: 100
          style: form
          explode: false
      responses:
        '200':
          description: |
            a list of transport requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkTransportRequestResponse'
  /transport-requests/by:
    get:
      tags:
        - transport request
      summary: Get a list of transport request by filter criteria
      description: >
        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](https://developer.conundra.eu/developer-portal/cursor-paging/).
      operationId: getCursorPagedTransportRequests
      parameters:
        - name: start_at
          description: >
            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`.
          in: query
          schema:
            type: string
            format: date-time
        - name: end_at
          in: query
          description: >-
            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`.
          schema:
            type: string
            format: date-time
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: >
            A cursor-based paged set of Transport Requests. The set might be
            empty if no Transport Requests match the query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorPageTransportRequests'
  /transport-requests/{business_id}:
    get:
      tags:
        - transport request
      summary: Get a transport request with specified business id
      description: Retrieve a single Transport Request by its business id.
      operationId: getTransportRequestById
      parameters:
        - $ref: '#/components/parameters/business_id'
        - $ref: '#/components/parameters/X-Conundra-Unwrap'
      responses:
        '200':
          description: OK
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleTransportRequestLookupResponse'
        '404':
          $ref: '#/components/responses/404NotFound'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    put:
      tags:
        - transport request
      summary: Upsert a Transport Request with specified business id
      description: >
        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.
      operationId: upsertTransportRequestById
      parameters:
        - $ref: '#/components/parameters/business_id'
        - $ref: '#/components/parameters/if-match'
        - $ref: '#/components/parameters/prefer'
      requestBody:
        description: Transport Request to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransportRequest'
      responses:
        '201':
          description: |
            Transport Request updated

            Response body contains updated Transport Request
          headers:
            Location:
              schema:
                type: string
              description: >-
                contains the URI, with the ID of the created Transport Request
                ex /transport-requests ETag: $ref: 
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleTransportRequestLookupResponse'
        '204':
          description: |
            Transport Request updated

            Response body is empty
          headers:
            Location:
              schema:
                type: string
              description: >-
                contains the URI, with the ID of the created Transport Request
                ex /transport-requests
            ETag:
              $ref: '#/components/headers/ETag'
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409Conflict'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    delete:
      tags:
        - transport request
      summary: Delete a transport request with specified Id
      description: >
        This endpoint allows you to delete the information about a given
        TransportRequest. Deleting a Transport Request will also delete all
        orders within it.
      operationId: deleteTransportRequestById
      parameters:
        - $ref: '#/components/parameters/business_id'
        - $ref: '#/components/parameters/if-match'
      responses:
        '204':
          description: Deletion has succeeded, but body is empty
        '404':
          $ref: '#/components/responses/404NotFound'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /transport-requests/{business_id}/orders/deliveries/{order_id}:
    get:
      tags:
        - deliveries
      summary: Get a Delivery by business id for a given TransportRequest
      description: >
        This endpoint allows you to get the information about a given delivery.


        **Note:** It is not possible to retrieve deliveries within
        TransportRequests directly through the _Get a Delivery by business Id_
        endpoint.
      operationId: getDeliveryByTransportRequestIdAndOrderId
      parameters:
        - $ref: '#/components/parameters/business_id'
          description: >
            The identifier of the TransportRequest within which this delivery
            exists.
        - name: order_id
          in: path
          description: The identifier of a delivery
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Delivery'
        '404':
          $ref: '#/components/responses/404NotFound'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    put:
      tags:
        - deliveries
      summary: Upsert a Delivery by business id for a given TransportRequest
      description: >
        Upsert delivery information. When if-match is not specified, then no
        optimistic protection is applied, ie: the last update wins.


        **Note:** It is not possible to update deliveries within
        TransportRequests directly through the _Upsert a Delivery by business
        Id_ endpoint.
      operationId: upsertDeliveryByTransportRequestIdAndOrderId
      parameters:
        - $ref: '#/components/parameters/business_id'
          description: >
            The identifier of the TransportRequest within which this delivery
            must be added/edited.
        - name: order_id
          in: path
          description: The identifier of a delivery instance
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/if-match'
        - $ref: '#/components/parameters/prefer'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Delivery'
      responses:
        '201':
          description: |
            Order updated

            Response body contains updated Order
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryInTransportRequest'
        '204':
          description: No Content
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409Conflict'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    delete:
      tags:
        - deliveries
      summary: Delete an Delivery by business id for a given TransportRequest
      description: >
        This endpoint allows you to delete a given delivery within a transport
        request.


        **Note:** It is not possible to delete deliveries within
        TransportRequests directly through the _Delete a Delivery by business
        Id_ endpoint.
      operationId: deleteDeliveryByTransportRequestIdAndOrderId
      parameters:
        - $ref: '#/components/parameters/business_id'
          description: >
            The identifier of the TransportRequest from which this delivery must
            be removed.
        - name: order_id
          in: path
          description: The identifier of a delivery instance
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/if-match'
      responses:
        '204':
          description: No Content
        '404':
          $ref: '#/components/responses/404NotFound'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /transport-requests/{business_id}/orders/pickups/{order_id}:
    get:
      tags:
        - pickups
      summary: Get a Pickup by business id for a given TransportRequest
      description: >
        This endpoint allows you to get the information about a given pickup
        that is contained in a TransportRequest.


        **Note:** It is not possible to retrieve pickups within
        TransportRequests directly through the _Get a Pickup by business Id_
        endpoint.
      operationId: getPickupByTransportRequestIdAndOrderId
      parameters:
        - $ref: '#/components/parameters/business_id'
          description: >
            The identifier of the TransportRequest within which this pickup
            exists.
        - name: order_id
          in: path
          description: The identifier of a Pickup instance
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PickupInTransportRequest'
        '404':
          $ref: '#/components/responses/404NotFound'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    put:
      tags:
        - pickups
      summary: Upsert a Pickup by business id for a given TransportRequest
      description: >
        Upsert pickup information. When if-match is not specified, then no
        optimistic protection is applied, ie: the last update wins.


        **Note:** It is not possible to update pickups within TransportRequests
        directly through the _Upsert a Pickup by business Id_ endpoint.
      operationId: upsertPickupByTransportRequestIdAndOrderId
      parameters:
        - $ref: '#/components/parameters/business_id'
          description: >
            The identifier of the TransportRequest within which this pickup must
            be added/edited.
        - name: order_id
          in: path
          description: The identifier of a Pickup instance
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/if-match'
        - $ref: '#/components/parameters/prefer'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pickup'
      responses:
        '201':
          description: |
            Order updated

            Response body contains updated Order
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PickupInTransportRequest'
        '204':
          description: No Content
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409Conflict'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    delete:
      tags:
        - pickups
      summary: Delete a Pickup by business id for a given TransportRequest
      description: >
        This endpoint allows you to delete a given pickup within a transport
        request.


        **Note:** It is not possible to delete pickups within TransportRequests
        directly through the _Delete a Pickup by business Id_ endpoint.
      operationId: deletePickupByTransportRequestIdAndOrderId
      parameters:
        - $ref: '#/components/parameters/business_id'
          description: >
            The identifier of the TransportRequest from which this pickup must
            be removed.
        - name: order_id
          in: path
          description: The identifier of a Pickup instance
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/if-match'
      responses:
        '204':
          description: No Content
        '404':
          $ref: '#/components/responses/404NotFound'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /transport-requests/{business_id}/orders/pickup-deliveries/{order_id}:
    get:
      tags:
        - pickupdeliveries
      summary: Get a PickupDelivery by business id for a given TransportRequest
      description: >
        This endpoint allows you to get the information about a given
        PickupDelivery.


        **Note:** It is not possible to retrieve pickupDeliveries within
        TransportRequests directly through the _Get a PickupDelivery by business
        Id_ endpoint.
      operationId: getPickupDeliveryByTransportRequestIdAndOrderId
      parameters:
        - $ref: '#/components/parameters/business_id'
          description: >
            The identifier of the TransportRequest within which this
            pickupDelivery exists.
        - name: order_id
          in: path
          description: The identifier of a PickupDelivery instance
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PickupDeliveryInTransportRequest'
        '404':
          $ref: '#/components/responses/404NotFound'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    put:
      tags:
        - pickupdeliveries
      summary: Upsert a PickupDelivery by business id for a given TransportRequest
      description: >
        Upsert PickupDelivery information. When if-match is not specified, then
        no optimistic protection is applied, ie: the last update wins.


        **Note:** It is not possible to update pickupDeliveries within
        TransportRequests directly through the _Upsert a PickupDelivery by
        business Id_ endpoint.
      operationId: upsertPickupDeliveryByTransportRequestIdAndOrderId
      parameters:
        - $ref: '#/components/parameters/business_id'
          description: >
            The identifier of the TransportRequest within which this
            pickupDelivery must be added/edited.
        - name: order_id
          in: path
          description: The identifier of a PickupDelivery instance
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/if-match'
        - $ref: '#/components/parameters/prefer'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PickupDelivery'
      responses:
        '201':
          description: |
            PickupDelivery updated

            Response body contains updated PickupDelivery
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PickupDeliveryInTransportRequest'
        '204':
          description: No Content
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409Conflict'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    delete:
      tags:
        - pickupdeliveries
      summary: Delete a PickupDelivery by business id for a given TransportRequest
      description: >
        This endpoint allows you to delete a given pickupDelivery within a
        transport request.


        **Note:** It is not possible to delete pickupDeliveries within
        TransportRequests directly through the _Delete a PickupDelivery by
        business Id_ endpoint.
      operationId: deletePickupDeliveryByTransportRequestIdAndOrderId
      parameters:
        - $ref: '#/components/parameters/business_id'
          description: >
            The identifier of the TransportRequest from which this
            pickupDelivery must be removed.
        - name: order_id
          in: path
          description: The identifier of a PickupDelivery instance
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/if-match'
      responses:
        '204':
          description: No Content
        '404':
          $ref: '#/components/responses/404NotFound'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /orders/deliveries/{business_id}:
    get:
      tags:
        - deliveries
      summary: Get a Delivery by business id
      description: |
        Retrieve a single Delivery Order by its business id.
      operationId: getDeliveryById
      parameters:
        - $ref: '#/components/parameters/business_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Delivery'
        '404':
          $ref: '#/components/responses/404NotFound'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    put:
      tags:
        - deliveries
      summary: Upsert a Delivery by business Id
      description: >
        Create or update a Delivery Order.


        This endpoint allows you to update (default behaviour) or insert a
        Delivery 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 Delivery order with the given business
        identifier can be found then it will be updated.
      operationId: upsertDeliveryById
      parameters:
        - $ref: '#/components/parameters/business_id'
        - $ref: '#/components/parameters/prefer'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Delivery'
      responses:
        '201':
          description: Order created or updated.
          headers:
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Delivery'
        '204':
          description: No Content
          headers:
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
            Location:
              $ref: '#/components/headers/Location'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409Conflict'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    delete:
      tags:
        - deliveries
      summary: Delete a Delivery with specified business Id
      description: >
        This endpoint allows you to delete the information about a given
        Delivery.
      operationId: deleteDeliveryById
      parameters:
        - $ref: '#/components/parameters/business_id'
      responses:
        '204':
          description: No Content
        '404':
          $ref: '#/components/responses/404NotFound'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /orders/pickups/{business_id}:
    get:
      tags:
        - pickups
      summary: Get a Pickup by business Id
      description: |
        Retrieve a single Pickup order by its business id.
      operationId: getPickupById
      parameters:
        - $ref: '#/components/parameters/business_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pickup'
        '404':
          $ref: '#/components/responses/404NotFound'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    put:
      tags:
        - pickups
      summary: Upsert a Pickup by business Id
      description: >
        Create or update a Pickup Order.


        This endpoint allows you to update (default behaviour) or insert a
        Pickup 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 Pickup order with the given business
        identifier can be found then it will be updated.
      operationId: upsertPickupById
      parameters:
        - $ref: '#/components/parameters/business_id'
        - $ref: '#/components/parameters/prefer'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pickup'
      responses:
        '201':
          description: Order created or updated.
          headers:
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pickup'
        '204':
          description: No Content
          headers:
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
            Location:
              $ref: '#/components/headers/Location'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409Conflict'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    delete:
      tags:
        - pickups
      summary: Delete a Pickup by business Id
      description: |
        This endpoint allows you to delete the information about a given pickup.
      operationId: deletePickupById
      parameters:
        - $ref: '#/components/parameters/business_id'
      responses:
        '204':
          description: No Content
        '404':
          $ref: '#/components/responses/404NotFound'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /orders/pickup-deliveries/{business_id}:
    get:
      tags:
        - pickupdeliveries
      summary: Get a PickupDelivery by business Id
      description: >
        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.
      operationId: getPickupDeliveryById
      parameters:
        - $ref: '#/components/parameters/business_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PickupDelivery'
        '404':
          $ref: '#/components/responses/404NotFound'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    put:
      tags:
        - pickupdeliveries
      summary: Upsert a PickupDelivery by business Id
      description: |
        Upsert PickupDelivery information.
      operationId: upsertPickupDeliveryById
      parameters:
        - $ref: '#/components/parameters/business_id'
        - $ref: '#/components/parameters/prefer'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PickupDelivery'
      responses:
        '201':
          description: Order created or updated.
          headers:
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PickupDelivery'
        '204':
          description: No Content
          headers:
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
            Location:
              $ref: '#/components/headers/Location'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409Conflict'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    delete:
      tags:
        - pickupdeliveries
      summary: Delete a PickupDelivery by business Id
      description: >
        This endpoint allows you to delete the information about a given
        PickupDelivery.
      operationId: deletePickupDeliveryById
      parameters:
        - $ref: '#/components/parameters/business_id'
      responses:
        '204':
          description: No Content
        '404':
          $ref: '#/components/responses/404NotFound'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /consolidated-orders:
    get:
      tags:
        - consolidated orders
      summary: Get a cursor paged list of consolidated orders
      description: >
        This endpoint allows you to retrieve a cursor paged list of information
        on **consolidated** orders, based on their _plannability_. We currently
        only support returning 

        information on Orders that have become **unplannable** after
        consolidating the orders' timeframes with their Location and applicable
        Conditionals.


        You can find out more about how to use cursors in our [developer
        portal](https://developer.conundra.eu/developer-portal/cursor-paging/).
      operationId: getConsolidatedOrders
      parameters:
        - name: plannability
          in: query
          required: true
          schema:
            type: string
            enum:
              - UNPLANNABLE
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsolidatedOrders'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /categories/{entity}:
    get:
      tags:
        - categories
      summary: '[EXPERIMENTAL] Get list of all categories of an entity'
      description: >-
        **[EXPERIMENTAL]** This endpoint allows you to retrieve list of
        categories of an entity.
      operationId: getCategoriesOfEntity
      parameters:
        - $ref: '#/components/parameters/entity'
        - $ref: '#/components/parameters/page-index'
        - $ref: '#/components/parameters/page-size'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityCategories'
  /categories/{entity}/{code}:
    get:
      tags:
        - categories
      summary: '[EXPERIMENTAL] Get a category of an entity with specified code'
      description: >-
        **[EXPERIMENTAL]** This endpoint allows you to get the category of an
        entity with a given code, including the ETag header for optimistic
        locking purpose
      operationId: getCategoryOfEntityByCode
      parameters:
        - $ref: '#/components/parameters/entity'
        - $ref: '#/components/parameters/code'
      responses:
        '200':
          description: OK
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityCategory'
        '404':
          $ref: '#/components/responses/404NotFound'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    put:
      tags:
        - categories
      summary: >-
        [EXPERIMENTAL] Create or Update a category of an entity with specified
        code
      description: >
        **[EXPERIMENTAL]** This endpoint allows you to create or update an
        existing category of an entity.


        When the code does not exist, a new category will be created for the
        entity. No ETag header is required yet.

        For a given code, the properties will be overwritten and then an ETag
        header is required. Do remark that the code in the body of the request,
        must correspond with the code in the path identifier
      operationId: createOrUpdateTypeOfEntity
      parameters:
        - $ref: '#/components/parameters/entity'
        - $ref: '#/components/parameters/code'
        - $ref: '#/components/parameters/if-match'
      requestBody:
        description: Update category of an entity request body
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityCategory'
      responses:
        '204':
          description: Update successful
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
    delete:
      tags:
        - categories
      summary: '[EXPERIMENTAL] Delete an existing category of entity with specified code'
      description: >
        **[EXPERIMENTAL]** This endpoint allows you to delete an existing
        category of an entity


        A category can only be deleted when no active entities are still using
        it.
      operationId: deleteEntityCategoryType
      parameters:
        - $ref: '#/components/parameters/entity'
        - $ref: '#/components/parameters/code'
        - $ref: '#/components/parameters/if-match'
      responses:
        '204':
          description: Delete successful
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
  /conditionals:
    post:
      tags:
        - conditionals
      summary: Create a new conditional
      description: >
        This endpoint allows you to create a new conditional. The application
        will assign a generated ID to the conditional, that can be used for
        retrieving, updating

        or deleting the conditional. This generated ID is returned in the
        Location header and (_optional_) response body.
      operationId: createConditional
      parameters:
        - $ref: '#/components/parameters/prefer'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Conditional'
      responses:
        '201':
          description: OK
          headers:
            Location:
              schema:
                type: string
              description: >-
                contains the URI, including the ID of the created conditional ex
                /conditional/{id}
            ETag:
              $ref: '#/components/headers/ETag'
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conditional'
        '204':
          description: Created successfully
          headers:
            Location:
              schema:
                type: string
              description: >-
                contains the URI, including the ID of the created conditional ex
                /conditional/{id}
            ETag:
              $ref: '#/components/headers/ETag'
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /conditionals/{id}:
    get:
      tags:
        - conditionals
      summary: Get a conditional by Id
      description: >
        This endpoint allows you to get the information about a given
        conditional.
      operationId: getConditionalById
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: OK
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conditional'
        '404':
          $ref: '#/components/responses/404NotFound'
    put:
      tags:
        - conditionals
      summary: Update an existing conditional by Id
      description: |
        This endpoint updates a given conditional.
      operationId: updateConditionalById
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/prefer'
        - $ref: '#/components/parameters/if-match'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Conditional'
      responses:
        '200':
          description: OK
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conditional'
        '204':
          description: Created successfully
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
        '404':
          $ref: '#/components/responses/404NotFound'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    delete:
      tags:
        - conditionals
      summary: Delete a conditional by Id
      description: |
        This endpoint allows you to delete a given conditional
      operationId: deleteConditionalById
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/if-match'
      responses:
        '204':
          description: |
            Deletion has succeeded and body is empty
        '404':
          $ref: '#/components/responses/404NotFound'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /companies/{business_id}:
    get:
      tags:
        - companies
      summary: Get a Company with specified business id
      description: Retrieve a single Company by its business id.
      operationId: getCompanyById
      parameters:
        - $ref: '#/components/parameters/business_id'
      responses:
        '200':
          description: OK
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
        '404':
          $ref: '#/components/responses/404NotFound'
    put:
      tags:
        - companies
      summary: Upsert a company by Id
      description: >
        This endpoint allows you to update (default behaviour) or insert a new
        Company. You are responsible to

        give a unique business identifier with your company. If this business
        identifier can't be found

        then a new company will be created. If a company with the given business
        identifier can be found

        then it will be updated. 


        When you specify 'if-match', which is filled in with a weak ETAG
        representing a version, then you can protect yourself from updates by
        someone else 

        before committing your updates. (see also Optimistic locking). When such
        a conflict is detected, a 412 PreconditionFailed response is returned.
      operationId: updateCompanyById
      parameters:
        - $ref: '#/components/parameters/business_id'
        - $ref: '#/components/parameters/prefer'
        - $ref: '#/components/parameters/if-match'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Company'
      responses:
        '200':
          description: OK
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
        '204':
          description: Created successfully
          headers:
            Location:
              schema:
                type: string
              description: contains the URI, with the business ID of the created company
            ETag:
              $ref: '#/components/headers/ETag'
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
        '404':
          $ref: '#/components/responses/404NotFound'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    delete:
      tags:
        - companies
      summary: Delete a company by Id
      description: |
        This endpoint allows you to delete a given company
      operationId: deleteCompanyById
      parameters:
        - $ref: '#/components/parameters/business_id'
        - $ref: '#/components/parameters/if-match'
      responses:
        '204':
          description: |
            Deletion has succeeded and body is empty
        '404':
          $ref: '#/components/responses/404NotFound'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /preplanned/partial-routes/{business_id}:
    put:
      tags:
        - partial routes
      summary: '[EXPERIMENTAL] Upsert PartialRoute'
      description: '**[EXPERIMENTAL]** Upsert a `PartialRoute` defined by a business id.'
      operationId: upsertPartialRoute
      parameters:
        - $ref: '#/components/parameters/business_id'
        - $ref: '#/components/parameters/if-match'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartialRoute'
      responses:
        '201':
          description: >
            `PartialRoute` created or updated, when the Prefer header was set to
            `return=representation`.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartialRoute'
        '204':
          description: >
            `PartialRoute` created or updated, when the Prefer header was set to
            `return=minimal`.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Preference-Applied:
              $ref: '#/components/headers/Preference-Applied'
            Location:
              $ref: '#/components/headers/Location'
        '404':
          $ref: '#/components/responses/404NotFound'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        default:
          description: General error payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    get:
      tags:
        - partial routes
      summary: '[EXPERIMENTAL] Get PartialRoute'
      description: '**[EXPERIMENTAL]** Get a `PartialRoute` by a business id.'
      operationId: getPartialRoute
      parameters:
        - $ref: '#/components/parameters/business_id'
      responses:
        '200':
          description: OK
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartialRoute'
        '404':
          $ref: '#/components/responses/404NotFound'
    delete:
      tags:
        - partial routes
      summary: '[EXPERIMENTAL] Delete PartialRoute'
      description: '**[EXPERIMENTAL]** Delete a `PartialRoute` by a business id.'
      operationId: deletePartialRoute
      parameters:
        - $ref: '#/components/parameters/business_id'
        - $ref: '#/components/parameters/if-match'
      responses:
        '204':
          description: Deletion has succeeded and body is empty
        '404':
          $ref: '#/components/responses/404NotFound'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
components:
  headers:
    ETag:
      description: >-
        weak Etag (ex W/<etag_value>) which contains the (updated) version of
        the entity
      schema:
        type: string
    Preference-Applied:
      description: >-
        to indicate whether a preference has been applied. (ex
        Preference-Applied: return=representation)
      schema:
        type: string
    Location:
      description: contains the URI to the entity
      schema:
        type: string
  parameters:
    id:
      name: id
      in: path
      description: The generated identifier of an entity instance
      required: true
      schema:
        type: string
    business_id:
      name: business_id
      in: path
      description: The business identifier of an entity instance
      required: true
      schema:
        type: string
        pattern: ^[a-zA-Z0-9.~\-_]{1,512}$
    code:
      name: code
      in: path
      description: The unique identifier for a type
      required: true
      schema:
        type: string
    entity:
      name: entity
      in: path
      description: The unique entity for a type
      required: true
      schema:
        type: string
        enum:
          - order
          - location
          - transport-request
    if-match:
      name: If-Match
      in: header
      description: weak Etag as optimistic locking check
      schema:
        type: string
    X-Conundra-Unwrap:
      name: X-Conundra-Unwrap
      in: header
      description: When set to true, the response will not be wrapped in a `data` property.
      schema:
        type: string
      required: false
    prefer:
      name: Prefer
      in: header
      description: >
        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](https://tools.ietf.org/html/rfc7240)).


        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).
      schema:
        type: array
        items:
          type: string
    page-size:
      name: page_size
      in: query
      description: Number of results by page, see also Paging section.
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 100
        default: 10
    page-index:
      name: page
      in: query
      description: Number of the page to retrieve, see also Paging section.
      schema:
        type: integer
        format: int32
        minimum: 1
        default: 1
    limit:
      name: limit
      in: query
      description: Number of results per page.
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 1000
        default: 100
    cursor:
      name: cursor
      in: query
      description: >
        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.
      schema:
        type: string
  schemas:
    BulkLocationResponse:
      type: object
      properties:
        data:
          type: array
          minItems: 0
          maxItems: 100
          uniqueItems: true
          items:
            $ref: '#/components/schemas/Location'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Problem'
    BulkTransportRequestResponse:
      type: object
      properties:
        data:
          type: array
          minItems: 0
          maxItems: 100
          uniqueItems: true
          items:
            $ref: '#/components/schemas/TransportRequest'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Problem'
    Capacity:
      title: Capacity
      type: object
      description: |
        Required capacity on the executor of this Order.
      properties:
        type:
          type: string
          enum:
            - volume
            - weight
            - loadingMeters
            - capacity1
            - capacity2
            - capacity3
            - capacity4
            - capacity5
          description: >
            Characterization of a capacity, representing the dimension in which
            this Capacity is expressed.
          default: volume
        value:
          type: number
          format: double
          exclusiveMinimum: 0
          example: 20
          description: >
            The nominal capacity required of the executor, in the specified
            dimension.
      required:
        - value
    ClosedDateRange:
      description: |
        Specifies a closed interval with 2 absolute dates
      type: object
      properties:
        start_at:
          type: string
          description: |
            The ISO-8601 formatted start date of the interval.
          format: date-time
          example: '2021-01-01T10:15:30Z'
        end_at:
          type: string
          description: |
            The ISO-8601 formatted end date of the interval.
          format: date-time
          example: '2021-01-01T10:15:30Z'
      required:
        - start_at
        - end_at
    Company:
      type: object
      properties:
        business_id:
          description: A unique reference ID
          type: string
          pattern: ^[a-zA-Z0-9.~\-_]+$
          example: 624ec196-4c5c-4fb4-bb43-9ffd8a6b8844
        name:
          description: The name of this Company
          type: string
          example: a name
    Conditional:
      description: >
        Conditionals capture business rules that need to be applied to subsets
        of orders when they adhere to certain conditions.
      type: object
      properties:
        id:
          description: >
            A generated identifier for a conditional. The identifier is returned
            in both the `Location` header and (optional) response body when
            creating the 

            Conditional.
          type: string
          example: 624ec196-4c5c-4fb4-bb43-9ffd8a6b8844
          readOnly: true
        name:
          description: A short name for the Conditional
          type: string
          example: a name
        description:
          type: string
          example: a description
          description: >-
            A description for the conditional, helpful in determining the why or
            what.
        conditions:
          type: object
          description: >
            The rules that will determine whether this conditional is applicable
            to an order or not.


            At least one conditional needs to be provided. The different
            top-level conditions are combined with AND logic, ie: they all need
            to match for an order

            to match this conditional.
          properties:
            locations:
              type: array
              description: >
                Use this condition to target orders based on their
                `site_location`, by providing the Location's business ID in the
                list. 


                When providing multiple references, only one of the Locations
                needs to be present on the Order.
              items:
                description: A business_id of a known Location
                type: string
                example: locationA
            temporals:
              type: array
              description: >
                This is a time-based condition for targeting orders. Each
                temporal condition provided will look for orders where at least
                one timeFrame (either 

                absolute or windowed) overlaps with this range.


                Should the order contain timeframes without an `end_at`, the
                default period of two weeks will be used to determine whether
                the timeframe overlaps

                with the temporal condition.


                When providing multiple temporal conditions, only one of them
                needs to match the order's timeframe.
              items:
                $ref: '#/components/schemas/ClosedDateRange'
            categories:
              type: array
              description: >
                When providing filters on categories of multiple types, each
                type needs to match for an order to match the condition.
              items:
                $ref: '#/components/schemas/ConditionsCategory'
            clients:
              type: array
              description: >
                A list of references to Companies (identified by their business
                id). When any company is present on an order's (_optional_)
                transport request, the

                order matches the condition.
              items:
                type: string
                example: company-id
        effects:
          type: object
          description: At least one property has to be filled.
          properties:
            stop_time:
              $ref: '#/components/schemas/IsoDuration'
            time_windows:
              type: array
              minItems: 0
              maxItems: 100
              uniqueItems: true
              items:
                $ref: '#/components/schemas/TimeWindow'
            requirements:
              $ref: '#/components/schemas/Requirements'
      required:
        - conditions
        - effects
    ConditionsCategory:
      type: object
      properties:
        entity_type:
          description: >
            The entity type for which this category needs to be present. within
            a conditional, only `LOCATION` and `ORDER` entities are supported.
            When using the 

            `LOCATION` entity type, all orders linked to this location will be
            targeted.
          $ref: '#/components/schemas/EntityType'
        categories:
          type: array
          description: >
            A list of categories (defined by their `code`), of which one needs
            to be present on the specified entity for the order to match.
          minItems: 1
          items:
            type: string
            example: my-category
      required:
        - entity_type
        - categories
    CountryCode:
      description: An ISO3166-1 alpha-2 two letter country code
      type: string
      pattern: ^[A-Z]{2}$
      example: BE
    Cursor:
      type: object
      properties:
        self:
          type: string
          description: >-
            The cursor for this page. Not present when the result contains no
            data.
          example: c2VsZl9fcGFnZQ
        prev:
          type: string
          description: >-
            The cursor for the previous page. Not present when fetching data for
            the first page.
          example: cHJldmlvdXNfX3BhZ2U
        next:
          type: string
          description: >-
            The cursor for the next page. Not present when fetching data for the
            last page.
          example: bmV4dF9fcGFnZQ
    CursorPageTransportRequests:
      type: object
      properties:
        data:
          type: array
          description: >
            Subset of Transport Requests matching the provided query, limited to
            the size specified in the request.
          items:
            $ref: '#/components/schemas/TransportRequest'
        cursor:
          $ref: '#/components/schemas/Cursor'
      required:
        - data
        - cursor
    CustomData:
      title: CustomData
      description: >
        Custom data is an extendable hashmap of key-value pairs for client
        usage. These values have no meaning in the context of Order Book, but
        can be used to 

        enrich the data in Order Book with relevant information for the end
        users.
      additionalProperties:
        type: string
        description: >
          A single key-value pair, with the value being an optional string.


          The platform distinguishes between `null` values (there is no value
          for this key) and empty values (the value of this key is an empty
          string: `""`).

          When setting the value of a custom data property to an empty string,
          the key will still be present on an order in an Optiflow Match
          planning (for relevant

          entities), whereas setting the value to `null` signifies that this key
          is not a part of this entity.
      example:
        shop_manager: John Smith
    DayOfWeek:
      description: |
        Corresponding to the days of the week, starting on Monday.
      type: string
      example: MONDAY
      enum:
        - MONDAY
        - TUESDAY
        - WEDNESDAY
        - THURSDAY
        - FRIDAY
        - SATURDAY
        - SUNDAY
    DeliveryInTransportRequest:
      title: Delivery
      description: |
        A single delivery order.
      type: object
      properties:
        order:
          $ref: '#/components/schemas/OrderInformationInTransportRequest'
        delivery:
          $ref: '#/components/schemas/TransportInformation'
      required:
        - order
        - delivery
    ConsolidatedOrders:
      type: object
      properties:
        data:
          type: array
          minItems: 0
          maxItems: 100
          uniqueItems: true
          items:
            $ref: '#/components/schemas/ConsolidatedOrder'
        cursor:
          $ref: '#/components/schemas/Cursor'
      required:
        - data
        - cursor
    ConsolidatedOrder:
      title: Consolidated Order
      description: |
        Information on a consolidated order.
      type: object
      properties:
        order_id:
          type: string
          description: The unique identifier of an order
        transport_request_id:
          type: string
          description: >-
            The identifier of the _(optional)_ transport request related to the
            order
        order_type:
          type: string
          description: |
            The type of the Order.
          enum:
            - PICKUP
            - DELIVERY
            - PICKUP_DELIVERY
        unplannable_reasons:
          type: array
          items:
            type: object
            properties:
              reason:
                type: string
                description: >
                  A code indicating why an order is inherently unplannable. We
                  keep these codes stable, so they can be used by automated
                  integrations.  

                  Possible values:

                  - NO_PLANNABLE_TIME_WINDOWS_FOR_PICKUP

                  - NO_PLANNABLE_TIME_WINDOWS_FOR_DELIVERY
              description:
                type: string
                description: >
                  Human-friendly description of the cause for the
                  unplannability.
    EntityCategory:
      title: EntityType
      type: object
      properties:
        entity:
          type: string
          enum:
            - order
            - location
            - transport-request
          description: The entity type for which this category is valid.
          example: location
          readOnly: true
        code:
          type: string
          description: A unique code for this category, within the entity's categories.
          example: codeA
          readOnly: true
        labels:
          description: |
            Descriptive labels for this category.
          $ref: '#/components/schemas/MultiLanguages'
      required:
        - code
        - labels
    EntityCategories:
      type: object
      properties:
        data:
          type: array
          minItems: 0
          maxItems: 100
          uniqueItems: true
          items:
            $ref: '#/components/schemas/EntityCategory'
        page:
          $ref: '#/components/schemas/Paging'
    EntityType:
      type: string
      example: LOCATION
      x-extensible-enum:
        - LOCATION
        - TRANSPORT_REQUEST
        - ORDER
    Etag:
      type: string
      example: W/"1"
      description: Must match header if provided on request.
    GeoPoint:
      properties:
        latitude:
          type: number
          format: double
          example: 50.9514048
        longitude:
          type: number
          format: double
          example: 3.8067878
      required:
        - latitude
        - longitude
    GeoAddress:
      type: object
      description: >
        Either a textual address information should be present, or a geo point.
        The resolved information is read only and will be filled out after
        resolving, 

        ie: it is only visible in the response.
      properties:
        address_line:
          type: string
          example: Voordries 41
          description: >-
            Optional address line representing the street address (optionally
            including house number, box, ...)
        city:
          type: string
          example: Oosterzele
          description: The name of the locality. Mandatory if no geo point is provided.
        zip_code:
          type: string
          example: '9860'
          description: >-
            The uniquely identifying code of this locality. Mandatory if no geo
            point is provided.
        country_code:
          description: >-
            An ISO3166-1 alpha-2 two letter country code. Mandatory if no geo
            point is provided.
          $ref: '#/components/schemas/CountryCode'
        geo_point:
          $ref: '#/components/schemas/GeoPoint'
          description: >
            A The geo point is optional, if and only if all the mandatory
            address fields are supplied. When no geo point is provided, a
            geocoding call will determine

            the geo point using the provided textual address fields. (See
            resolved address for more information.)


            Adding a geo point allows you to retain full control of the data
            that will be used in your planning.
        resolved_address:
          $ref: '#/components/schemas/ResolvedAddress'
      required:
        - city
        - zip_code
        - country_code
    Location:
      title: Location
      description: >
        A location has an address and timewindows representing opening hours.


        An alternative address and/or timewindows to be used for planning can be
        specified.

        When planning address and/or timewindows are specified the originals are
        only there for information purposes.


        An address item can consist of an address and/or geo coordinates.

        The resolved version will be resolved based on the geo coordinates or
        the address (not both).

        The resolved version will be available when reading to make out what the
        original geo coordinates in the routing service are.
      type: object
      properties:
        business_id:
          type: string
          pattern: ^[a-zA-Z0-9.~\-_]{1,512}$
          example: locationA
          description: Unique reference id
        location_category:
          type: string
          example: locationCategoryA
          description: >
            An optional category for the Locations, represented by its code.
            Defining a category for your Location can help in easy retrieval of
            the information 

            through the search-endpoints or in the user interface.


            A category will also allow you to target Conditionals to Orders
            which are tied to a Location with specific categories.
        name:
          type: string
          example: locationName
          description: |
            An optional name that helps in identifying the Location.
        description:
          type: string
          example: locationDescription
          description: >
            A freeform text description of the Location, providing additional
            details that might be of use for a planner.
        comment:
          type: string
          example: locationComment
          description: |
            A freeform text field for adding comments to a Location.
        address:
          description: >
            The main, physical address for this Location. This address as
            mandatory for creating/updating a Location.
          $ref: '#/components/schemas/GeoAddress'
        planning_address:
          description: >
            The planning address allows you to override the address on a
            Location. A typical use case for this would be to provide the
            official address of a retail

            location in the address field, but specifying a loading dock in a
            back alley using the planning address.
          $ref: '#/components/schemas/GeoAddress'
        stop_time:
          description: >
            The stop time to be applied when visiting this Location. 


            Must be specified as a valid ISO Duration (see [wikipedia
            ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Durations) and
            [RFC-3339](https://datatracker.ietf.org/doc/html/rfc3339)). Must be
            non negative.
          $ref: '#/components/schemas/IsoDuration'
        requirements:
          $ref: '#/components/schemas/Requirements'
        time_window:
          $ref: '#/components/schemas/TimeWindows'
        planning_time_window:
          description: >
            Planning time windows allow you to specify a different set of time
            windows for use in the planning, and follow the same format as the
            `time_window` property. 

            A typical use case for this would be to specify different delivery
            windows for a retail location (eg: you can deliver order before the
            regular opening hours 

            of the retail location) while still providing the information about
            the regular opening hours (eg: a planner can still determine whether
            he would be 

            able to contact anyone at the location during their regular opening
            hours). 


            If no planning time windows are specified, the regular time windows
            will be used for planning.
          $ref: '#/components/schemas/TimeWindows'
        custom_data:
          description: >
            Custom data allows you te enrich a `Location` with relevant
            information for the planner that is not part of the Order Book
            domain. 


            Custom Data on a Location will be inherited by `Orders` linked to
            this `Location`. When a key is duplicated on the `Order`, the
            `Order` will retain its value for this key.
          $ref: '#/components/schemas/CustomData'
        etag:
          $ref: '#/components/schemas/Etag'
      required:
        - address
        - business_id
    LocationId:
      type: object
      properties:
        location_id:
          type: string
          example: locationA
          description: |
            A `business_id` of a known `Location`.
    Locations:
      type: object
      properties:
        data:
          type: array
          minItems: 0
          maxItems: 100
          uniqueItems: true
          items:
            $ref: '#/components/schemas/Location'
        page:
          $ref: '#/components/schemas/Paging'
    MultiLanguages:
      properties:
        languages:
          description: >
            Key must be a valid [ISO
            639-1](https://www.iso.org/iso-639-language-codes.html) language
            code.
          type: object
          additionalProperties:
            type: string
            description: >-
              The value represents the label to be used for the language code
              specified by the key.
        default_label:
          type: string
          example: low emission zone
          description: label for the default language to fall back on
      required:
        - default_label
      example:
        default_label: low emission zone
        languages:
          nl: lage emissie zone
          fr: zone à faible émission
    WindowedTimeFrame:
      description: >
        Specifies a datetime interval within which an Order's activity _can_ be
        executed.
      type: object
      properties:
        start_at:
          type: string
          description: >
            The start of the datetime interval, provided as an ISO-8601
            formatted datetime.
          format: date-time
          example: '2021-01-01T10:15:30Z'
        end_at:
          type: string
          description: >
            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.
          format: date-time
          example: '2021-01-01T10:15:30Z'
      required:
        - start_at
    AbsoluteTimeFrame:
      description: >
        Specifies a datetime interval within which an Order's activity _can_ be
        executed.
      type: object
      properties:
        start_at:
          type: string
          description: >
            The start of the datetime interval, provided as an ISO-8601
            formatted datetime.
          format: date-time
          example: '2021-01-01T10:15:30Z'
        end_at:
          type: string
          description: >
            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.
          format: date-time
          example: '2021-01-01T10:15:30Z'
        cost:
          description: >
            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.
          type: number
          format: double
          example: 42
      required:
        - start_at
    OrderInformation:
      type: object
      properties:
        business_id:
          type: string
          pattern: ^[a-zA-Z0-9.~\-_]{1,512}$
          example: orderA
          readOnly: true
          description: |
            A unique reference id.
        order_category:
          type: string
          example: orderCategoryA
          description: >
            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.
        description:
          type: string
          example: a description
          description: >
            A freeform text description, providing additional details that might
            be of use for a planner.
        capacities:
          type: array
          minItems: 1
          maxItems: 8
          uniqueItems: true
          description: >
            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.
          items:
            $ref: '#/components/schemas/Capacity'
        mandatory:
          type: boolean
          example: true
          default: false
          description: >
            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.
        requirements:
          $ref: '#/components/schemas/OrderRequirements'
        lifo_groups:
          type: array
          description: >
            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.
          items:
            type: string
            example: lifo_group
        outsourcing_cost:
          type: number
          format: double
          example: 0
          description: >
            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.
        custom_data:
          description: >
            Custom data allows you te enrich an `Order` with relevant
            information for the planner that is not part of the Order Book
            domain. Custom data properties

            will be available on the distinct activities (`Pickup` and/or
            `Delivery`) of this `Order` in the planning context. This allows you
            to define a property

            once and have it available on both parts of a `PickupDelivery`
            `Order`.


            When a custom data key is duplicated on the activity-level, it will
            override the value defined on the `Order` level.
          $ref: '#/components/schemas/CustomData'
        plan_group:
          type: string
          example: a plan group
          description: >
            The plan group this `Order` belongs to. Plan groups signify the
            group of orders that are supposed to be planned together.
        client:
          type: string
          example: companyId
          description: >
            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.
      required:
        - capacities
    OrderInformationInTransportRequest:
      type: object
      description: >
        General order properties. In case of a pickupDelivery Order, these
        properties are shared between both the pickup and delivery activities.
      properties:
        business_id:
          type: string
          pattern: ^[a-zA-Z0-9.~\-_]{1,512}$
          example: orderA
          description: |
            A unique reference id.
        order_category:
          type: string
          example: orderCategoryA
          description: >
            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.
        description:
          type: string
          example: a description
          description: >
            A freeform text description, providing additional details that might
            be of use for a planner.
        capacities:
          type: array
          minItems: 1
          maxItems: 8
          uniqueItems: true
          description: >
            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.
          items:
            $ref: '#/components/schemas/Capacity'
        mandatory:
          type: boolean
          example: true
          description: >
            Boolean flag signaling the optimization that this order **must** be
            executed. If this flag is not provided, an `outsourcing_cost` needs
            to be provided.
        requirements:
          $ref: '#/components/schemas/OrderRequirements'
        lifo_groups:
          type: array
          description: >
            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.
          items:
            type: string
            example: lifo_group
        outsourcing_cost:
          type: number
          format: double
          example: 0
          description: >
            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.
        custom_data:
          description: >
            Custom data allows you te enrich an `Order` with relevant
            information for the planner that is not part of the Order Book
            domain. Custom data properties

            will be available on the distinct activities (`Pickup` and/or
            `Delivery`) of this `Order` in the planning context. This allows you
            to define a property

            once and have it available on both parts of a `PickupDelivery`
            `Order`.


            When a custom data key is duplicated on the activity-level, it will
            override the value defined on the `Order` level.
          $ref: '#/components/schemas/CustomData'
        plan_group:
          type: string
          example: a plan group
          description: >
            The plan group this `Order` belongs to. Plan groups signify the
            group of orders that are supposed to be planned together.
      required:
        - business_id
        - capacities
    OrderRequirements:
      type: object
      description: >
        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.
      properties:
        tags:
          type: array
          description: >
            Properties that **must** be present on the executor to be allowed to
            execute this order.
          items:
            type: string
            example: tagX
        forbidden_tags:
          type: array
          description: >
            Properties that **must not** be present on the executor to be
            allowed to execute this order.
          items:
            type: string
            example: tagY
        combination_strategy:
          type: string
          description: >
            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
          default: COMBINE
    Orders:
      type: object
      description: >
        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`.
      properties:
        deliveries:
          type: array
          minItems: 0
          maxItems: 100
          uniqueItems: true
          description: |
            Set of deliveries related to this Transport Request.
          items:
            $ref: '#/components/schemas/DeliveryInTransportRequest'
        pickups:
          type: array
          minItems: 0
          maxItems: 100
          uniqueItems: true
          description: |
            Set of pickups related to this Transport Request.
          items:
            $ref: '#/components/schemas/PickupInTransportRequest'
        pickup_and_deliveries:
          type: array
          minItems: 0
          maxItems: 100
          uniqueItems: true
          description: |
            Set of pickupAndDelivery pairs related to this Transport Request.
          items:
            $ref: '#/components/schemas/PickupDeliveryInTransportRequest'
    OrderStopTime:
      type: object
      description: >
        The time that needs to be taken into account for stopping at the Order's
        location.
      properties:
        value:
          $ref: '#/components/schemas/IsoDuration'
        combination_strategy:
          type: string
          description: >
            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
          default: HIGHEST
      required:
        - value
    Paging:
      properties:
        total_items:
          type: integer
          format: int32
          example: 100
        total_pages:
          type: integer
          format: int32
          example: 10
        page_size:
          type: integer
          format: int32
          example: 10
        current_page:
          type: integer
          format: int32
          example: 1
    PickupInTransportRequest:
      title: Pickup
      description: |
        A single pickup order.
      type: object
      properties:
        order:
          $ref: '#/components/schemas/OrderInformationInTransportRequest'
        pickup:
          $ref: '#/components/schemas/TransportInformation'
      required:
        - order
        - pickup
    PickupDeliveryInTransportRequest:
      title: PickupDelivery
      description: |
        A single pickup-delivery pair.
      type: object
      properties:
        order:
          $ref: '#/components/schemas/OrderInformationInTransportRequest'
        delivery:
          $ref: '#/components/schemas/TransportInformation'
        pickup:
          $ref: '#/components/schemas/TransportInformation'
      required:
        - order
        - delivery
        - pickup
    Pickup:
      title: Pickup
      description: Pickup entity
      type: object
      properties:
        order:
          $ref: '#/components/schemas/OrderInformation'
        pickup:
          $ref: '#/components/schemas/TransportInformation'
      required:
        - order
        - pickup
    PickupDelivery:
      title: PickupDelivery
      description: Pickup and delivery entity
      type: object
      properties:
        order:
          $ref: '#/components/schemas/OrderInformation'
        delivery:
          $ref: '#/components/schemas/TransportInformation'
        pickup:
          $ref: '#/components/schemas/TransportInformation'
      required:
        - order
        - delivery
        - pickup
    Problem:
      type: object
      properties:
        type:
          type: string
          format: uri
          description: >
            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:
          type: string
          example: Invalid ...
          description: >
            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
        status:
          type: integer
          format: int32
          description: >
            The HTTP status code generated by the origin server for this
            occurrence

            of the problem.
          minimum: 100
          exclusiveMaximum: 600
          example: 400
        detail:
          type: string
          description: |
            A human readable explanation specific to this occurrence of the
            problem.
          example: string
        instance:
          type: string
          format: uri
          example: https://api.conundra.eu/orderbook/v1/orders/deliveries/chilled
          description: >
            An absolute URI that identifies the specific occurrence of the
            problem.

            It may or may not yield further information if dereferenced.
        violations:
          type: array
          items:
            $ref: '#/components/schemas/Violation'
    ResolvedAddress:
      title: ResolvedAddress
      type: object
      description: >
        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.
      readOnly: true
      properties:
        geo_point:
          $ref: '#/components/schemas/GeoPoint'
        address_line:
          type: string
          example: Voordries 41
        city:
          type: string
          example: Oosterzele
        zip_code:
          type: string
          example: '9860'
        country_code:
          $ref: '#/components/schemas/CountryCode'
        score:
          type: integer
          format: int32
          example: 9
          description: >-
            This score ranges from 0 to 9, with 0 being the worst and 9 a
            perfectly geocoded address.
    Requirements:
      description: >
        Requirements that have to be fulfilled by the executor of an order at
        this location.
      type: object
      properties:
        tags:
          description: Properties that MUST be present on the executor.
          type: array
          default: []
          uniqueItems: true
          items:
            type: string
            example: tagX
        forbidden_tags:
          description: Properties that MUST NOT be present on the executor.
          type: array
          default: []
          uniqueItems: true
          items:
            type: string
            example: tagY
    SingleTransportRequestLookupResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/TransportRequest'
    SingleLocationLookupResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Location'
    Time:
      description: |
        Time supports 00:00-23:59h
      type: string
      pattern: ^([0-1][0-9]|[2][0-3]):([0-5][0-9])$
      example: '14:45'
    TimeFrame:
      description: >
        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.**
      type: object
      properties:
        absolute:
          description: >
            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.
          type: array
          items:
            $ref: '#/components/schemas/AbsoluteTimeFrame'
        windowed:
          description: >
            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.
          type: array
          items:
            $ref: '#/components/schemas/WindowedTimeFrame'
    TimeWindow:
      description: |
        One pair of open and corresponding closing moment.
      type: object
      properties:
        open_time:
          $ref: '#/components/schemas/Time'
        open_day:
          $ref: '#/components/schemas/DayOfWeek'
        close_time:
          $ref: '#/components/schemas/Time'
        close_day:
          $ref: '#/components/schemas/DayOfWeek'
        cost:
          description: >
            The cost of a time window can be use to steer the optimization,
            where it wil prefer a lower cost. It's recommended to use integer
            values as decimal 

            precision is not guaranteed.
          type: number
          format: double
          default: 0
      required:
        - open_time
        - open_day
        - close_time
        - close_day
    TimeWindows:
      description: >
        A collection of TimeWindows, defining when this location can be visited.
        This can be used to restrict an Order's windowed timeframes. If this
        property 

        is not provided, we consider the location open 24/7.
      type: object
      properties:
        description:
          description: An optional description to accompany or clarify the opening hours.
          type: string
          example: a description
        windows:
          type: array
          description: >
            An empty array is a valid option, as it indicates no specific
            opening hours and we consider it open 24/7.
          minItems: 0
          maxItems: 100
          uniqueItems: true
          items:
            $ref: '#/components/schemas/TimeWindow'
    TransportInformation:
      type: object
      description: >
        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.
      properties:
        site_location:
          description: >
            A known `Location` in Order Book at which this activity occurs. This
            allows reusing the information present on the Location, such as
            opening hours, addresses

            requirements... Using a `site_location` also allows you to target
            sets of Orders based on a shared Location reference in a
            Conditional. Combining the 

            Order properties with those of the linked Location can be fine-tuned
            using the combination strategies on relevant properties.


            Mutually exclusive with `visit_location`.
          $ref: '#/components/schemas/LocationId'
        visit_location:
          description: >
            An ad-hoc address at which this Order needs to be executed. When
            using a `visit_location` either address information should be
            present, or otherwise 

            a geo point. When no geo_point is provided the address will be
            resolved by our geocoding service. The resolved information is read
            only (ie: only 

            available in a response).


            Mutually exclusive with `site_location`.
          $ref: '#/components/schemas/VisitLocation'
        stop_time:
          $ref: '#/components/schemas/OrderStopTime'
        service_time:
          $ref: '#/components/schemas/ServiceTime'
        sequence:
          type: integer
          format: int32
          description: >
            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
        time_frame:
          $ref: '#/components/schemas/TimeFrame'
        color:
          type: string
          description: >
            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
        labels:
          type: array
          description: >
            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
            Constraint Management.
          items:
            type: string
            example: labelA
        custom_data:
          description: >
            Custom data allows you te enrich an `Order` with relevant
            information for the planner that is not part of the Order Book
            domain. Custom data properties

            defined on this activity of an `Order` will be available in the
            planning context.


            Keys defined on this level will override any custom data that is
            defined on other entities or properties.
          $ref: '#/components/schemas/CustomData'
      required:
        - time_frame
    TransportRequest:
      type: object
      description: transport request contains orders
      properties:
        business_id:
          type: string
          pattern: ^[a-zA-Z0-9.~\-_]{1,512}$
          example: transportRequestA
          description: Unique reference ID
        transport_category:
          type: string
          example: transportCategoryA
          description: >
            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:
          type: string
          example: companyId
          description: >
            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.
        earliest_start_at:
          description: >
            A calculated field that is the earliest start_at of all contained
            Orders.
          type: string
          format: date-time
          example: '2021-01-01T10:15:30Z'
          readOnly: true
        description:
          type: string
          example: a description
          description: >
            A freeform text description of the Transport Request, providing
            additional details that might be of use for a planner.
        orders:
          $ref: '#/components/schemas/Orders'
        custom_data:
          description: >
            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`.
          $ref: '#/components/schemas/CustomData'
        etag:
          $ref: '#/components/schemas/Etag'
      required:
        - business_id
    Violation:
      type: object
      properties:
        field:
          type: string
          description: >-
            A reference to the field in the request that triggered this
            violation.
          example: class.field
        message:
          type: string
          description: A message explaining the violation in the referenced field.
          example: a violation message
    VisitLocation:
      type: object
      description: >-
        Either address information should be present, or otherwise the geo
        point. The resolved information will be read-only and be filled out
        after resolving.
      properties:
        name:
          description: A name by which to identify this location
          type: string
          example: Conundra
        address_line:
          description: The address line for this location's address.
          type: string
          example: Voordries 41
        city:
          description: |
            The city of this location.

            Required when no geo point is provided.
          type: string
          example: Oosterzele
        zip_code:
          description: |
            The zip code of this location.

            Required when no geo point is provided.
          type: string
          example: '9860'
        country_code:
          description: |
            An ISO3166-1 alpha-2 two letter country code.

            Required when no geo point is provided.
          $ref: '#/components/schemas/CountryCode'
        geo_point:
          description: >
            The geo point identifying this location. If this is provided, all
            textual address information is optional.
          $ref: '#/components/schemas/GeoPoint'
        resolved_address:
          $ref: '#/components/schemas/ResolvedAddress'
    Delivery:
      title: Delivery
      description: Delivery entity
      type: object
      properties:
        order:
          $ref: '#/components/schemas/OrderInformation'
        delivery:
          $ref: '#/components/schemas/TransportInformation'
      required:
        - order
        - delivery
    IsoDuration:
      type: string
      description: >-
        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
    ServiceTime:
      type: string
      default: PT0S
      description: >
        The 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
    PartialRoute:
      type: object
      properties:
        business_id:
          type: string
          pattern: ^[a-zA-Z0-9.~\-_]{1,512}$
          readOnly: true
          example: PPT-1
          description: |
            Unique identifier for this `PartialRoute`.
        plan_group:
          type: string
          example: a plan group
          description: >
            The (optional) plan group this `PartialRoute` belong to. Plan Groups
            can be used for filtering the data included in a logistical
            optimization.
        same_route_group:
          type: string
          example: route-group-01
          description: >
            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.
        requirements:
          $ref: '#/components/schemas/Requirements'
          description: >
            The requirements that need to be fulfilled for this `PartialRoute`
            to be considered feasible for an executor in a logistical
            optimization.
        labels:
          type: array
          default: []
          uniqueItems: true
          description: >
            Labels can be used for identifying sets of `PartialRoutes`, or
            `Orders` within these `PartialRoutes`.
          items:
            type: string
            example: labelA
        stops:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: '#/components/schemas/Stop'
          description: >
            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.
        breaks:
          type: array
          default: []
          items:
            $ref: '#/components/schemas/Break'
      required:
        - business_id
        - stops
    Stop:
      type: object
      properties:
        visit_location:
          $ref: '#/components/schemas/VisitLocation'
        pickups:
          type: array
          items:
            $ref: '#/components/schemas/PickupActivity'
        deliveries:
          type: array
          items:
            $ref: '#/components/schemas/DeliveryActivity'
        timings:
          type: object
          properties:
            arrival_at:
              type: string
              format: date-time
              example: '2021-01-01T10:15:30Z'
              description: The planned time of arrival at the `Stop`
            location_stop_time:
              type: string
              example: PT45M
              description: >
                The stop time for this `Stop`. 


                Must be specified as a valid ISO Duration (see [wikipedia
                ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Durations) and
                [RFC-3339](https://datatracker.ietf.org/doc/html/rfc3339)). Must
                be non negative.
          required:
            - arrival_at
      required:
        - visit_location
        - timings
    PickupActivity:
      type: object
      properties:
        order:
          type: object
          properties:
            business_id:
              type: string
              pattern: ^[a-zA-Z0-9.~\-_]{1,512}$
              example: Order-1
              description: >
                Unique identifier for this `Pickup`. This must match the
                `business_id` for the corresponding `Delivery` in this
                `PartialRoute`.
            capacities:
              type: array
              maxItems: 8
              default: []
              uniqueItems: true
              items:
                $ref: '#/components/schemas/Capacity'
            requirements:
              $ref: '#/components/schemas/Requirements'
            labels:
              type: array
              description: >
                Labels can be used for identifying sets of `Orders` within a
                logistical optimization.
              uniqueItems: true
              default: []
              items:
                type: string
                example: labelA
            description:
              type: string
            custom_data:
              $ref: '#/components/schemas/CustomData'
          required:
            - business_id
        timings:
          $ref: '#/components/schemas/OrderTimings'
      required:
        - order
        - timings
    DeliveryActivity:
      type: object
      properties:
        order:
          type: object
          properties:
            business_id:
              type: string
              pattern: ^[a-zA-Z0-9.~\-_]{1,512}$
              example: Order-1
              description: >
                Unique identifier for this `Delivery`. This must match the
                `business_id` for the corresponding `Pickup` in this
                `PartialRoute`.
            requirements:
              $ref: '#/components/schemas/Requirements'
            labels:
              type: array
              default: []
              uniqueItems: true
              description: |
                Labels can be used for identifying sets of `Orders`.
              items:
                type: string
                example: labelA
            custom_data:
              $ref: '#/components/schemas/CustomData'
          required:
            - business_id
        timings:
          $ref: '#/components/schemas/OrderTimings'
      required:
        - order
        - timings
    Break:
      type: object
      properties:
        at:
          type: string
          format: date-time
          example: '2021-01-01T10:15:30Z'
          description: The planned start time of this `Break`
        duration:
          type: string
          example: PT8H
          description: >
            The duration of this `Break`.


            Must 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). Must be
            non negative.
      required:
        - at
        - duration
    OrderTimings:
      type: object
      properties:
        start_at:
          type: string
          format: date-time
          example: '2021-01-01T10:15:30Z'
          description: |
            The planned time of start for this activity. 

            Must be provided as an ISO-8601 formatted datetime.
        service_time:
          type: string
          example: PT5M
          description: >
            The duration required for executing this activity.


            Must 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). Must be
            non negative.
      required:
        - start_at
        - service_time
  responses:
    401Unauthorized:
      description: Authentication required
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    403Forbidden:
      description: Access forbidden
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    404NotFound:
      description: The entity is not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    409Conflict:
      description: >-
        Response status code indicates a request conflict with current state of
        the server.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    412PreconditionFailed:
      description: >
        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.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    clientCredentials:
      type: oauth2
      description: >
        This API uses OAuth2 with the Client Credentials flow for M2M
        communication. Client ID and secret should be provided as a HTTP Basic
        Auth header.
      flows:
        clientCredentials:
          tokenUrl: >-
            https://auth.conundra.eu/auth/realms/prod/protocol/openid-connect/token
          scopes: {}
