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: