Fixed touchPointId casing; added SE query param "includeStatusHistory", remove text explaining mandatory query params for SE issuedvoucher, add explanation for automatic touchpointId filtering

src/openapi/products/SE-vouchers-supplier.yaml

@@ -57,8 +57,8 @@ paths:
                   summary: No products / Empty list
                   description: No products
                   value: { "voucherDefinitions": [] }
-                List containing one voucher definition (called by touchpointId 12):
+                List containing one voucher definition (called by touchPointId 12):
-                  summary: List containing one voucher definition (called by touchpointId 12)
+                  summary: List containing one voucher definition (called by touchPointId 12)
                   description: |- 
                    List containing one voucher definition for a voucher that can be redeemed for the product "Ooievaarspas voor AOW-ers in Den Haag".\
                    In this case, the voucher definition has a sellingPrice of 0, which means that vouchers issued from this voucher definition can be redeemed to acquire the requiredProduct for free. The requiredProduct also has a sellingPrice of 0, so no "discount" is shown to the customer; just the voucher's amountInclTax.\
@@ -199,12 +199,18 @@ paths:
       summary: Get a list of issued vouchers that were issued for a specific touch point
       description: |-
         Retrieve all issued vouchers that match the given query parameters. \
-        At least on of the following query parameters should be provided: 
+        Every request is automatically filtered to return only vouchers issued by the calling touch point (based on the touchPointId that is assigned to the caller's API credentials).
+        
+        Further filtering can be done by providing any of the following query parameters:
         - `issuedVoucherId` (internal and globally unique ID);
         - `voucherCode` (code that the customer uses for redeeming the voucher, can be reissued as long as only one instance is active at the same time);
-        - `productId` (the productId of the voucher definition).
+        - `productId` (the `productId` of the voucher definition);
+        - `voucherStatusId` (return only voucher instances with the given status(es));
+        - `statusChangedAfter` (only return voucher instances whose status changed after this date-time);
+        - `includeStatusHistory` (include the status history for each voucher instance).
 
-        When a voucher code has been issued multiple times, all issuedvouchers with the same voucher code will be returned, together with their statuses.
+
+        When a voucher code has been issued multiple times, all issuedvouchers with the same voucher code will be returned, together with their status (or optionally also the status history).
       parameters:
         - name: issuedVoucherId
           in: query
@@ -248,12 +254,20 @@ paths:
             - 3 = redeemed
             - 4 = revoked
             - 5 = expired
-            - 6 = pendingRedemption
+            - 6 = pendingRedemption        
           schema:
             type: array
             items:
               type: integer
             example: [4,5]
+        - name: includeStatusHistory
+          in: query
+          required: false
+          description: Include the status history for each voucher instance. Is false by default (if not provided).
+          schema:
+            type: boolean
+            example: false
+
       tags:
         - Vouchers
       responses:
@@ -330,6 +344,88 @@ paths:
                           }
                         ]
                     }
+                List containing one issued voucher, with status history:
+                  summary: List containing one issued voucher, with status history
+                  description: |-
+                    The same issued voucher is returned as was shown in the first example, but in this case 
+                    requested with query parameter `includeStatusHistory=true`.
+                  value:
+                    {
+                      "issuedVouchers":
+                        [
+                          {
+                            "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
+                            "voucherCode": "HTM-A7J-128-PYT",
+                            "fromInclusive": "2024-10-04T00:00:00.000",
+                            "untilInclusive": "2024-11-04T00:00:00.000",
+                            "voucherStatus": { "voucherStatusId": 2, "name": "issued", "reason": "Test reason" },
+                            "product":
+                              {
+                                "productId": 263,
+                                "productName": "Voucher Ooievaarspas-product AOW",
+                                "productDescription": "Voucher voor AOW-ers in Den Haag met een Ooievaarspas, die ingewisseld kan worden voor het product \"Ooievaarspas voor AOW-ers in Den Haag\"",
+                                "amountInclTax": 0,
+                                "requiredProducts":
+                                  [
+                                    {
+                                      "productId": 982,
+                                      "productName": "Ooievaarspas voor AOW-ers in Den Haag",
+                                      "productDescription": "Vrij reizen bij HTM voor Haagse AOW-gerechtigden met een Ooievaarspas.",
+                                      "productCategory": 
+                                        {
+                                          "productCategoryId": 2,
+                                          "isTravelProduct": true,
+                                          "name": "Afgekocht reisrecht",
+                                        },
+                                      "amountInclTax": 0
+                                      
+                                    },
+                                  ],
+                                  "_links":
+                                    {
+                                      "get_voucher_definition_details":
+                                        {
+                                          "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/voucherdefinitions/263",
+                                          "method": "GET",
+                                        },
+                                    },
+                              },
+                            "voucherClaims":
+                              [
+                                {
+                                  "mandatoryCustomerDataItem":
+                                    {
+                                      "mandatoryCustomerDataItemId": 8,
+                                      "customerDataItem": "padBirthDate",
+                                    },
+                                  "value": "1980-06-30",
+                                }
+                              ],
+                            "voucherStatusInstances":
+                              [
+                                {
+                                  "voucherStatusInstanceId": "ac8c54d1-79f7-4167-8817-c66b9575d679",
+                                  "voucherStatus":
+                                    { "voucherStatusId": 1, "name": "New" },
+                                  "createdOn": "2024-10-04T12:34:56.000",
+                                  "reason": null,
+                                },
+                                {
+                                  "voucherStatusInstanceId": "b01412e6-70fb-4c05-9bef-e65bf2747ca1",
+                                  "voucherStatus":
+                                    { "voucherStatusId": 2, "name": "Issued" },
+                                  "createdOn": "2024-10-04T12:37:14.000",
+                                  "reason": "test reason",
+                                },
+                              ],
+                            "metadata1": null,
+                            "metadata2": null,
+                            "metadata3": null,
+                            "metadata4": null,
+                            "metadata5": null
+                          }
+                        ]
+                    }
                 List containing one issued voucher that grants a product for a reduced price:
                   summary: List containing one issued voucher that grants a product for a reduced price
                   description: |-
