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 2418 (from 1. 8. to 15. 8.)

Production environemnt: During sprint 2418 (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:

See updated time on line 6

Also notice that the nextReservationTimes have to be always supplied!

{
  "data": {
    "reservation": {
      "id": "RES123",
      "attributes":{
        "prereservationExpirationDate": "2023-11-09T06:00:00.000Z",
        "nextReservationTimes": [
          {
            "startReservationDate": "2023-11-10T10:00:00.000Z",
            "prereservationExpirationDate": "2023-11-10T02: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"
          }
        ]
      }
    }
  }
}

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

See updated time on lines 13 and 14 compared to the original POST request

{
  "data": {
    "reservation": {
      "id": "RES123",
      "attributes": {
        "nextReservationTimes": [
          {
            "startReservationDate": "2023-11-10T10:00:00.000Z",
            "prereservationExpirationDate": "2023-11-10T02:00:00.000Z"
          },
          {
            "startReservationDate": "2023-11-11T10:00:00.000Z",
            "expirationDate": "2023-11-13T16:00:00.000Z",
            "prereservationExpirationDate": "2023-11-11T08:00:00.000Z"
          },
          {
            "startReservationDate": "2023-11-12T10:00:00.000Z",
            "expirationDate": "2023-11-14T10:00:00.000Z",
            "prereservationExpirationDate": "2023-11-12T02:00:00.000Z"
          }
        ]
      }
    }
  }
}

Responses

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

PrereservationExpirationDate,
NextReservationTimes.

For more information, see the documentation Prereservation | Response.

AB for developers