From a09ad1ad083de2b61cf024bca8012aaa22b1f711 Mon Sep 17 00:00:00 2001 From: Max Martens Date: Mon, 1 Jun 2026 10:40:28 +0200 Subject: [PATCH] Process PR feedback, first version of issuedVoucher JSON schema --- src/openapi/products/SE-vouchers-TP.yaml | 254 +++++++++++------- .../products/SE-vouchers-supplier.yaml | 6 +- 2 files changed, 164 insertions(+), 96 deletions(-) diff --git a/src/openapi/products/SE-vouchers-TP.yaml b/src/openapi/products/SE-vouchers-TP.yaml index 8b8c724..ef6ba2f 100644 --- a/src/openapi/products/SE-vouchers-TP.yaml +++ b/src/openapi/products/SE-vouchers-TP.yaml @@ -28,99 +28,7 @@ paths: 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: - { - "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: - { - "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": [], - } + $ref: "#/components/schemas/issuedVoucherResponse" "403": description: Forbidden content: @@ -176,6 +84,166 @@ components: scheme: bearer bearerFormat: JWT schemas: + issuedVoucherResponse: + type: object + required: + - issuedVoucherId + - voucherCode + - fromInclusive + - untilInclusive + - voucherStatus + - product + - mandatoryCustomerDataItems + properties: + issuedVoucherId: + type: string + description: The unique (technical) identifier of the issued voucher instance. + example: "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90" + voucherCode: + type: string + description: The voucher code that is shared with the customer and uniquely identifies this voucher. + example: "HTM-A7J-128-PYT" + fromInclusive: + type: string + format: date-time + description: |- + The date and time the voucher becomes valid for redemption. This has nothing to do with + the allowed start date of a requiredProduct (for this, the existing order flow logic is applied). + example: "2024-10-04T00:00:00.000" + untilInclusive: + type: string + format: date-time + description: |- + The date and time the voucher becomes invalid for redemption. This has nothing to do with + the maximum allowed start date of a requiredProduct (for this, the existing order flow logic is applied). + example: "2024-11-04T00:00:00.000" + voucherStatus: + type: object + required: + - voucherStatusId + - name + description: |- + The current status of the voucher. Can be any of the following: + - 1 = new + - 2 = issued + - 3 = redeemed + - 4 = revoked + - 5 = expired + - 6 = pendingRedemption + properties: + voucherStatusId: + type: integer + example: 2 + name: + type: string + example: "issued" + product: + type: object + description: The "product" referencing the voucher definition that this voucher instance is based on" + required: + - productId + - productName + - productDescription + - amountInclTax + properties: + productId: + type: integer + example: 263 + productName: + type: string + example: Voucher Ooievaarspas-product AOW + productDescription: + type: string + example: |- + 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: + type: integer + description: |- + When combined with a requiredProduct, the (positive or zero) amountInclTax dictates + the total amount that needs to be paid for said product. When the requiredProduct has + a sellingPrice > 0, the difference between sellingPrice and voucher amountInclTax + represents the granted discount. + When not combined with a required product, the (negative) amountInclTax dictates + the value of the voucher, that is subtracted from the total order value as a discount + (with a minimum order total of 0). + example: 0 + requiredProducts: + type: array + description: |- + Currently, only one requiredProduct is supported and thus, this array can contain at + most one element. + items: + type: object + required: + - productId + properties: + productId: + type: integer + example: 892 + productName: + type: string + example: "Ooievaarspas voor AOW-ers in Den Haag" + productDescription: + type: string + example: "Vrij reizen bij HTM voor Haagse AOW-gerechtigden met een Ooievaarspas." + productCategory: + type: object + required: + - productCategoryId + - isTravelProduct + - name + properties: + productCategoryId: + type: integer + example: 2 + isTravelProduct: + type: boolean + example: true + name: + type: string + example: "Afgekocht reisrecht" + amountInclTax: + type: integer + description: |- + Selling price of the product in cents (including tax, if applicable) that is + currently active for the calling touchpoint. When 0, the product is free of charge. + example: 0 + imageReference: + type: string + description: Can be a URL or a base64 encoded image + example: https://www.htm.nl/nog-onbekende-productafbeelding + _links: + type: object + properties: + get_details: + type: object + description: Link to get more details for the product that this voucher instance applies to + properties: + href: + type: string + example: https://api.integratielaag.nl/abt/touchpoint/1.0/products/982 + method: + type: string + example: GET + mandatoryCustomerDataItems: + type: array + description: |- + List of mandatory customer data items that are required to redeem this voucher.\ + The values provided for these data items may be checked against allowed values as provided by the voucher issuer. + items: + type: object + required: + - mandatoryCustomerDataItemId + - customerDataItem + properties: + mandatoryCustomerDataItemId: + type: integer + example: 8 + customerDataItem: + type: string + example: padBirthdate + unavailable: type: object rfc9457: diff --git a/src/openapi/products/SE-vouchers-supplier.yaml b/src/openapi/products/SE-vouchers-supplier.yaml index c284f82..5b1aa2b 100644 --- a/src/openapi/products/SE-vouchers-supplier.yaml +++ b/src/openapi/products/SE-vouchers-supplier.yaml @@ -35,7 +35,7 @@ paths: - name: productId in: query required: false - description: Return a specific voucher definition by it's productId. + description: Return a specific voucher definition by its productId. schema: type: integer example: 321 @@ -233,7 +233,7 @@ paths: - name: productId in: query required: false - description: Return only issued vouchers that were issued for the given voucher definition (by it's productId). + description: Return only issued vouchers that were issued for the given voucher definition (by its productId). schema: type: integer example: 321 @@ -370,7 +370,7 @@ paths: examples: Issue a voucher and supply own voucher code: summary: Issue a voucher and supply own voucher code - description: This allows the voucher supplier to supply its own voucher code, which can be useful if the suplier already has its own (internal or external) source for voucher codes. The supplied voucher code must be unique - if this code is already in use, the request will fail. + description: This allows the voucher supplier to supply its own voucher code, which can be useful if the supplier already has its own (internal or external) source for voucher codes. The supplied voucher code must be unique - if this code is already in use, the request will fail. value: { "voucherCode": "HTM-A7J-128-PYT",