From 7ab0de07c486112fbf1c309680b55665ce202239 Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Wed, 11 Feb 2026 12:01:45 +0100 Subject: [PATCH 1/9] OVPAY-2442 - Created endpoints for GET /voucherdefinitions and /issuedvouchers. --- src/openapi/products/vouchers-se.yaml | 442 ++++++++++++++++++++------ 1 file changed, 352 insertions(+), 90 deletions(-) diff --git a/src/openapi/products/vouchers-se.yaml b/src/openapi/products/vouchers-se.yaml index c8423d2..adf7db0 100644 --- a/src/openapi/products/vouchers-se.yaml +++ b/src/openapi/products/vouchers-se.yaml @@ -6,17 +6,275 @@ info: servers: - url: https://services.acc.api.htm.nl/abt/abtvouchers/1.0 paths: - /issuedvouchers/{voucherCode}: + /voucherdefinitions: get: - summary: Get voucher details by voucher code - description: Retrieve voucher details using its unique voucher code. + tags: + - Vouchers + summary: Get a list of all voucher definitions that a touch point is allowed to issue + description: |- + Get a list of all voucher definitions that the calling touch point is allowed to issue. + Essentially, this means that only products that have active sellingPeriods for touch points within the same + retailer as the calling touch point are returned. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/unavailable" + examples: + No products / Empty list: + summary: No products / Empty list + description: No products + value: { "Entries": [] } + List containing one product with many null attributes: + summary: List containing one product with many null attributes + description: |- + Most product attributes are optional on a database level and can thus be null; this example shows that all attributes as defined in the schema are always represented in the response, even if null. \ + **Empty lists/arrays show up as "[]", not as null!** + value: + { + "Entries": + [ + { + "productId": 99, + "productName": null, + "productDescription": null, + "productCategory": null, + "tokenTypes": [], + "sellableTouchpointIds": [], + "amountInclTax": null, + "imageReference": null, + "productPageUrl": null, + "_links": + { + "get_details": + { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/99", + "method": "GET", + }, + }, + }, + ], + } + List containing one product with 4 currently active SellingPeriods (called by touchpointId 1): + summary: List containing one product with 4 currently active SellingPeriods (called by touchpointId 1) + description: Only two sellingPeriods for touch point 1 and/or 2 (part of same retailer) are returned - the price for touchpointId 1 is returned + value: + { + "Entries": + [ + { + "productId": 2, + "productName": "HTM dagkaart", + "productDescription": "Reis een dag met het openbaar vervoer bij HTM", + "productCategory": + { + "productCategoryId": 5, + "isTravelProduct": false, + "name": "Barcode", + }, + "tokenTypes": [], + "sellableTouchpointIds": [1, 2], + "amountInclTax": 300, + "imageReference": "https://www.htm.nl/media/leif2leu/htm-logo-mobile.svg", + "productPageUrl": "https://www.htm.nl/nog-onbekende-product-pagina", + "_links": + { + "get_details": + { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/2", + "method": "GET", + }, + }, + }, + ], + } + List containing one product with 4 currently active SellingPeriods (called by touchpointId 3): + summary: List containing one product with 4 currently active SellingPeriods (called by touchpointId 3) + description: Only two sellingPeriods for touchpoint 3 and/or 4 (part of same retailer) are returned - the price for touchpointId 3 is returned + value: + { + "Entries": + [ + { + "productId": 2, + "productName": "HTM dagkaart", + "productDescription": "Reis een dag met het openbaar vervoer bij HTM", + "productCategory": + { + "productCategoryId": 5, + "isTravelProduct": false, + "name": "Barcode", + }, + "tokenTypes": [], + "sellableTouchpointIds": [3, 4], + "amountInclTax": 300, + "imageReference": "https://www.htm.nl/media/leif2leu/htm-logo-mobile.svg", + "productPageUrl": "https://www.htm.nl/nog-onbekende-product-pagina", + "_links": + { + "get_details": + { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/2", + "method": "GET", + }, + }, + }, + ], + } + List containing one product which can only be sold by touchpointId 3 (called by touchpointId 4): + summary: List containing one product which can only be sold by touchpointId 3 (called by touchpointId 4) + description: Product is still returned (because touchpointId 3 is part of same retailer) but no price, as touchpointId 4 is not allowed to sell this product. + value: + { + "Entries": + [ + { + "productId": 49, + "productName": "HTM Regio Vrij", + "productDescription": "Voor een vast bedrag onbeperkt reizen met EBS, HTM en RET in het gekozen gebied in de regio Rotterdam Den Haag.", + "productCategory": + { + "productCategoryId": 2, + "isTravelProduct": true, + "name": "Afgekocht reisrecht", + }, + "tokenTypes": [], + "sellableTouchpointIds": [3], + "amountInclTax": null, + "imageReference": "https://www.htm.nl/media/leif2leu/htm-logo-mobile.svg", + "productPageUrl": "https://www.htm.nl/nog-onbekende-product-pagina", + "_links": + { + "get_details": + { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/49", + "method": "GET", + }, + }, + }, + ], + } + List containing one product which can be sold by touchpointId 3 and 4 (called by touchpointId 4): + summary: List containing one product which can be sold by touchpointId 3 and 4 (called by touchpointId 4) + description: Product is returned + value: + { + "Entries": + [ + { + "productId": 126, + "productName": "HTM-30001", + "productDescription": "Reis met 20% korting op je betaalpas bij HTM.", + "productCategory": + { + "productCategoryId": 1, + "isTravelProduct": true, + "name": "Kortingsabonnement", + }, + "tokenTypes": [{ "tokenTypeId": 1, "name": "EMV" }], + "sellableTouchpointIds": [3, 4], + "amountInclTax": 300, + "imageReference": "https://www.htm.nl/media/leif2leu/htm-logo-mobile.svg", + "productPageUrl": "https://www.htm.nl/nog-onbekende-product-pagina", + "_links": + { + "get_details": + { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/126", + "method": "GET", + }, + }, + }, + ], + } + List containing multiple products (called by touchpointId 3): + summary: List containing multiple products (called by touchpointId 3) + description: Only products that have active SellingPeriods for touchpoint 3 and/or 4 (part of same retailer) are returned + value: + { + "Entries": + [ + { + "productId": 2, + "productName": "HTM dagkaart", + "productDescription": "Reis een dag met het openbaar vervoer bij HTM", + "productCategory": + { + "productCategoryId": 5, + "isTravelProduct": false, + "name": "Barcode", + }, + "tokenTypes": [], + "sellableTouchpointIds": [3, 4], + "amountInclTax": 300, + "imageReference": "https://www.htm.nl/media/leif2leu/htm-logo-mobile.svg", + "productPageUrl": "https://www.htm.nl/nog-onbekende-product-pagina", + "_links": + { + "get_details": + { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/2", + "method": "GET", + }, + }, + }, + { + "productId": 4, + "productName": "HTM 40% korting", + "productDescription": "Reis een maand lang met 40% korting!", + "productCategory": + { + "productCategoryId": 1, + "isTravelProduct": true, + "name": "Kortingsabonnement", + }, + "tokenTypes": [{ "tokenTypeId": 1, "name": "EMV" }], + "sellableTouchpointIds": [3, 4], + "amountInclTax": 800, + "imageReference": "https://www.htm.nl/media/leif2leu/htm-logo-mobile.svg", + "productPageUrl": "https://www.htm.nl/nog-onbekende-product-pagina", + "_links": + { + "get_details": + { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/4", + "method": "GET", + }, + }, + }, + ], + } + /issuedvouchers: + get: + summary: Get a list of issued vouchers that were issued for a specific touch point + description: + Retrieve all issued vouchers for a specific touch point. This means that only products that have active sellingPeriods for touch points within the same + retailer as the calling touch point are returned. parameters: - - name: voucherCode - in: path - required: true - description: The unique code of the voucher details to retrieve. + - name: issuedVoucherId + in: query + required: false + description: The unique identifier of the issued voucher instance to retrieve. schema: type: string + format: uuid + example: d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90 + - name: voucherCode + in: query + required: false + description: The unique code of the issued voucher to retrieve. + schema: + type: string + example: VOUCHER123 + - name: productId + in: query + required: false + description: The unique identifier of the product for which to retrieve all issued vouchers. + schema: + type: integer + example: 263 tags: - Vouchers responses: @@ -31,100 +289,104 @@ paths: summary: Voucher for a single product with required attributes value: { - "issuedVoucher": - { - "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", - "voucherCode": "VOUCHER123", - "fromInclusive": "2024-10-04T00:00:00.000", - "untilInclusive": "2024-11-04T00:00:00.000", - "voucherStatus": - { "voucherStatusId": 1, "name": "New" }, - "product": - { - "productId": 263, - "productName": "HTM-80001", - "productDescription": "10 euro korting op Regiovrij maand.", - "productCategory": - { - "productCategoryId": 9, - "isTravelProduct": false, - "name": "Voucher", - }, - "amountInclTax": -1000, - "requiredProducts": - [ + "issuedVouchers": + [ + { + "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", + "voucherCode": "VOUCHER123", + "fromInclusive": "2024-10-04T00:00:00.000", + "untilInclusive": "2024-11-04T00:00:00.000", + "voucherStatus": + { "voucherStatusId": 1, "name": "New" }, + "product": + { + "productId": 263, + "productName": "HTM-80001", + "productDescription": "10 euro korting op Regiovrij maand.", + "productCategory": { - "productId": 126, - "productName": "HTM-30001", - "productDescription": "Reis met 20% korting op je betaalpas bij HTM.", - "_links": + "productCategoryId": 9, + "isTravelProduct": false, + "name": "Voucher", + }, + "amountInclTax": -1000, + "requiredProducts": + [ + { + "productId": 126, + "productName": "HTM-30001", + "productDescription": "Reis met 20% korting op je betaalpas bij HTM.", + "_links": + { + "get_details": + { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/126", + "method": "GET", + }, + }, + }, + ], + "_links": + { + "get_details": { - "get_details": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/126", - "method": "GET", - }, + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/263", + "method": "GET", }, }, - ], - "_links": + }, + "mandatoryCustomerDataItems": + [ { - "get_details": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/263", - "method": "GET", - }, + "mandatoryCustomerDataItemId": 8, + "customerDataItem": "padBirthDate", }, - }, - "mandatoryCustomerDataItems": - [ - { - "mandatoryCustomerDataItemId": 8, - "customerDataItem": "padBirthDate", - }, - { - "mandatoryCustomerDataItemId": 4, - "customerDataItem": "emailAddress", - }, - ], - }, + { + "mandatoryCustomerDataItemId": 4, + "customerDataItem": "emailAddress", + }, + ], + }, + ], } Voucher for a whole order: summary: Voucher for a whole order value: { - "issuedVoucher": - { - "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", - "voucherCode": "VOUCHER123", - "fromInclusive": "2024-10-04T00:00:00.000", - "untilInclusive": "2024-11-04T00:00:00.000", - "voucherStatus": - { "voucherStatusId": 1, "name": "New" }, - "product": - { - "productId": 263, - "productName": "HTM-80002", - "productDescription": "10 euro korting op je gehele winkelmand.", - "productCategory": - { - "productCategoryId": 9, - "isTravelProduct": false, - "name": "Voucher", - }, - "amountInclTax": -1000, - "requiredProducts": [], - "_links": - { - "get_details": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/263", - "method": "GET", - }, - }, - }, - }, - "mandatoryCustomerDataItems": [], + "issuedVouchers": + [ + { + "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", + "voucherCode": "VOUCHER123", + "fromInclusive": "2024-10-04T00:00:00.000", + "untilInclusive": "2024-11-04T00:00:00.000", + "voucherStatus": + { "voucherStatusId": 1, "name": "New" }, + "product": + { + "productId": 263, + "productName": "HTM-80002", + "productDescription": "10 euro korting op je gehele winkelmand.", + "productCategory": + { + "productCategoryId": 9, + "isTravelProduct": false, + "name": "Voucher", + }, + "amountInclTax": -1000, + "requiredProducts": [], + "_links": + { + "get_details": + { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/263", + "method": "GET", + }, + }, + }, + }, + "mandatoryCustomerDataItems": [], + ], } "403": description: Forbidden From 5e2b646a301d9920805247615e4bc530386ac0fb Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Wed, 11 Feb 2026 16:31:08 +0100 Subject: [PATCH 2/9] OVPAY-2442 - Added query params. Updated examples. --- src/openapi/products/vouchers-se.yaml | 344 +++++++++++--------------- 1 file changed, 147 insertions(+), 197 deletions(-) diff --git a/src/openapi/products/vouchers-se.yaml b/src/openapi/products/vouchers-se.yaml index adf7db0..ad6cae9 100644 --- a/src/openapi/products/vouchers-se.yaml +++ b/src/openapi/products/vouchers-se.yaml @@ -15,6 +15,28 @@ paths: Get a list of all voucher definitions that the calling touch point is allowed to issue. Essentially, this means that only products that have active sellingPeriods for touch points within the same retailer as the calling touch point are returned. + parameters: + - name: productId + in: query + required: false + description: Filter the voucher definitions on a specific product id. + schema: + type: integer + example: 263 + - name: requiredProductId + in: query + required: false + description: Filter the voucher definitions on a specific required product id. This means that only voucher definitions that have the specified product id in their requiredProducts list are returned. + schema: + type: integer + example: 126 + - name: showOnlyActive + in: query + required: false + description: Filter the voucher definitions on active selling periods. If true, only voucher definitions with at least one active selling period are returned. If false, all voucher definitions are returned regardless of their selling periods. + schema: + type: boolean + example: true responses: "200": description: OK @@ -27,224 +49,136 @@ paths: summary: No products / Empty list description: No products value: { "Entries": [] } - List containing one product with many null attributes: - summary: List containing one product with many null attributes - description: |- - Most product attributes are optional on a database level and can thus be null; this example shows that all attributes as defined in the schema are always represented in the response, even if null. \ - **Empty lists/arrays show up as "[]", not as null!** + List containing one voucher definition (called by touchpointId 1001): + summary: List containing one voucher definition (called by touchpointId 10010011) + description: TODO value: { "Entries": [ { - "productId": 99, - "productName": null, - "productDescription": null, - "productCategory": null, - "tokenTypes": [], - "sellableTouchpointIds": [], - "amountInclTax": null, - "imageReference": null, - "productPageUrl": null, - "_links": + "productId": 1002, + "productName": "Korting Ooievaarspas", + "productDescription": "Kortingsvoucher voor houders van een Ooievaarspas", + "validityPeriod": { - "get_details": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/99", - "method": "GET", - }, + "validityPeriodId": 144, + "fromInclusive": "2023-12-31T23:00:00.000+00:00", + "toInclusive": "2028-11-25T04:00:00.000+00:00", }, - }, - ], - } - List containing one product with 4 currently active SellingPeriods (called by touchpointId 1): - summary: List containing one product with 4 currently active SellingPeriods (called by touchpointId 1) - description: Only two sellingPeriods for touch point 1 and/or 2 (part of same retailer) are returned - the price for touchpointId 1 is returned - value: - { - "Entries": - [ - { - "productId": 2, - "productName": "HTM dagkaart", - "productDescription": "Reis een dag met het openbaar vervoer bij HTM", "productCategory": { - "productCategoryId": 5, + "productCategoryId": 9, "isTravelProduct": false, - "name": "Barcode", + "name": "Voucher", }, - "tokenTypes": [], - "sellableTouchpointIds": [1, 2], - "amountInclTax": 300, + "requiredProducts": [2], + "mandatoryCustomerDataItems": + [ + { + "mandatoryCustomerDataItemId": 8, + "customerDataItem": "padBirthDate", + }, + { + "mandatoryCustomerDataItemId": 4, + "customerDataItem": "emailAddress", + }, + ], "imageReference": "https://www.htm.nl/media/leif2leu/htm-logo-mobile.svg", "productPageUrl": "https://www.htm.nl/nog-onbekende-product-pagina", - "_links": - { - "get_details": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/2", - "method": "GET", - }, - }, + "sellingPeriods": + [ + { + "sellingPeriodId": 78, + "fromInclusive": "2024-09-30T23:00:00.000+00:00", + "toInclusive": "2028-11-17T23:00:00.000+00:00", + "salesTouchpoint": + { + "salesTouchpointId": 1001, + "name": "Gemeente Den Haag", + "isActive": true, + "retailer": + { + "retailerId": 1001, + "name": "Gemeente Den Haag", + "street": "Koningin Julianaplein", + "number": "10", + "numberAddition": null, + "postalCode": "2595 AA", + "city": "Den Haag", + "country": "Nederland", + "emailAddress": "info@denhaag.nl", + "phoneNumber": "070 374 9002", + "taxId": "572309345923", + "imageReference": "https://www.htm.nl/media/leif2leu/htm-logo-mobile.svg", + }, + }, + "forbiddenPaymentMethods": [], + "sellingPrices": + [ + { + "sellingPriceId": 78, + "amountExclTax": null, + "amountInclTax": -100, + "fromInclusive": "2024-09-30T23:00:00.000+00:00", + "toInclusive": "2028-11-17T23:00:00.000+00:00", + "internalPrice": 0.0000, + "taxCode": "V09", + "taxPercentage": 9.0000, + }, + ], + }, + ], }, ], } - List containing one product with 4 currently active SellingPeriods (called by touchpointId 3): - summary: List containing one product with 4 currently active SellingPeriods (called by touchpointId 3) - description: Only two sellingPeriods for touchpoint 3 and/or 4 (part of same retailer) are returned - the price for touchpointId 3 is returned + "403": + description: Forbidden + content: + application/problem+json: + schema: + $ref: "#/components/schemas/rfc9457" + examples: + Access denied due to insufficient permissions: + summary: Access denied due to insufficient permissions value: { - "Entries": - [ - { - "productId": 2, - "productName": "HTM dagkaart", - "productDescription": "Reis een dag met het openbaar vervoer bij HTM", - "productCategory": - { - "productCategoryId": 5, - "isTravelProduct": false, - "name": "Barcode", - }, - "tokenTypes": [], - "sellableTouchpointIds": [3, 4], - "amountInclTax": 300, - "imageReference": "https://www.htm.nl/media/leif2leu/htm-logo-mobile.svg", - "productPageUrl": "https://www.htm.nl/nog-onbekende-product-pagina", - "_links": - { - "get_details": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/2", - "method": "GET", - }, - }, - }, - ], + "type": "https://example.com/probs/forbidden", + "title": "Access denied", + "detail": "You do not have permission to access this resource.", + "instance": "/voucherdefinitions", } - List containing one product which can only be sold by touchpointId 3 (called by touchpointId 4): - summary: List containing one product which can only be sold by touchpointId 3 (called by touchpointId 4) - description: Product is still returned (because touchpointId 3 is part of same retailer) but no price, as touchpointId 4 is not allowed to sell this product. + "404": + description: Not found + content: + application/problem+json: + schema: + $ref: "#/components/schemas/rfc9457" + examples: + Voucher not found: + summary: Voucher not found value: { - "Entries": - [ - { - "productId": 49, - "productName": "HTM Regio Vrij", - "productDescription": "Voor een vast bedrag onbeperkt reizen met EBS, HTM en RET in het gekozen gebied in de regio Rotterdam Den Haag.", - "productCategory": - { - "productCategoryId": 2, - "isTravelProduct": true, - "name": "Afgekocht reisrecht", - }, - "tokenTypes": [], - "sellableTouchpointIds": [3], - "amountInclTax": null, - "imageReference": "https://www.htm.nl/media/leif2leu/htm-logo-mobile.svg", - "productPageUrl": "https://www.htm.nl/nog-onbekende-product-pagina", - "_links": - { - "get_details": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/49", - "method": "GET", - }, - }, - }, - ], + "type": "https://example.com/probs/not-found", + "title": "Voucher not found", + "detail": "The voucher definition does not exist.", + "instance": "/voucherdefinitions", } - List containing one product which can be sold by touchpointId 3 and 4 (called by touchpointId 4): - summary: List containing one product which can be sold by touchpointId 3 and 4 (called by touchpointId 4) - description: Product is returned + "500": + description: Internal server error + content: + application/problem+json: + schema: + $ref: "#/components/schemas/rfc9457" + examples: + Unexpected server error: + summary: Unexpected server error value: { - "Entries": - [ - { - "productId": 126, - "productName": "HTM-30001", - "productDescription": "Reis met 20% korting op je betaalpas bij HTM.", - "productCategory": - { - "productCategoryId": 1, - "isTravelProduct": true, - "name": "Kortingsabonnement", - }, - "tokenTypes": [{ "tokenTypeId": 1, "name": "EMV" }], - "sellableTouchpointIds": [3, 4], - "amountInclTax": 300, - "imageReference": "https://www.htm.nl/media/leif2leu/htm-logo-mobile.svg", - "productPageUrl": "https://www.htm.nl/nog-onbekende-product-pagina", - "_links": - { - "get_details": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/126", - "method": "GET", - }, - }, - }, - ], - } - List containing multiple products (called by touchpointId 3): - summary: List containing multiple products (called by touchpointId 3) - description: Only products that have active SellingPeriods for touchpoint 3 and/or 4 (part of same retailer) are returned - value: - { - "Entries": - [ - { - "productId": 2, - "productName": "HTM dagkaart", - "productDescription": "Reis een dag met het openbaar vervoer bij HTM", - "productCategory": - { - "productCategoryId": 5, - "isTravelProduct": false, - "name": "Barcode", - }, - "tokenTypes": [], - "sellableTouchpointIds": [3, 4], - "amountInclTax": 300, - "imageReference": "https://www.htm.nl/media/leif2leu/htm-logo-mobile.svg", - "productPageUrl": "https://www.htm.nl/nog-onbekende-product-pagina", - "_links": - { - "get_details": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/2", - "method": "GET", - }, - }, - }, - { - "productId": 4, - "productName": "HTM 40% korting", - "productDescription": "Reis een maand lang met 40% korting!", - "productCategory": - { - "productCategoryId": 1, - "isTravelProduct": true, - "name": "Kortingsabonnement", - }, - "tokenTypes": [{ "tokenTypeId": 1, "name": "EMV" }], - "sellableTouchpointIds": [3, 4], - "amountInclTax": 800, - "imageReference": "https://www.htm.nl/media/leif2leu/htm-logo-mobile.svg", - "productPageUrl": "https://www.htm.nl/nog-onbekende-product-pagina", - "_links": - { - "get_details": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/4", - "method": "GET", - }, - }, - }, - ], + "type": "https://example.com/probs/internal-server-error", + "title": "Internal Server Error", + "detail": "An unexpected error occurred while processing your request.", + "instance": "/voucherdefinitions", } /issuedvouchers: get: @@ -275,6 +209,22 @@ paths: schema: type: integer example: 263 + - name: highestVoucherStatusId + in: query + required: false + explode: false + description: |- + The highest voucher status id to filter the issued vouchers on. + - 1 = new + - 2 = issued + - 3 = redeemed + - 4 = revoked + - 5 = expired + schema: + type: array + items: + type: integer + example: [1, 2] tags: - Vouchers responses: @@ -402,7 +352,7 @@ paths: "type": "https://example.com/probs/forbidden", "title": "Access denied", "detail": "You do not have permission to access this resource.", - "instance": "/issuedvouchers/VOUCHER123", + "instance": "/issuedvouchers", } "404": description: Not found @@ -418,7 +368,7 @@ paths: "type": "https://example.com/probs/not-found", "title": "Voucher not found", "detail": "The voucher with code VOUCHER123 does not exist.", - "instance": "/issuedvouchers/VOUCHER123", + "instance": "/issuedvouchers", } "500": description: Internal server error @@ -434,7 +384,7 @@ paths: "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "detail": "An unexpected error occurred while processing your request.", - "instance": "/issuedvouchers/VOUCHER123", + "instance": "/issuedvouchers", } components: securitySchemes: From a71aa2e4df604e504b7b2db31562b5daf56cf3fb Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Fri, 13 Feb 2026 12:42:30 +0100 Subject: [PATCH 3/9] OVPAY-2442 - Nested product entity for GET /voucherdefinitions. --- src/openapi/products/vouchers-se.yaml | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/src/openapi/products/vouchers-se.yaml b/src/openapi/products/vouchers-se.yaml index ad6cae9..238c3d5 100644 --- a/src/openapi/products/vouchers-se.yaml +++ b/src/openapi/products/vouchers-se.yaml @@ -48,13 +48,13 @@ paths: No products / Empty list: summary: No products / Empty list description: No products - value: { "Entries": [] } + value: { "voucherDefinitions": [] } List containing one voucher definition (called by touchpointId 1001): summary: List containing one voucher definition (called by touchpointId 10010011) description: TODO value: { - "Entries": + "voucherDefinitions": [ { "productId": 1002, @@ -72,7 +72,13 @@ paths: "isTravelProduct": false, "name": "Voucher", }, - "requiredProducts": [2], + "requiredProducts": [ + { + "productId": 126, + "productName": "HTM-30001", + "productDescription": "Reis met 20% korting op je betaalpas bij HTM.", + }, + ], "mandatoryCustomerDataItems": [ { From 62f001c902eb5c9b9682ce01b08090db0dcd4256 Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Fri, 13 Feb 2026 14:17:17 +0100 Subject: [PATCH 4/9] OVPAY-2442 - Added POST /issuedvouchers. --- src/openapi/products/vouchers-se.yaml | 121 ++++++++++++++++++++++++-- 1 file changed, 114 insertions(+), 7 deletions(-) diff --git a/src/openapi/products/vouchers-se.yaml b/src/openapi/products/vouchers-se.yaml index 238c3d5..5167462 100644 --- a/src/openapi/products/vouchers-se.yaml +++ b/src/openapi/products/vouchers-se.yaml @@ -72,13 +72,14 @@ paths: "isTravelProduct": false, "name": "Voucher", }, - "requiredProducts": [ - { - "productId": 126, - "productName": "HTM-30001", - "productDescription": "Reis met 20% korting op je betaalpas bij HTM.", - }, - ], + "requiredProducts": + [ + { + "productId": 126, + "productName": "HTM-30001", + "productDescription": "Reis met 20% korting op je betaalpas bij HTM.", + }, + ], "mandatoryCustomerDataItems": [ { @@ -392,6 +393,112 @@ paths: "detail": "An unexpected error occurred while processing your request.", "instance": "/issuedvouchers", } + post: + summary: Issue a voucher for a specific product to a customer + description: | + Issue a voucher for a specific product to a customer. The voucher will be issued for the touch point that is associated with the access token used in the request. + The product for which the voucher should be issued must have active selling periods for touch points within the same retailer as the calling touch point. + tags: + - Vouchers + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/unavailable" + examples: + Issue a single voucher: + summary: Issue a single voucher + value: + { + "issuedVouchers": + [ + { + "voucherCode": "VOUCHER123", + "fromInclusive": "2024-10-04T00:00:00.000", + "untilInclusive": "2024-11-04T00:00:00.000", + "productId": 263, + "voucherClaims": + [ + { + "mandatoryCustomerDataItemId": 8, + "value": "1970-01-01", + }, + { + "mandatoryCustomerDataItemId": 4, + "value": "stasjo@html.nl", + }, + ], + }, + ], + } + Issue multiple vouchers: + summary: Issue multiple vouchers + value: + { + "issuedVouchers": + [ + { + "voucherCode": "VOUCHER123", + "fromInclusive": "2024-10-04T00:00:00.000", + "untilInclusive": "2024-11-04T00:00:00.000", + "productId": 263, + "voucherClaims": + [ + { + "mandatoryCustomerDataItemId": 8, + "value": "1970-01-01", + }, + { + "mandatoryCustomerDataItemId": 4, + "value": "stasjo@html.nl", + }, + ], + }, + { + "voucherCode": "VOUCHER456", + "fromInclusive": "2024-10-04T00:00:00.000", + "untilInclusive": "2024-11-04T00:00:00.000", + "productId": 263, + "voucherClaims": + [ + { + "mandatoryCustomerDataItemId": 8, + "value": "1970-01-01", + }, + { + "mandatoryCustomerDataItemId": 4, + "value": "joey@htm.nl", + }, + ], + }, + ], + } + responses: + "201": + description: Created + content: + application/json: + schema: + $ref: "#/components/schemas/unavailable" + examples: + Successfully issued a single voucher: + summary: Successfully issued a single voucher + value: + { + "issuedVoucherIds": + ["d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90"], + } + Successfully issued multiple vouchers: + summary: Successfully issued multiple vouchers + value: + { + "issuedVoucherIds": + [ + "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", + "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d", + ], + } components: securitySchemes: bearerToken: From 42c49693f1da8356eca40562859ac2a1aee6fa55 Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Fri, 13 Feb 2026 14:30:32 +0100 Subject: [PATCH 5/9] OVPAY-2442 - Added PATCH /issuedvouchers. --- src/openapi/products/vouchers-se.yaml | 65 +++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/src/openapi/products/vouchers-se.yaml b/src/openapi/products/vouchers-se.yaml index 5167462..895eb20 100644 --- a/src/openapi/products/vouchers-se.yaml +++ b/src/openapi/products/vouchers-se.yaml @@ -499,6 +499,71 @@ paths: "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d", ], } + patch: + summary: Update the status of one ore more issued vouchers + description: Update the status of one ore more issued vouchers. This can be used to mark a voucher as redeemed, revoked or expired. + tags: + - Vouchers + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/unavailable" + examples: + Mark a voucher as expired: + summary: Mark a single voucher as expired + value: + { + "issuedVouchers": + [ + { + "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", + "voucherStatusId": 5, + }, + ], + } + Mark multiple vouchers as revoked: + summary: Mark multiple vouchers as revoked + value: + { + "issuedVouchers": + [ + { + "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", + "voucherStatusId": 4, + }, + { + "issuedVoucherId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d", + "voucherStatusId": 4, + }, + ], + } + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/unavailable" + examples: + Successfully updated the status of a single voucher: + summary: Successfully updated the status of a single voucher + value: + { + "issuedVoucherIds": + ["d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90"], + } + Successfully updated the status of multiple vouchers: + summary: Successfully updated the status of multiple vouchers + value: + { + "issuedVoucherIds": + [ + "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", + "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d", + ], + } components: securitySchemes: bearerToken: From 594475331fba7de48b26369547a603f44d2d86f6 Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Fri, 13 Feb 2026 14:47:12 +0100 Subject: [PATCH 6/9] OVPAY-2442 - Added touchpointId query param. --- src/openapi/products/vouchers-se.yaml | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/src/openapi/products/vouchers-se.yaml b/src/openapi/products/vouchers-se.yaml index 895eb20..a01c3f9 100644 --- a/src/openapi/products/vouchers-se.yaml +++ b/src/openapi/products/vouchers-se.yaml @@ -16,6 +16,15 @@ paths: Essentially, this means that only products that have active sellingPeriods for touch points within the same retailer as the calling touch point are returned. parameters: + - name: touchpointId + in: query + required: false + description: | + Filter the voucher definitions on a specific touch point id. This means that only voucher definitions with active selling periods for the specified touch point are returned. + This query parameter is only intended for administrative purposes, since the touch point associated with the access token used in the request is used to determine which voucher definitions are returned. This query parameter can be used to retrieve voucher definitions for other touch points within the same retailer, for example to retrieve voucher definitions for a specific sales touch point that is different from the calling touch point. + schema: + type: integer + example: 1001 - name: productId in: query required: false @@ -194,6 +203,15 @@ paths: Retrieve all issued vouchers for a specific touch point. This means that only products that have active sellingPeriods for touch points within the same retailer as the calling touch point are returned. parameters: + - name: touchpointId + in: query + required: false + description: | + Filter the issued vouchers on a specific touch point id. This means that only issued vouchers for products with active selling periods for the specified touch point are returned. + This query parameter is only intended for administrative purposes, since the touch point associated with the access token used in the request is used to determine which issued vouchers are returned. This query parameter can be used to retrieve issued vouchers for other touch points within the same retailer, for example to retrieve issued vouchers for a specific sales touch point that is different from the calling touch point. + schema: + type: integer + example: 1001 - name: issuedVoucherId in: query required: false @@ -272,7 +290,7 @@ paths: { "productId": 126, "productName": "HTM-30001", - "productDescription": "Reis met 20% korting op je betaalpas bij HTM.", + "productDescription": "Regiovrij maand.", "_links": { "get_details": From 541b0662f1aecdf5954f8db63092039448c3115e Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Fri, 13 Feb 2026 14:49:44 +0100 Subject: [PATCH 7/9] OVPAY-2442 - Improved descriptions. --- src/openapi/products/vouchers-se.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/openapi/products/vouchers-se.yaml b/src/openapi/products/vouchers-se.yaml index a01c3f9..c5fccfd 100644 --- a/src/openapi/products/vouchers-se.yaml +++ b/src/openapi/products/vouchers-se.yaml @@ -412,10 +412,10 @@ paths: "instance": "/issuedvouchers", } post: - summary: Issue a voucher for a specific product to a customer + summary: Issue one or more vouchers for a specific product description: | - Issue a voucher for a specific product to a customer. The voucher will be issued for the touch point that is associated with the access token used in the request. - The product for which the voucher should be issued must have active selling periods for touch points within the same retailer as the calling touch point. + Issue one ore more vouchers for a specific product. The vouchers will be issued for the touch point that is associated with the access token used in the request. + The product for which the vouchers should be issued must have active selling periods for touch points within the same retailer as the calling touch point. tags: - Vouchers requestBody: From bf0ebee4358b55b9c7ac2ac4b91e68820ca34494 Mon Sep 17 00:00:00 2001 From: Mirjam Herald Date: Mon, 16 Feb 2026 13:38:45 +0100 Subject: [PATCH 8/9] added claim value to supplier voucher GET and added seperate swagger for voucher check sales TP --- src/openapi/products/SE-vouchers-TP.yaml | 234 ++++++++++++++++++ ...hers-se.yaml => SE-vouchers-supplier.yaml} | 26 +- 2 files changed, 252 insertions(+), 8 deletions(-) create mode 100644 src/openapi/products/SE-vouchers-TP.yaml rename src/openapi/products/{vouchers-se.yaml => SE-vouchers-supplier.yaml} (96%) diff --git a/src/openapi/products/SE-vouchers-TP.yaml b/src/openapi/products/SE-vouchers-TP.yaml new file mode 100644 index 0000000..deb8954 --- /dev/null +++ b/src/openapi/products/SE-vouchers-TP.yaml @@ -0,0 +1,234 @@ +openapi: 3.0.1 +info: + title: Service Engine APIs for HTM voucher for sales Touchpint + description: Service Engine APIs for HTM vouchers. These are NOT the CRUD APIs to the data hub. These ARE the api's for sales touchpoints. + version: "1.0" +servers: + - url: https://services.acc.api.htm.nl/abt/abtvouchersTouchpoint/1.0 +paths: + /issuedvouchers: + get: + summary: Get a list of issued vouchers that were issued for a specific touch point + description: + Retrieve all issued vouchers for a specific touch point. This means that only products that have active sellingPeriods for touch points within the same + retailer as the calling touch point are returned. + parameters: + - name: touchpointId + in: query + required: false + description: | + This endpoint is meant for salesTouchpoints to check the existance and validity of the voucher a customer has supplied + schema: + type: integer + example: 1001 + - name: issuedVoucherId + in: query + required: false + description: The unique identifier of the issued voucher instance to retrieve. + schema: + type: string + format: uuid + example: d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90 + - name: voucherCode + in: query + required: false + description: The unique code of the issued voucher to retrieve. + schema: + type: string + example: VOUCHER123 + tags: + - Vouchers + responses: + "200": + description: Successful retrieval of voucher instance + content: + application/json: + schema: + $ref: "#/components/schemas/unavailable" + examples: + Voucher for a product with required attributes: + summary: Voucher for a single product with required attributes + value: + { + "issuedVouchers": + [ + { + "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", + "voucherCode": "VOUCHER123", + "fromInclusive": "2024-10-04T00:00:00.000", + "untilInclusive": "2024-11-04T00:00:00.000", + "voucherStatus": + { "voucherStatusId": 1, "name": "New" }, + "product": + { + "productId": 263, + "productName": "HTM-80001", + "productDescription": "10 euro korting op Regiovrij maand.", + "productCategory": + { + "productCategoryId": 9, + "isTravelProduct": false, + "name": "Voucher", + }, + "amountInclTax": -1000, + "requiredProducts": + [ + { + "productId": 126, + "productName": "HTM-30001", + "productDescription": "Regiovrij maand.", + "_links": + { + "get_details": + { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/126", + "method": "GET", + }, + }, + }, + ], + "_links": + { + "get_details": + { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/263", + "method": "GET", + }, + }, + }, + "mandatoryCustomerDataItems": + [ + { + "mandatoryCustomerDataItemId": 8, + "customerDataItem": "padBirthDate" + }, + { + "mandatoryCustomerDataItemId": 4, + "customerDataItem": "emailAddress" + }, + ], + }, + ], + } + Voucher for a whole order: + summary: Voucher for a whole order + value: + { + "issuedVouchers": + [ + { + "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", + "voucherCode": "VOUCHER123", + "fromInclusive": "2024-10-04T00:00:00.000", + "untilInclusive": "2024-11-04T00:00:00.000", + "voucherStatus": + { "voucherStatusId": 1, "name": "New" }, + "product": + { + "productId": 263, + "productName": "HTM-80002", + "productDescription": "10 euro korting op je gehele winkelmand.", + "productCategory": + { + "productCategoryId": 9, + "isTravelProduct": false, + "name": "Voucher", + }, + "amountInclTax": -1000, + "requiredProducts": [], + "_links": + { + "get_details": + { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/263", + "method": "GET", + }, + }, + }, + }, + "mandatoryCustomerDataItems": [], + ], + } + "403": + description: Forbidden + content: + application/problem+json: + schema: + $ref: "#/components/schemas/rfc9457" + examples: + Access denied due to insufficient permissions: + summary: Access denied due to insufficient permissions + value: + { + "type": "https://example.com/probs/forbidden", + "title": "Access denied", + "detail": "You do not have permission to access this resource.", + "instance": "/issuedvouchers", + } + "404": + description: Not found + content: + application/problem+json: + schema: + $ref: "#/components/schemas/rfc9457" + examples: + Voucher not found: + summary: Voucher not found + value: + { + "type": "https://example.com/probs/not-found", + "title": "Voucher not found", + "detail": "The voucher with code VOUCHER123 does not exist.", + "instance": "/issuedvouchers", + } + "500": + description: Internal server error + content: + application/problem+json: + schema: + $ref: "#/components/schemas/rfc9457" + examples: + Unexpected server error: + summary: Unexpected server error + value: + { + "type": "https://example.com/probs/internal-server-error", + "title": "Internal Server Error", + "detail": "An unexpected error occurred while processing your request.", + "instance": "/issuedvouchers", + } +components: + securitySchemes: + bearerToken: + type: http + scheme: bearer + bearerFormat: JWT + schemas: + unavailable: + type: object + rfc9457: + type: object + properties: + type: + type: string + format: url + example: https://example.com/probs/out-of-credit + title: + type: string + example: You do not have enough credit. + detail: + type: string + example: Your current balance is 30, but that costs 50. + instance: + type: string + example: /account/12345/msgs/abc + balance: + type: string + example: 30 + accounts: + type: array + items: + type: string + example: + - /account/12345 + - /account/67890 diff --git a/src/openapi/products/vouchers-se.yaml b/src/openapi/products/SE-vouchers-supplier.yaml similarity index 96% rename from src/openapi/products/vouchers-se.yaml rename to src/openapi/products/SE-vouchers-supplier.yaml index c5fccfd..9a03c91 100644 --- a/src/openapi/products/vouchers-se.yaml +++ b/src/openapi/products/SE-vouchers-supplier.yaml @@ -1,7 +1,7 @@ openapi: 3.0.1 info: - title: Service Engine APIs for HTM vouchers - description: Service Engine APIs for HTM vouchers. These are NOT the CRUD APIs to the data hub. + title: Service Engine APIs for HTM voucher suppliers + description: Service Engine APIs for HTM vouchers suppliers, this means all instances responsible for supplying vouchers. These are NOT the CRUD APIs to the data hub. These are ALSO NOT the api's for sales touchpoints. version: "1.0" servers: - url: https://services.acc.api.htm.nl/abt/abtvouchers/1.0 @@ -310,15 +310,25 @@ paths: }, }, }, - "mandatoryCustomerDataItems": + "claims": [ { - "mandatoryCustomerDataItemId": 8, - "customerDataItem": "padBirthDate", + "mandatoryCustomerDataItem": + { + "mandatoryCustomerDataItemId": 8, + "customerDataItem": "padBirthDate" + }, + "value": "1980-06-31" + }, { - "mandatoryCustomerDataItemId": 4, - "customerDataItem": "emailAddress", + "mandatoryCustomerDataItem": + { + "mandatoryCustomerDataItemId": 4, + "customerDataItem": "emailAddress" + }, + "value": "harry@griffindor.co.uk" + }, ], }, @@ -360,7 +370,7 @@ paths: }, }, }, - "mandatoryCustomerDataItems": [], + "claims": [], ], } "403": From 5d307d98085a1d0a266a63d778843be10e932e9b Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Mon, 23 Feb 2026 17:03:24 +0100 Subject: [PATCH 9/9] OVPAY-2442 - Changed all bulk endpoints to single inserts and patches (yarr). --- .../products/SE-vouchers-supplier.yaml | 216 +++++++++--------- 1 file changed, 102 insertions(+), 114 deletions(-) diff --git a/src/openapi/products/SE-vouchers-supplier.yaml b/src/openapi/products/SE-vouchers-supplier.yaml index 9a03c91..2ed5e39 100644 --- a/src/openapi/products/SE-vouchers-supplier.yaml +++ b/src/openapi/products/SE-vouchers-supplier.yaml @@ -316,19 +316,17 @@ paths: "mandatoryCustomerDataItem": { "mandatoryCustomerDataItemId": 8, - "customerDataItem": "padBirthDate" + "customerDataItem": "padBirthDate", }, - "value": "1980-06-31" - + "value": "1980-06-31", }, { "mandatoryCustomerDataItem": { "mandatoryCustomerDataItemId": 4, - "customerDataItem": "emailAddress" + "customerDataItem": "emailAddress", }, - "value": "harry@griffindor.co.uk" - + "value": "harry@griffindor.co.uk", }, ], }, @@ -422,10 +420,10 @@ paths: "instance": "/issuedvouchers", } post: - summary: Issue one or more vouchers for a specific product + summary: Issue a voucher for a specific product description: | - Issue one ore more vouchers for a specific product. The vouchers will be issued for the touch point that is associated with the access token used in the request. - The product for which the vouchers should be issued must have active selling periods for touch points within the same retailer as the calling touch point. + Issue a voucher for a specific product. The voucher will be issued for the touch point that is associated with the access token used in the request. + The product for which the voucher should be issued must have active selling periods for touch points within the same retailer as the calling touch point. tags: - Vouchers requestBody: @@ -435,70 +433,42 @@ paths: schema: $ref: "#/components/schemas/unavailable" examples: - Issue a single voucher: - summary: Issue a single voucher + Issue a voucher with prefilled voucher code: + summary: Issue a voucher with prefilled voucher code value: { - "issuedVouchers": + "voucherCode": "VOUCHER123", + "fromInclusive": "2024-10-04T00:00:00.000", + "untilInclusive": "2024-11-04T00:00:00.000", + "productId": 263, + "voucherClaims": [ { - "voucherCode": "VOUCHER123", - "fromInclusive": "2024-10-04T00:00:00.000", - "untilInclusive": "2024-11-04T00:00:00.000", - "productId": 263, - "voucherClaims": - [ - { - "mandatoryCustomerDataItemId": 8, - "value": "1970-01-01", - }, - { - "mandatoryCustomerDataItemId": 4, - "value": "stasjo@html.nl", - }, - ], + "mandatoryCustomerDataItemId": 8, + "value": "1970-01-01", + }, + { + "mandatoryCustomerDataItemId": 4, + "value": "stasjo@html.nl", }, ], } - Issue multiple vouchers: - summary: Issue multiple vouchers + Issue a voucher without prefilled voucher code: + summary: Issue a voucher without prefilled voucher code value: { - "issuedVouchers": + "fromInclusive": "2024-10-04T00:00:00.000", + "untilInclusive": "2024-11-04T00:00:00.000", + "productId": 263, + "voucherClaims": [ { - "voucherCode": "VOUCHER123", - "fromInclusive": "2024-10-04T00:00:00.000", - "untilInclusive": "2024-11-04T00:00:00.000", - "productId": 263, - "voucherClaims": - [ - { - "mandatoryCustomerDataItemId": 8, - "value": "1970-01-01", - }, - { - "mandatoryCustomerDataItemId": 4, - "value": "stasjo@html.nl", - }, - ], + "mandatoryCustomerDataItemId": 8, + "value": "1970-01-01", }, { - "voucherCode": "VOUCHER456", - "fromInclusive": "2024-10-04T00:00:00.000", - "untilInclusive": "2024-11-04T00:00:00.000", - "productId": 263, - "voucherClaims": - [ - { - "mandatoryCustomerDataItemId": 8, - "value": "1970-01-01", - }, - { - "mandatoryCustomerDataItemId": 4, - "value": "joey@htm.nl", - }, - ], + "mandatoryCustomerDataItemId": 4, + "value": "stasjo@html.nl", }, ], } @@ -510,26 +480,51 @@ paths: schema: $ref: "#/components/schemas/unavailable" examples: - Successfully issued a single voucher: - summary: Successfully issued a single voucher + Successfully issued a voucher: + summary: Successfully issued a voucher value: { - "issuedVoucherIds": - ["d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90"], - } - Successfully issued multiple vouchers: - summary: Successfully issued multiple vouchers - value: - { - "issuedVoucherIds": - [ - "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", - "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d", - ], + "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", + "voucherCode": "HKV-A7J-128-PYT", + "fromInclusive": "2024-10-04T00:00:00.000", + "untilInclusive": "2024-11-04T00:00:00.000", + "voucherStatus": { "voucherStatusId": 1, "name": "New" }, + "product": + { + "productId": 263, + "productName": "HTM-80002", + "productDescription": "10 euro korting op je gehele winkelmand.", + "productCategory": + { + "productCategoryId": 9, + "isTravelProduct": false, + "name": "Voucher", + }, + "amountInclTax": -1000, + "requiredProducts": [], + "_links": + { + "get_details": + { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/263", + "method": "GET", + }, + }, + }, } + /issuedvouchers/{issuedVoucherId}: + parameters: + - name: issuedVoucherId + in: path + required: true + description: The unique identifier of the issued voucher instance to update the status for. + schema: + type: string + format: uuid + example: d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90 patch: - summary: Update the status of one ore more issued vouchers - description: Update the status of one ore more issued vouchers. This can be used to mark a voucher as redeemed, revoked or expired. + summary: Update the status of an issued voucher + description: Update the status of an issued voucher. This can be used to mark a voucher as redeemed, revoked or expired. tags: - Vouchers requestBody: @@ -540,32 +535,10 @@ paths: $ref: "#/components/schemas/unavailable" examples: Mark a voucher as expired: - summary: Mark a single voucher as expired + summary: Mark a voucher as expired value: { - "issuedVouchers": - [ - { - "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", - "voucherStatusId": 5, - }, - ], - } - Mark multiple vouchers as revoked: - summary: Mark multiple vouchers as revoked - value: - { - "issuedVouchers": - [ - { - "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", - "voucherStatusId": 4, - }, - { - "issuedVoucherId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d", - "voucherStatusId": 4, - }, - ], + "voucherStatusId": 5, } responses: "200": @@ -575,22 +548,37 @@ paths: schema: $ref: "#/components/schemas/unavailable" examples: - Successfully updated the status of a single voucher: - summary: Successfully updated the status of a single voucher + Successfully updated the status of a voucher: + summary: Successfully updated the status of a voucher value: { - "issuedVoucherIds": - ["d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90"], - } - Successfully updated the status of multiple vouchers: - summary: Successfully updated the status of multiple vouchers - value: - { - "issuedVoucherIds": - [ - "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", - "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d", - ], + "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", + "voucherCode": "HKV-A7J-128-PYT", + "fromInclusive": "2024-10-04T00:00:00.000", + "untilInclusive": "2024-11-04T00:00:00.000", + "voucherStatus": { "voucherStatusId": 5, "name": "Expired" }, + "product": + { + "productId": 263, + "productName": "HTM-80002", + "productDescription": "10 euro korting op je gehele winkelmand.", + "productCategory": + { + "productCategoryId": 9, + "isTravelProduct": false, + "name": "Voucher", + }, + "amountInclTax": -1000, + "requiredProducts": [], + "_links": + { + "get_details": + { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/263", + "method": "GET", + }, + }, + }, } components: securitySchemes: