diff --git a/src/openapi/products/SE-vouchers-supplier.yaml b/src/openapi/products/SE-vouchers-supplier.yaml index b7a67a8..e85f7e5 100644 --- a/src/openapi/products/SE-vouchers-supplier.yaml +++ b/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): - summary: 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) 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: diff --git a/src/openapi/products/purchased_products-crud.yaml b/src/openapi/products/purchased_products-crud.yaml index c43eb6d..0521741 100644 --- a/src/openapi/products/purchased_products-crud.yaml +++ b/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: