Booking phase

General

The booking phase is more complex: in a transactional way we have to book all the legs/assets.
The first step is that the end user will select a route to take. The MP will have to post a call to the ​/bookings-options end point to let the TO's know that this he's intending to book this asset for the requested leg.

If the TO requested extra personal data (using the conditionRequireBookingData), the result should also contain the requested fields.

POST https://exampleTO.com/bookings/
{
  "id": "746ac-48792bb-746dac3", ** this is the ID provided in the planning phase **
  "customer": {
    "id": 123456,
    "firstName": "John",
    "lastName": "Doe",
    "phone": "tring"
  }
}

The result can be (=booking object):

{
  "id": "746ac-48792bb-746dac3",
  "customer": {
    "id": 123456,
    "firstName": "John",
    "lastName": "Doe",
    "phone": "string"
  },
  "state": "PENDING", ** this is a new booking in state pending **
  "terms": "some text",
  "token": {
    "validityDuration": {
      "from": 1546336800,
      "to": 1546336800,
      "meta": []
    }
  },
  "webhook": "https://myMSP.com/booking/746ac-48792bb-746dac3/events",
  "meta": []
}

The webhook is optionally provided to send e.g. expires or cancels to the MP. If there is no webhook property, the TO should call the end points in this API to communicate with the MP.

After sending the request to all needed TO's - and they all responded positively, the MP will have to send a POST request with the operation 'COMMIT' in it to change the booking-option into a real booking.

POST https://exampleTO.com/booking/{id}/events/
{
  "operation": "COMMIT"
}

The result will be a booking object, in state COMFIRMED. The webhook in the booking object can be used to communicate from TO to MP about the asset or booked leg.

{
  "id": "746ac-48792bb-746dac3",
  "customer": {
    "id": 123456,
    "firstName": "John",
    "lastName": "Doe",
    "phone": "string"
  },
  "state": "CONFIRMED", ** this is a confirmed booking **
  "terms": "some text",
  "token": {
    "validityDuration": {
      "from": 1546336800,
      "to": 1546336800,
      "meta": []
    }
  },
  "webhook": "https://myMSP.com/booking/746ac-48792bb-746dac3/events",
  "meta": []
}

In case of an expired or cancelled booking option, the TO can send a POST booking-option to the MP (as described in the API) or -in case a webhook is provided- call the webhook for these operations. The MP can also call the TO to cancel the booking-option.

In case of assets that will be opened offline, the 'token' should provide the information to open the asset.

So, the route is booked, the user can be informed everything is OK. The trip can be made. Look at the next section: trip execution.

In case the user is changing her/his mind, the booking can be cancelled by sending a cancel-event to https://exampleTO.com/bookings/{id}/events/.

Diagrams

POSTPONED COMMIT

During the planning phase the TO can send a 'conditionPostponedCommit'. The MP should keep this in mind, the process flow of these legs is quite different. The returned booked leg is in state 'CONDITIONAL_CONFIRMED' and will later on be committed or denied, using the /booking/{id}/events endpoint.