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. version: "1.0" servers: - url: https://services.acc.api.htm.nl/abt/abtvouchers/1.0 paths: /voucherdefinitions: get: 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. 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 content: application/json: schema: $ref: "#/components/schemas/unavailable" examples: No products / Empty list: summary: No products / Empty list description: No products value: { "voucherDefinitions": [] } List containing one voucher definition (called by touchpointId 1001): summary: List containing one voucher definition (called by touchpointId 10010011) description: TODO value: { "voucherDefinitions": [ { "productId": 1002, "productName": "Korting Ooievaarspas", "productDescription": "Kortingsvoucher voor houders van een Ooievaarspas", "validityPeriod": { "validityPeriodId": 144, "fromInclusive": "2023-12-31T23:00:00.000+00:00", "toInclusive": "2028-11-25T04:00:00.000+00:00", }, "productCategory": { "productCategoryId": 9, "isTravelProduct": false, "name": "Voucher", }, "requiredProducts": [ { "productId": 126, "productName": "HTM-30001", "productDescription": "Reis met 20% korting op je betaalpas bij HTM.", }, ], "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", "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, }, ], }, ], }, ], } "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": "/voucherdefinitions", } "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 definition does not exist.", "instance": "/voucherdefinitions", } "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": "/voucherdefinitions", } /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: 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 - 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: "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": "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": { "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