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