API Change Protocol - 20250503 - PaymentState

What we want to change:

Add ability to get, set and update state for reservation payment

Why we want to change:

To get/set/update state for payment

When we want to change:

Test environment: In sprint 2506 from 28. 2. 2025 to 13. 3. 2025

Production environemnt: In sprint 2506 from 28. 2. 2025 to 13. 3. 2025

Affected enpoints

POST /{v1,v2}/reservation

PATCH /{v1,v2}/reservation

GET /{v1,v2}/reservation

GET /v2/reservations

Example of change:

When a caller wants to specify and get paymentState (focus on a new paymentState field on line 25 inside request body and in response body line 27).

Request:

curl -X 'POST' \
  'http://localhost:5146/parcel-lockers/v2/reservation?fields%5Breservation%5D=blocked&fields%5Breservation%5D=openerKey&fields%5Breservation%5D=docNumber&fields%5Breservation%5D=flowType&fields%5Breservation%5D=prereservationExpirationDate&fields%5Breservation%5D=nextReservationTimes' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "data": {
    "reservation": {
      "id": "kuz1-res1-test12",
      "attributes": {
        "expirationDate": "2025-03-08T10:53:42.514Z",
        "startReservationDate": "2025-03-07T10:53:42.514Z",
        "blocked": false,
        "packages": [
          {
            "depth": 3.5,
            "height": 2.8,
            "width": 4.2,
            "barcode": "kuz1-pkg1-test12"
          }
        ],
        "paymentData": {
          "price": 15,
          "currency": "EUR",
          "variableSymbol": "1778881",
          "paymentState": "PAID"
        },
      },
      "relationships": {
        "box": {
          "id": 56
        },
      }
    }
  }
}'

Response:

{
  "data": {
    "id": "kuz1-res1-test12",
    "attributes": {
      "status": "RESERVED",
      "blocked": false,
      "openerKey": "PARC113793174",
      "createdAt": "2025-03-07T08:13:02.3895124Z",
      "expirationDate": "2025-03-08T10:53:42.514Z",
      "startReservationDate": "2025-03-07T10:53:42.514Z",
      "prereservationExpirationDate": null,
      "docNumber": "kuz1-res1-test12",
      "flowType": "OUTLET",
      "packages": [
        {
          "depth": 3.5,
          "height": 2.8,
          "width": 4.2,
          "barcode": "kuz1-pkg1-test12",
          "packageState": "DISPATCHED"
        }
      ],
      "paymentData": {
        "price": 15,
        "currency": "EUR",
        "variableSymbol": "1778881",
        "paymentState": "PAID"
      },
      "pin": "868857",
      "type": "IMMEDIATE",
      "nextReservationTimes": []
    },
    "relationships": {
      "box": {
        "id": 56,
        "pid": null
      }
    }
  },
  "metadata": null,
  "errors": null
}

Request:

curl -X 'GET' \
  'http://localhost:5146/parcel-lockers/v2/reservation?filter%5Bid%5D=kuz1-res1-test12&fields%5Breservation%5D=docNumber&fields%5Breservation%5D=flowType&fields%5Breservation%5D=prereservationExpirationDate&fields%5Breservation%5D=nextReservationTimes' \
  -H 'accept: application/json'

Response:

{
  "data": {
    "reservation": {
      "id": "kuz1-res1-test12",
      "attributes": {
        "status": "RESERVED",
        "createdAt": "2025-03-07T08:13:02.373Z",
        "expirationDate": "2025-03-08T10:53:42.513Z",
        "startReservationDate": "2025-03-07T10:53:42.513Z",
        "prereservationExpirationDate": null,
        "docNumber": "kuz1-res1-test12",
        "flowType": "OUTLET",
        "packages": [
          {
            "depth": 3.5,
            "height": 2.8,
            "width": 4.2,
            "barcode": "kuz1-pkg1-test12",
            "packageState": "DISPATCHED"
          }
        ],
        "paymentData": {
          "price": 15,
          "currency": "EUR",
          "variableSymbol": "1778881",
          "paymentState": "PAID"
        },
        "pin": "868857",
        "type": "IMMEDIATE",
        "nextReservationTimes": []
      },
      "relationships": {
        "box": {
          "id": 56,
          "pid": null
        }
      }
    }
  },
  "metadata": null,
  "errors": null
}

And similar for other endpoints.

API specification diff:

Test Prod

AB for developers