Upsert a location with specified business Id

Request

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.

Security

clientCredentials

Path

business_idstring^[a-zA-Z0-9.~\-_]{1,512}$required

The business identifier of an entity instance

If-Matchstring

weak Etag as optimistic locking check

PreferArray of strings

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

The following behavior is supported by this API:

return=<minimal|representation> is used to suggest the server to return using status code 204 without a resource in the response body (minimal) or using status codes 200 or 201 with the resource in the response body on success (representation).

Bodyapplication/jsonrequired

business_idstring^[a-zA-Z0-9.~\-_]{1,512}$required

Unique reference id

Example:"locationA"

location_categorystring, non-empty^\S.*

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.

When provided, the value must not be blank.

Example:"locationCategoryA"

namestring

An optional name that helps in identifying the Location.

Example:"locationName"

descriptionstring

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

Example:"locationDescription"

commentstring

A freeform text field for adding comments to a Location.

Example:"locationComment"

addressobject(GeoAddress)required

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

planning_addressobject(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_timestring(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). Must be non negative.

Example:"PT5M"

requirementsobject(Requirements)

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

time_windowobject(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.

planning_time_windowobject(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.

custom_dataobject(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.

Example:

{
  "shop_manager": "John Smith"
}

ignore_consecutive_restrictionsboolean

When set to true, consecutive visit restrictions will be ignored for this Location during planning.

labelsArray of strings, <= 100 items

Default:[]

etagstring(Etag)

Must match header if provided on request.

Example:"W/\"1\""

curl -i -X PUT \
  'https://developer.conundra.eu/_mock/apis/order-book/order-book-api/locations/{business_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'If-Match: string' \
  -H 'Prefer: string' \
  -d '{
    "business_id": "locationA",
    "location_category": "locationCategoryA",
    "name": "locationName",
    "description": "locationDescription",
    "comment": "locationComment",
    "address": {
      "address_line": "Voordries 41",
      "city": "Oosterzele",
      "zip_code": "9860",
      "country_code": "BE",
      "geo_point": {
        "latitude": 50.9514048,
        "longitude": 3.8067878
      }
    },
    "planning_address": {
      "address_line": "Voordries 41",
      "city": "Oosterzele",
      "zip_code": "9860",
      "country_code": "BE",
      "geo_point": {
        "latitude": 50.9514048,
        "longitude": 3.8067878
      }
    },
    "stop_time": "PT5M",
    "requirements": {
      "tags": [],
      "forbidden_tags": []
    },
    "time_window": {
      "description": "a description",
      "windows": [
        {
          "open_time": "14:45",
          "open_day": "MONDAY",
          "close_time": "14:45",
          "close_day": "MONDAY",
          "cost": 0
        }
      ]
    },
    "planning_time_window": {
      "description": "a description",
      "windows": [
        {
          "open_time": "14:45",
          "open_day": "MONDAY",
          "close_time": "14:45",
          "close_day": "MONDAY",
          "cost": 0
        }
      ]
    },
    "custom_data": {
      "shop_manager": "John Smith"
    },
    "ignore_consecutive_restrictions": true,
    "labels": [],
    "etag": "W/\"1\""
  }'

Responses

Indicates the locations is created or updated.

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

Headers

ETagstring

weak Etag (ex W/<etag_value>) which contains the (updated) version of the entity

Preference-Appliedstring

to indicate whether a preference has been applied. (ex Preference-Applied: return=representation)

Bodyapplication/json

dataobject(Location)

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.

Response

{
  "data": {
    "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": { … },
    "ignore_consecutive_restrictions": true,
    "labels": [],
    "etag": "W/\"1\""
  }
}