ReDoc documentation

Locations

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.

Find out more

Get a list of all locations by ids

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.

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

A comma-separated list of Location business IDs.

Responses
200

a list of locations

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

Get a list of locations by filter criteria

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.

Securitykeycloak
Request
query Parameters
location_categorycategory
string

Filter results based on category

country_code
string (CountryCode) ^[A-Z]{2}$

Filter results based on country identifier (ISO3166-1 alpha-2).

Example: country_code=BE
zip_code
string

Filter results based on ZIP code

city
string

Filter results based on city

address_line
string

collection filtered on address line

page
integer <int32> >= 1
Default: 1

Number of the page to retrieve, see also Paging section.

page_size
integer <int32> [ 1 .. 100 ]
Default: 10

Number of results by page, see also Paging section.

Responses
200

a list of locations

default

General error payload

get/locations/by
Response samples
application/json
{
  • "data": [
    ],
  • "page": {
    }
}

Get a location with specified business Id

Retrieve a single location by its business id.

Securitykeycloak
Request
path Parameters
business_id
required
string

The business identifier of an entity instance

header Parameters
X-Conundra-Unwrap
string

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

Responses
200

OK

404

The entity is not found

default

General error payload

get/locations/{business_id}
Response samples
application/json
{
  • "data": {
    }
}

Upsert a location with specified business Id

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.

Securitykeycloak
Request
path Parameters
business_id
required
string

The business identifier of an entity instance

header Parameters
If-Match
string

weak Etag as optimistic locking check

Prefer
Array of strings

The RFC7240 Prefer header indicates that a particular server behavior is preferred by the client but is not required for successful completion of the request (see RFC 7240).

The following behavior is supported by this API:

  • return=<minimal|representation> is used to suggest the server to return using status code 204 without a resource in the response body (minimal) or using status codes 200 or 201 with the resource in the response body on success (representation).
Request Body schema: application/json
required
business_id
required
string

Unique reference id

location_category
string

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
string

An optional name that helps in identifying the Location.

description
string

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

comment
string

A freeform text field for adding comments to a Location.

required
object (GeoAddress)

The main, physical address for this Location. This address as mandatory for creating/updating a Location.

object (GeoAddress)

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.

stop_time
string (IsoDuration)

The stop time to be applied when visiting this Location. Must be specified as a valid ISO Duration (see wikipedia ISO-8601 and RFC-3339).

object (Requirements)

Requirements that have to be fulfilled by the executor of an order at this location.

object (TimeWindows)

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.

object (TimeWindows)

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.

object (CustomData)

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.

etag
string (Etag)

Must match header if provided on request.

Responses
201

Indicates the locations is created or updated.

The response body contains the location, since Prefer is set to return=representation.

204

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.

404

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.

412

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

default

General error payload

put/locations/{business_id}
Request samples
application/json
{
  • "business_id": "locationA",
  • "location_category": "locationCategoryA",
  • "name": "locationName",
  • "description": "locationDescription",
  • "comment": "locationComment",
  • "address": {
    },
  • "planning_address": {
    },
  • "stop_time": "PT5M",
  • "requirements": {
    },
  • "time_window": {
    },
  • "planning_time_window": {
    },
  • "custom_data": {
    },
  • "etag": "W/\"1\""
}
Response samples
application/json
{
  • "data": {
    }
}

Delete a location with specified business Id

This endpoint allows you to delete a location.

Securitykeycloak
Request
path Parameters
business_id
required
string

The business identifier of an entity instance

header Parameters
If-Match
string

weak Etag as optimistic locking check

Responses
204

Deletion has succeeded, but body is empty

404

The entity is not found

409

Typically indicates that this Location is still in use by an Order that is executable in the future.

default

General error payload

delete/locations/{business_id}
Response samples
application/problem+json
{}
➔ Next to Conditionals