@@ -1267,6 +1363,10 @@ components:
               value:
                 type: string
                 example: 1970-01-01
+        voucherStatusInstances:
+          type: array
+          items:
+            $ref: "#/components/schemas/voucherStatusInstance"                        
         metadata1:
           type: string
           description: Field for storing custom metadata.
@@ -1286,7 +1386,37 @@ components:
         metadata5:
           type: string
           description: Field for storing custom metadata.
-          example: "Some metadata"                
+          example: "Some metadata"   
+    voucherStatusInstance:
+      type: object
+      required:
+        - voucherStatusInstanceId
+        - voucherStatus
+        - createdOn
+      properties:
+        voucherStatusInstanceId:
+          type: string
+          format: uuid
+          example: 42efebf7-132e-4ee0-9cbb-4037a9a54ad8
+        voucherStatus:
+          type: object
+          required:
+            - voucherStatusId
+            - name
+          properties:
+            voucherStatusId:
+              type: integer
+              example: 4
+            name:
+              type: string
+              example: "Revoked"
+        createdOn:
+          type: string
+          format: date-time-offset
+          example: "2021-05-23T12:00:00.000+02:00"
+        reason:
+          type: string
+          example: "Voucher revoked because it was redeemed by an unauthorized user."
     unavailable:
       type: object
     rfc9457:

src/openapi/products/purchased_products-crud.yaml

@@ -209,7 +209,7 @@ paths:
                                 {
                                   "issuedVoucherId": "e1f2g3h4-i5j6-k7l8-m9n0-o1p2q3r4s5t6",
                                   "voucherCode": "VOUCHER12345",
-                                  "touchpointId": 23,
+                                  "touchPointId": 23,
                                   "metadata1": null,
                                   "metadata2": null,
                                   "metadata3": null,
@@ -368,7 +368,7 @@ paths:
                       [
                         {
                           "voucherCode": "VOUCHER123",
-                          "touchpointId": 23,
+                          "touchPointId": 23,
                           "metadata1": null,
                           "metadata2": null,
                           "metadata3": null,
@@ -539,7 +539,7 @@ paths:
                           {
                             "issuedVoucherId": "e1f2g3h4-i5j6-k7l8-m9n0-o1p2q3r4s5t6",
                             "voucherCode": "VOUCHER12345",
-                            "touchpointId": 23,
+                            "touchPointId": 23,
                             "metadata1": null,
                             "metadata2": null,
                             "metadata3": null,
@@ -1219,7 +1219,7 @@ paths:
             example:
               {
                 "voucherCode": "VOUCHER123",
-                "touchpointId": 23,
+                "touchPointId": 23,
                 "metadata1": null,
                 "metadata2": null,
                 "metadata3": null,
@@ -1326,7 +1326,7 @@ paths:
                         "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
                         "purchasedProductId": "058a1af7-897f-45d5-b691-9cc9161e387f",
                         "voucherCode": "VOUCHER123",
-                        "touchpointId": 23,
+                        "touchPointId": 23,
                         "metadata1": null,
                         "metadata2": null,
                         "metadata3": null,
@@ -1525,56 +1525,6 @@ components:
           format: date-time
           description: The date-time at which the ticket will become invalid for traveling. The ticket will not be valid after this date/time.
           example: 2024-10-06T12:34:56.000
-    BulkResponseBody:
-      type: object
-      properties:
-        startTime:
-          type: string
-          format: date-time
-          example: 2025-02-14T05:32:47.0672237Z
-        status:
-          type: string
-          example: Running
-        clientTrackingId:
-          type: string
-          example: 08584620957189579629541919368CU00
-        callbackurl:
-          type: string
-          format: uri
-          example: https://services.api.htm.nl/purchasedproducts/responsestatus/runtime/webhooks/workflow/scaleUnits/prod-00/workflows/6fd466916c
-        retryAfter:
-          type: integer
-          example: 10
-        summary:
-          $ref: "#/components/schemas/summaryBody"
-      required:
-        - startTime
-        - status
-        - clientTrackingId
-        - callbackurl
-        - retryAfter
-        - summary
-    summaryBody:
-      type: object
-      properties:
-        summary:
-          type: object
-          properties:
-            created:
-              type: integer
-              example: 15
-            updated:
-              type: integer
-              example: 2
-            total:
-              type: integer
-              example: 17
-          required:
-            - created
-            - total
-            - updated
-      required:
-        - summary
     rfc9457:
       type: object
       properties: