API Change Protocol - 20230320 - Patch box endpoint

Change protocol about new PATCH endpoint for updating box PID (partner identification of a box).

What we want to change:

We are adding possibility for partner to update box PID, so that partner is able to manage its naming of boxes.

Why we want to change:

We added custom naming of boxes as a result of partners requreiment. They wanted to work with boxes with names they use and know.
Currently it is quite difficult to add or update box PID. It requires work of AB development team.
With this new endpoint partner is able to add or update PID and no work from the development team is needed.

When we want to change:

This functionality will be added during sprint 2307.

Affected enpoints

/v2/box

Example of change:

We want to add or update PID for box with ID 1837, PID will be ”MyBox456”. We’d like to return just name of the box and identificators ID and PID.

We will call PATCH request:

/parcel-lockers/v2/box?fields%5Bbox%5D=name

with body:

{
  "data": {
    "box": {
      "id": 1837,
      "pid": "MyBox456"
    }
  }
}

And we should get successful response:

{
  "data": {
    "box": {
      "id": 1837,
      "pid": "MyBox456",
      "attributes": {
        "name": "Brno (Pasáž Rozkvět)"
      }
    }
  },
  "metadata": null,
  "errors": null
}

We could get error response, e.g. in case we want to update PID of unexisted or not accessible box 123456:

API specification diff:

Patch box PID by vladimir-zak-alza · Pull Request #9 · AlzaBox/AlzaBox-API-Description (github.com)