API Change Protocol - 20240719 - Prereservation

What we want to change:

Make it possible for partners to create such reservation (in status PRERESERVED) that can wait for a set amount of time for it to be reserved "status": "RESERVED".

For such functionality new field must be introduced:

prereservationExpirationDate

Also a few new fields migt have to be supported in callbacks by partners, who want to leverage this new funcionality:

startReservationDate
expirationDate

Please note this functionality can (but doesn’t have to) be used with the NextReservationTimes, see API Change protocol - 20231110 - NextReservationTimes input parameter

Why we want to change:

To make the reservation algorithm more fair

When we want to change:

Stage environment: During sprint 2417 (from 1. 8. to 15. 8.)

Production environemnt: During sprint 2417 (from 1. 8. to 15. 8.)

Affected enpoints

POST /v2/reservation

PATCH /v2/reservation

Examples of change:

POST

For more information see https://alzabox.atlassian.net/wiki/x/AgBjEw.

Check lanes 9, 15, 22 and 27.

POST /parcel-lockers/v2/reservation
{
  "data": {
    "reservation": {
      "id": "RES123",
      "attributes": {
        "startReservationDate": "2023-11-09T10:00:00.000Z",
        "expirationDate": "2023-11-13T10:00:00.000Z",
        "prereservationExpirationDate": "2023-11-09T02:00:00.000Z",
        "type": "TIME",
        ...
        "nextReservationTimes": [
          {
            "startReservationDate": "2023-11-10T10:00:00.000Z",
            "prereservationExpirationDate": "2023-11-10T02:00:00.000Z",
            //NOTE: Note the missing expiration date, since it is optional
            //the root 'expirationDate' will be used, that is "2023-11-13T10:00:00.000Z"
          },
          {
            "startReservationDate": "2023-11-11T10:00:00.000Z",
            "expirationDate": "2023-11-13T10:00:00.000Z",
            "prereservationExpirationDate": "2023-11-11T02:00:00.000Z",
          },
          {
            "startReservationDate": "2023-11-12T10:00:00.000Z",
            "expirationDate": "2023-11-14T10:00:00.000Z",
            "prereservationExpirationDate": "2023-11-12T02:00:00.000Z",
          }
        ]
      }
    }
  }
}

PATCH

For more information see https://alzabox.atlassian.net/wiki/x/BgDrFQ.

Update the root time slot prereservationExpirationDate:

Check lane 6

{
  "data": {
    "reservation": {
      "id": "id_prereservation_efae3b16-5d13-4978-bb2b-a790f9a541e1",
      "attributes":{
        "prereservationExpirationDate":"2024-08-25T13:35:00.000Z"
      }
    }
  }
}

Update (one or more) next reservation time slot window(s):

{
  "data": {
    "reservation": {
      "id": "id_prereservation_efae3b16-5d13-4978-bb2b-a790f9a541e1",
      "attributes": {
        "nextreservationtimes":[
            {
                "expirationDate": "2024-08-25T16:00:00.000Z",
                "startReservationDate": "2024-08-25T14:00:00.000Z",
                "prereservationExpirationDate":"2024-08-25T13:35:00.000Z"
            }
        ]
      }
    }
  }
}

Responses

Responses remain unchanged, however you can query additional new attributes:

PrereservationExpirationDate,
NextReservationTimes.

For more information, see the documentation https://alzabox.atlassian.net/wiki/spaces/ABD/pages/325255170/Prereservation#Response.