From e6b2146706a01f78890a8dd36227237808cf9381 Mon Sep 17 00:00:00 2001
From: "b.boterman@htm.nl" <b.boterman@htm.nl>
Date: Tue, 30 Dec 2025 14:57:43 +0100
Subject: [PATCH] OVPAY-2346 - Implemented /issuedvouchers/{code}.

---
 src/openapi/products/vouchers-se.yaml | 181 ++++++++++++++++++++++++++
 1 file changed, 181 insertions(+)
 create mode 100644 src/openapi/products/vouchers-se.yaml

diff --git a/src/openapi/products/vouchers-se.yaml b/src/openapi/products/vouchers-se.yaml
new file mode 100644
index 0000000..5628f3c
--- /dev/null
+++ b/src/openapi/products/vouchers-se.yaml
@@ -0,0 +1,181 @@
+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:
+  /issuedvouchers/{voucherCode}:
+    get:
+      summary: Get voucher details by voucher code
+      description: Retrieve voucher details using its unique voucher code.
+      parameters:
+        - name: voucherCode
+          in: path
+          required: true
+          description: The unique code of the voucher details to retrieve.
+          schema:
+            type: string
+      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:
+                    {
+                      "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" },
+                          "products":
+                            [
+                              {
+                                "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",
+                                      }
+                                  }
+                              }
+                            ],
+                          "mandatoryCustomerDataItems":
+                            [
+                              {
+                                "mandatoryCustomerDataItemId": 8,
+                                "customerDataItem": "padBirthDate",
+                              },
+                              {
+                                "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" },
+                          "products": [],
+                          "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/VOUCHER123",
+                    }
+        "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/VOUCHER123",
+                    }
+        "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/VOUCHER123",
+                    }
+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