Added contractVersions in SE contracts list response, fixed some example formatting

Reviewed-on: #63

src/java/ABTProductsPUTGenerator/.idea/misc.xml

@@ -8,7 +8,7 @@
       </list>
     </option>
   </component>
-  <component name="ProjectRootManager" version="2" languageLevel="JDK_21" default="true" project-jdk-name="temurin-21" project-jdk-type="JavaSDK">
+  <component name="ProjectRootManager" version="2" languageLevel="JDK_17" default="true" project-jdk-name="17" project-jdk-type="JavaSDK">
     <output url="file://$PROJECT_DIR$/out" />
   </component>
 </project>

src/java/ABTProductsPUTGenerator/bin/README.md

@@ -1,7 +1,9 @@
 # ABTProducts PUT request body generator
 Simple tool to quickly edit HTM products via ABTProducts REST API.
 
-- Requires JRE 21
+- Requires JRE 17
+
+## Generating a PUT output (that you need to supply to PUT API yourself):
 - Run via: `java -jar ABTProductsPUTGenerator.jar`
   - Specify custom input/output path via: `java -jar ABTProductsPUTGenerator.jar <inputPath> <outputPath>`
 - Takes a ABTProducts GET response body in JSON format (product details)
@@ -10,3 +12,14 @@ Simple tool to quickly edit HTM products via ABTProducts REST API.
   - `curl -X PUT -H 'Content-Type: application/json' {baseUrl}/abt/abtproducts/1.0/38 --data @output.json`
 - Default input path: /input.json
 - Default output path: /output.json (output is overwritten if it exists)
+  
+## Bulk clearing (set to null) of a certain product attribute for all productIds in a product-tree (SE product reponse)
+- Run via: `java -jar ABTProductsPUTGenerator.jar clearAttribute <inputPath> <attributeToClear> <environment> <wso2BearerToken>`
+- Takes a SE GET product tree response body or ABTProducts GET response body in JSON format
+- Also needs the attribute to clear and the WSO2 environment and valid WSO2 bearer token for that environment
+- Performs the following operations:
+  - Finds all productId's in the given product(tree) and for each productId found:
+    - GETs productdetails via ABTProducts API
+    - Converts it to PUT request body using the functionality in the previous section
+    - Replaces <attributeToClear> with `null`
+    - Actually sends the modified PUT request body to ABTProducts PUT API

src/java/ABTProductsPUTGenerator/pom.xml

@@ -58,8 +58,8 @@
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-compiler-plugin</artifactId>
         <configuration>
-          <source>21</source>
-          <target>21</target>
+          <source>17</source>
+          <target>17</target>
         </configuration>
       </plugin>
     </plugins>

src/java/ABTProductsPUTGenerator/src/main/java/nl/htm/ovpay/abt/ABTProductsPUTGenerator.java

@@ -3,8 +3,11 @@ package nl.htm.ovpay.abt;
 import java.io.File;
 import java.io.IOException;
 import java.io.InputStream;
+import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
+import java.util.Scanner;
+import java.util.stream.Collectors;
 
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -19,6 +22,15 @@ public class ABTProductsPUTGenerator {
     private static final Logger LOGGER = LoggerFactory.getLogger(ABTProductsPUTGenerator.class);
 
     public static void main(String[] args) throws Exception {
+        LOGGER.info("Starting ABTProductsPUTGenerator with arguments {}", Arrays.stream(args).toList());
+        if (args.length > 0 && args[0].equalsIgnoreCase("clearAttribute")) {
+            clearAttribute(args);
+        } else {
+            generateOutput(args);
+        }
+    }
+
+    private static void generateOutput(String[] args) throws Exception {
         if (args.length != 2) {
             LOGGER.info("To modify input/output path, use: java -jar ABTProductsPUTGenerator.jar <inputPath> <outputPath>");
         }
@@ -40,6 +52,49 @@ public class ABTProductsPUTGenerator {
         }
     }
 
+    private static void clearAttribute(String[] args) throws Exception {
+        if (args.length != 5) {
+            LOGGER.error("Incorrect input parameters!");
+            LOGGER.error("To clear attribute, use: java -jar ABTProductsPUTGenerator.jar clearAttribute <inputPath> <attributeToClear> <environment> <wso2BearerToken>");
+            return;
+        }
+
+        var inputFile = args[1];
+        var attributeToClear = args[2];
+        var environment = args[3];
+        var wso2BearerToken = args[4];
+
+        try (InputStream is = getInputStream(inputFile)) {
+            ObjectMapper mapper = new ObjectMapper();
+            JsonNode jsonNode = mapper.readTree(is);
+            var productIds = jsonNode.findValues("productId").stream().filter(JsonNode::isValueNode).map(JsonNode::asText).toList();
+
+            LOGGER.info("Found productIds to process: {}", productIds);
+            LOGGER.warn("Are you SURE you want to set attribute \"{}\" for all these productIds on environment {} to NULL?", attributeToClear, environment);
+            LOGGER.warn("Type 'yes' to continue...");
+            var input = new Scanner(System.in).nextLine();
+            if (!input.equalsIgnoreCase("yes")) {
+                LOGGER.info("Aborting...");
+                return;
+            }
+
+            for (var productId : productIds) {
+                LOGGER.info("Getting product details for product {}...", productId);
+                var productJsonString = APIHelper.getProductDetails(environment, productId, wso2BearerToken);
+                var productJsonNode = mapper.readTree(productJsonString);
+                var putJsonNode = processJsonNode(productJsonNode);
+                LOGGER.info("Clearing attribute \"{}\" from product with productId {}...", attributeToClear, productId);
+                ((ObjectNode)putJsonNode).putRawValue(attributeToClear, null);
+
+                LOGGER.info("PUT product details for product with productId {} with cleared attribute \"{}\"...", productId, attributeToClear);
+                LOGGER.info("PUT product details with JSON body: {}", putJsonNode.toPrettyString());
+                APIHelper.putProductDetails(environment, productId, putJsonNode.toString(), wso2BearerToken);
+            }
+
+            LOGGER.info("DONE clearing attribute \"{}\" for productIds {}!", attributeToClear, productIds);
+        }
+    }
+
     private static InputStream getInputStream(String filePath) throws IOException {
         var externalResource = new File(filePath);
         if (externalResource.exists()) {

src/java/ABTProductsPUTGenerator/src/main/java/nl/htm/ovpay/abt/APIHelper.java

@@ -0,0 +1,89 @@
+package nl.htm.ovpay.abt;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.net.HttpURLConnection;
+import java.net.URL;
+import java.net.URLConnection;
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+import java.security.KeyManagementException;
+import java.security.NoSuchAlgorithmException;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.StringJoiner;
+import javax.net.ssl.HttpsURLConnection;
+import javax.net.ssl.SSLContext;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class APIHelper {
+
+    private static final Logger LOGGER = LoggerFactory.getLogger(APIHelper.class);
+    private static final String PRODUCT_DETAILS_URI = "https://services.<ENV>.api.htm.nl/abt/abtproducts/1.0/products/<PRODUCTID>";
+
+
+    public static String envToUriPart(String environment) {
+        return switch (environment) {
+            case "DEV" -> "dev";
+            case "ACC" -> "acc";
+            case "PRD" -> "";
+            default -> throw new IllegalArgumentException("Invalid environment: " + environment);
+        };
+    }
+
+    public static String getProductDetails(String environment, String productId, String wso2BearerToken) throws Exception {
+        var envUriPart = envToUriPart(environment);
+        var getProductDetailsUri = PRODUCT_DETAILS_URI.replace("<ENV>", envUriPart).replace("<PRODUCTID>", productId);
+
+        SSLContext sc = SSLContext.getInstance("SSL");
+        sc.init(null, DummyX509TrustManager.getDummyArray(), new java.security.SecureRandom());
+        HttpsURLConnection.setDefaultSSLSocketFactory(sc.getSocketFactory());
+
+        URL url = new URL(getProductDetailsUri);
+        URLConnection con = url.openConnection();
+        HttpURLConnection http = (HttpURLConnection)con;
+        http.setRequestMethod("GET");
+        http.setDoOutput(false);
+        http.setRequestProperty("Authorization", "Bearer " + wso2BearerToken);
+        http.connect();
+
+        try(InputStream is = http.getInputStream()) {
+            return new String(is.readAllBytes(), StandardCharsets.UTF_8);
+        }
+    }
+
+    public static void putProductDetails(String environment, String productId, String jsonBody, String wso2BearerToken) throws Exception {
+        var envUriPart = envToUriPart(environment);
+        var putProductDetailsUri = PRODUCT_DETAILS_URI.replace("<ENV>", envUriPart).replace("<PRODUCTID>", productId);
+
+        LOGGER.info("PUT product details to URI: {}", putProductDetailsUri);
+
+        SSLContext sc = SSLContext.getInstance("SSL");
+        sc.init(null, DummyX509TrustManager.getDummyArray(), new java.security.SecureRandom());
+        HttpsURLConnection.setDefaultSSLSocketFactory(sc.getSocketFactory());
+
+        URL url = new URL(putProductDetailsUri);
+        URLConnection con = url.openConnection();
+        HttpURLConnection http = (HttpURLConnection)con;
+        http.setRequestMethod("PUT");
+        http.setDoOutput(true);
+        http.setRequestProperty("Authorization", "Bearer " + wso2BearerToken);
+        http.setRequestProperty("Content-Type", "application/json");
+
+        byte[] out = jsonBody.getBytes(StandardCharsets.UTF_8);
+        int length = out.length;
+        http.setFixedLengthStreamingMode(length);
+        http.connect();
+
+        try(OutputStream os = http.getOutputStream()) {
+            os.write(out);
+        }
+
+        try(InputStream is = http.getInputStream()) {
+            LOGGER.info("Got response from PUT API: {}", new String(is.readAllBytes(), StandardCharsets.UTF_8));
+        }
+    }
+}

src/java/ABTProductsPUTGenerator/src/main/java/nl/htm/ovpay/abt/DummyX509TrustManager.java

@@ -0,0 +1,38 @@
+package nl.htm.ovpay.abt;
+
+import java.security.cert.X509Certificate;
+import javax.net.ssl.TrustManager;
+import javax.net.ssl.X509TrustManager;
+
+public final class DummyX509TrustManager implements X509TrustManager {
+
+    private static DummyX509TrustManager INSTANCE;
+
+    private DummyX509TrustManager() {
+        // prevent instantiation
+    }
+
+    public static DummyX509TrustManager getInstance() {
+        if (INSTANCE == null) {
+            INSTANCE = new DummyX509TrustManager();
+        }
+        return INSTANCE;
+    }
+
+    public static TrustManager[] getDummyArray() {
+        if (INSTANCE == null) {
+            INSTANCE = new DummyX509TrustManager();
+        }
+        return new TrustManager[] { INSTANCE };
+    }
+
+    public X509Certificate[] getAcceptedIssuers() {
+        return null;
+    }
+
+    public void checkClientTrusted(X509Certificate[] certs, String authType) {
+    }
+
+    public void checkServerTrusted(X509Certificate[] certs, String authType) {
+    }
+}

src/java/ABTProductsPUTGenerator/src/main/resources/input.json

@@ -1,23 +1,33 @@
 {
-  "productId": 251,
-  "fikoArticleNumber": null,
+  "productId": 663,
   "parentProductId": null,
-  "gboPackageTemplateId": "30901",
+  "layerInfo": {
+    "layerInfoId": 7,
+    "choiceKey": "isRenewable",
+    "choiceLabel": "Kies voor een doorlopend abonnement of een enkele termijn",
+    "isCustomChoice": false
+  },
+  "fikoArticleNumber": null,
+  "gboPackageTemplateId": "30001",
   "tapConnectProductCode": null,
-  "productName": "MaxTestPOST-21-okt-test-1 edited PUT",
-  "productDescription": "21-okt-test-1 edited PUT - reis met 90% korting gedurende de eerste F&F pilot!",
-  "validityPeriod": null,
-  "productTranslations": null,
+  "productName": "Test OVPAY-2306",
+  "productDescription": "Test OVPAY-2306 (sellingPeriods in kindje verwijderen en later opnieuw weer kunnen toevoegen)",
+  "validityPeriod": {
+    "validityPeriodId": 782,
+    "fromInclusive": "2025-12-31T23:00:00.000Z",
+    "toInclusive": "2026-03-30T22:00:00.000Z"
+  },
+  "productTranslations": [],
+  "allowedGboAgeProfiles": [],
   "productOwner": {
     "productOwnerId": 1,
-    "name": "Corneel Verstoep",
-    "organization": "HTM"
+    "name": "Wie dit leest",
+    "organization": "... is een aap."
   },
-  "marketSegments": null,
-  "customerSegments": null,
-  "allowedGboAgeProfiles": null,
+  "marketSegments": [],
+  "customerSegments": [],
   "productCategory": {
-    "productCategoryId": 9,
+    "productCategoryId": 1,
     "isTravelProduct": true,
     "name": "Kortingsabonnement"
   },
@@ -25,32 +35,10 @@
     "requiredCustomerLevelId": 1,
     "name": "guest"
   },
-  "requiredProducts": null,
-  "incompatibleProducts": null,
-  "mandatoryCustomerDataItems": [
-    {
-      "mandatoryCustomerDataItemId": 4,
-      "customerDataItem": "emailAddress"
-    },
-    {
-      "mandatoryCustomerDataItemId": 5,
-      "customerDataItem": "address"
-    }
-  ],
-  "requiredGboPersonalAttributes": [
-    {
-      "requiredGboPersonalAttributeId": 1,
-      "name": "NAME"
-    },
-    {
-      "requiredGboPersonalAttributeId": 2,
-      "name": "BIRTHDATE"
-    },
-    {
-      "requiredGboPersonalAttributeId": 3,
-      "name": "PHOTO"
-    }
-  ],
+  "requiredProducts": [],
+  "incompatibleProducts": [],
+  "mandatoryCustomerDataItems": [],
+  "requiredGboPersonalAttributes": [],
   "tokenTypes": [
     {
       "tokenTypeId": 1,
@@ -61,72 +49,36 @@
     "paymentMomentId": 1,
     "name": "prepaid"
   },
-  "serviceOptions": null,
-  "validityDuration": "P7D",
-  "maxStartInFutureDuration": "P6W",
-  "isRenewable": false,
+  "serviceOptions": [
+    {
+      "serviceOptionId": 4,
+      "action": "cancel_notAllowed",
+      "description": "Stopzetting is niet toegestaan (doorgaans in combinatie met refund_notAllowed)"
+    },
+    {
+      "serviceOptionId": 10,
+      "action": "refund_notAllowed",
+      "description": "Terugbetaling niet toegestaan (doorgaans in combinatie met cancel_notAllowed)"
+    }
+  ],
+  "validityDuration": "P1W",
+  "maxStartInFutureDuration": "P1W",
+  "isRenewable": null,
   "sendInvoice": false,
-  "imageReference": "https://www.htm.nl/media/leif2leu/htm-logo-mobile.svg",
-  "productPageUrl": "https://www.htm.nl/nog-onbekende-product-pagina",
-  "termsUrl": "https://www.htm.nl/nog-onbekende-productvoorwaarden-pagina",
+  "imageReference": null,
+  "productPageUrl": null,
+  "termsUrl": null,
   "isSellableAtHtm": true,
   "needsSolvencyCheckConsumer": false,
   "needsSolvencyCheckBusiness": false,
   "sellingPeriods": [
     {
-      "sellingPeriodId": 240,
-      "fromInclusive": "2024-09-06T00:00:00.000+00:00",
-      "toInclusive": "2024-12-29T23:59:59.000+00:00",
+      "sellingPeriodId": 1382,
+      "fromInclusive": "2025-12-31T23:00:00.000Z",
+      "toInclusive": "2026-03-30T22:00:00.000Z",
       "salesTouchpoint": {
-        "salesTouchpointId": 6,
-        "name": "Service-engine",
-        "isActive": true,
-        "retailer": {
-          "retailerId": 1000,
-          "name": "HTM intern beheer",
-          "street": "Koningin Julianaplein",
-          "number": 10,
-          "numberAddition": null,
-          "postalCode": "2595 AA",
-          "city": "Den Haag",
-          "country": "Nederland",
-          "emailAddress": "info@htm.nl",
-          "phoneNumber": "070 374 9002",
-          "taxId": null,
-          "imageReference": "https://www.htm.nl/typo3conf/ext/htm_template/Resources/Public/img/logo.svg"
-        }
-      },
-      "forbiddenPaymentMethods": null,
-      "sellingPrices": [
-        {
-          "sellingPriceId": 318,
-          "taxCode": "V21",
-          "taxPercentage": 21.0000,
-          "amountExclTax": 94,
-          "amountInclTax": 100,
-          "fromInclusive": "2024-09-06T00:00:00.000+00:00",
-          "toInclusive": "2024-12-18T23:59:59.000+00:00",
-          "internalPrice": 92.0000
-        },
-        {
-          "sellingPriceId": 319,
-          "taxCode": "V21",
-          "taxPercentage": 21.0000,
-          "amountExclTax": 98,
-          "amountInclTax": 102,
-          "fromInclusive": "2024-12-19T00:00:00.000+00:00",
-          "toInclusive": "2024-12-29T23:59:59.000+00:00",
-          "internalPrice": 0.0000
-        }
-      ]
-    },
-    {
-      "sellingPeriodId": 241,
-      "fromInclusive": "2024-09-06T00:00:00.000+00:00",
-      "toInclusive": "2024-12-29T23:59:59.000+00:00",
-      "salesTouchpoint": {
-        "salesTouchpointId": 5,
-        "name": "Servicewinkel (Team Incident Masters)",
+        "salesTouchpointId": 3,
+        "name": "Website",
         "isActive": true,
         "retailer": {
           "retailerId": 1001,
@@ -139,64 +91,196 @@
           "country": "Nederland",
           "emailAddress": "info@htm.nl",
           "phoneNumber": "070 374 9002",
-          "taxId": null,
-          "imageReference": "https://www.htm.nl/typo3conf/ext/htm_template/Resources/Public/img/logo.svg"
+          "taxId": 572309345923,
+          "imageReference": "https://www.htm.nl/media/leif2leu/htm-logo-mobile.svg"
         }
       },
-      "forbiddenPaymentMethods": [
+      "forbiddenPaymentMethods": [],
+      "sellingPrices": []
+    }
+  ],
+  "purchasePrices": [],
+  "productVariants": [
+    {
+      "productId": 664,
+      "parentProductId": 663,
+      "layerInfo": {
+        "layerInfoId": null,
+        "choiceKey": null,
+        "choiceLabel": null,
+        "isCustomChoice": false
+      },
+      "fikoArticleNumber": null,
+      "gboPackageTemplateId": "30001",
+      "tapConnectProductCode": null,
+      "productName": "Losse week - Test OVPAY-2306",
+      "productDescription": "Test OVPAY-2306 (sellingPeriods in kindje verwijderen en later opnieuw weer kunnen toevoegen)",
+      "validityPeriod": {
+        "validityPeriodId": 783,
+        "fromInclusive": "2025-12-31T23:00:00.000Z",
+        "toInclusive": "2026-03-30T22:00:00.000Z"
+      },
+      "productTranslations": [],
+      "allowedGboAgeProfiles": [],
+      "productOwner": {
+        "productOwnerId": 1,
+        "name": "Wie dit leest",
+        "organization": "... is een aap."
+      },
+      "marketSegments": [],
+      "customerSegments": [],
+      "productCategory": {
+        "productCategoryId": 1,
+        "isTravelProduct": true,
+        "name": "Kortingsabonnement"
+      },
+      "requiredCustomerLevel": {
+        "requiredCustomerLevelId": 1,
+        "name": "guest"
+      },
+      "requiredProducts": [],
+      "incompatibleProducts": [],
+      "mandatoryCustomerDataItems": [],
+      "requiredGboPersonalAttributes": [],
+      "tokenTypes": [
         {
-          "forbiddenPaymentMethodId": 2,
-          "name": "creditcard",
-          "issuer": "Visa"
+          "tokenTypeId": 1,
+          "name": "EMV"
         }
       ],
-      "sellingPrices": [
+      "paymentMoment": {
+        "paymentMomentId": 1,
+        "name": "prepaid"
+      },
+      "serviceOptions": [
         {
-          "sellingPriceId": 320,
-          "taxCode": "V21",
-          "taxPercentage": 21.0000,
-          "amountExclTax": 94,
-          "amountInclTax": 100,
-          "fromInclusive": "2024-09-06T00:00:00.000+00:00",
-          "toInclusive": "2024-12-18T23:59:59.000+00:00",
-          "internalPrice": 92.0000
+          "serviceOptionId": 4,
+          "action": "cancel_notAllowed",
+          "description": "Stopzetting is niet toegestaan (doorgaans in combinatie met refund_notAllowed)"
         },
         {
-          "sellingPriceId": 321,
-          "taxCode": "V21",
-          "taxPercentage": 21.0000,
-          "amountExclTax": 98,
-          "amountInclTax": 102,
-          "fromInclusive": "2024-12-19T00:00:00.000+00:00",
-          "toInclusive": "2024-12-29T23:59:59.000+00:00",
-          "internalPrice": 0.0000
+          "serviceOptionId": 10,
+          "action": "refund_notAllowed",
+          "description": "Terugbetaling niet toegestaan (doorgaans in combinatie met cancel_notAllowed)"
         }
-      ]
-    }
-  ],
-  "purchasePrices": [
-    {
-      "purchasePriceId": 184,
-      "taxCode": "V21",
-      "taxPercentage": 21.0000,
-      "amountExclTax": 0,
-      "amountInclTax": 0,
-      "fromInclusive": "2024-09-01T00:00:00.000+00:00",
-      "toInclusive": "2024-12-31T23:59:59.000+00:00"
-    }
-  ],
-  "auditTrail": [
-    {
-      "auditTrailId": 228,
-      "action": "update",
-      "user": "api",
-      "timestamp": "2024-10-21T09:00:30.410+00:00"
+      ],
+      "validityDuration": "P1W",
+      "maxStartInFutureDuration": "P1W",
+      "isRenewable": false,
+      "sendInvoice": false,
+      "imageReference": null,
+      "productPageUrl": null,
+      "termsUrl": null,
+      "isSellableAtHtm": true,
+      "needsSolvencyCheckConsumer": false,
+      "needsSolvencyCheckBusiness": false,
+      "sellingPeriods": [
+        {
+          "sellingPeriodId": 1384,
+          "fromInclusive": "2025-12-31T23:00:00.000Z",
+          "toInclusive": "2026-03-30T22:00:00.000Z",
+          "salesTouchpoint": {
+            "salesTouchpointId": 3,
+            "name": "Website",
+            "isActive": true,
+            "retailer": {
+              "retailerId": 1001,
+              "name": "HTM externe touchpoints",
+              "street": "Koningin Julianaplein",
+              "number": 10,
+              "numberAddition": null,
+              "postalCode": "2595 AA",
+              "city": "Den Haag",
+              "country": "Nederland",
+              "emailAddress": "info@htm.nl",
+              "phoneNumber": "070 374 9002",
+              "taxId": 572309345923,
+              "imageReference": "https://www.htm.nl/media/leif2leu/htm-logo-mobile.svg"
+            }
+          },
+          "forbiddenPaymentMethods": [],
+          "sellingPrices": []
+        }
+      ],
+      "purchasePrices": [],
+      "productVariants": []
     },
     {
-      "auditTrailId": 227,
-      "action": "insert",
-      "user": "api",
-      "timestamp": "2024-10-21T08:58:39.237+00:00"
+      "productId": 665,
+      "parentProductId": 663,
+      "layerInfo": {
+        "layerInfoId": null,
+        "choiceKey": null,
+        "choiceLabel": null,
+        "isCustomChoice": false
+      },
+      "fikoArticleNumber": null,
+      "gboPackageTemplateId": "30001",
+      "tapConnectProductCode": null,
+      "productName": "Doorlopend - Test OVPAY-2306",
+      "productDescription": "Test OVPAY-2306 (sellingPeriods in kindje verwijderen en later opnieuw weer kunnen toevoegen)",
+      "validityPeriod": {
+        "validityPeriodId": 784,
+        "fromInclusive": "2025-12-31T23:00:00.000Z",
+        "toInclusive": "2026-03-30T22:00:00.000Z"
+      },
+      "productTranslations": [],
+      "allowedGboAgeProfiles": [],
+      "productOwner": {
+        "productOwnerId": 1,
+        "name": "Wie dit leest",
+        "organization": "... is een aap."
+      },
+      "marketSegments": [],
+      "customerSegments": [],
+      "productCategory": {
+        "productCategoryId": 1,
+        "isTravelProduct": true,
+        "name": "Kortingsabonnement"
+      },
+      "requiredCustomerLevel": {
+        "requiredCustomerLevelId": 1,
+        "name": "guest"
+      },
+      "requiredProducts": [],
+      "incompatibleProducts": [],
+      "mandatoryCustomerDataItems": [],
+      "requiredGboPersonalAttributes": [],
+      "tokenTypes": [
+        {
+          "tokenTypeId": 1,
+          "name": "EMV"
+        }
+      ],
+      "paymentMoment": {
+        "paymentMomentId": 1,
+        "name": "prepaid"
+      },
+      "serviceOptions": [
+        {
+          "serviceOptionId": 4,
+          "action": "cancel_notAllowed",
+          "description": "Stopzetting is niet toegestaan (doorgaans in combinatie met refund_notAllowed)"
+        },
+        {
+          "serviceOptionId": 10,
+          "action": "refund_notAllowed",
+          "description": "Terugbetaling niet toegestaan (doorgaans in combinatie met cancel_notAllowed)"
+        }
+      ],
+      "validityDuration": "P1W",
+      "maxStartInFutureDuration": "P1W",
+      "isRenewable": true,
+      "sendInvoice": false,
+      "imageReference": null,
+      "productPageUrl": null,
+      "termsUrl": null,
+      "isSellableAtHtm": true,
+      "needsSolvencyCheckConsumer": false,
+      "needsSolvencyCheckBusiness": false,
+      "sellingPeriods": [],
+      "purchasePrices": [],
+      "productVariants": []
     }
   ]
 }

src/java/rabbitmq-poc/src/main/java/nl/ovpay/queue/Helpers.java

@@ -28,10 +28,33 @@ public final class Helpers {
         return new JSONObject(string).get("alertId").toString();
     }
 
+    public static String getTripId(String string) throws IOException {
+        return new JSONObject(string).get("tripId").toString();
+    }
+
     public static String getXbot(String string) throws IOException {
         return new JSONObject(string).get("xbot").toString();
     }
 
+    public static void getTripDetails(String tripId, String xbot, String gboBearerToken) throws Exception {
+        SSLContext sc = SSLContext.getInstance("SSL");
+        sc.init(null, DummyX509TrustManager.getDummyArray(), new java.security.SecureRandom());
+        HttpsURLConnection.setDefaultSSLSocketFactory(sc.getSocketFactory());
+
+        URL url = new URL("https://api.sbx.idbt.translink.nl/api/v3/id-media/tokens/xbot/" + xbot + "/trips/details/" + tripId);
+        URLConnection con = url.openConnection();
+        HttpURLConnection http = (HttpURLConnection)con;
+        http.setRequestMethod("GET");
+        http.setDoOutput(true);
+        http.setRequestProperty("Authorization", "Bearer " + gboBearerToken);
+        http.connect();
+
+        try(InputStream is = http.getInputStream()) {
+            String response = new String(is.readAllBytes(), StandardCharsets.UTF_8);
+            LOGGER.info("GBO API 8659 trip details response for xBOT " + xbot + " and tripId " + tripId + ": \n" + new JSONObject(response).toString(2));
+        }
+    }
+
     public static void getAlertDetails(String alertId, String xBot, String gboBearerToken) throws Exception {
         SSLContext sc = SSLContext.getInstance("SSL");
         sc.init(null, DummyX509TrustManager.getDummyArray(), new java.security.SecureRandom());
@@ -48,7 +71,7 @@ public final class Helpers {
 
         try(InputStream is = http.getInputStream()) {
             String response = new String(is.readAllBytes(), StandardCharsets.UTF_8);
-            LOGGER.info("GBO API 8851 alert details response for xBOT " + xBot + ": \n" + new JSONObject(response).toString(2));
+            LOGGER.info("GBO API 8851 alert details response for xBOT " + xBot + " and alertId " + alertId + ": \n" + new JSONObject(response).toString(2));
         }
     }
 

src/java/rabbitmq-poc/src/main/java/nl/ovpay/queue/RabbitConnector.java

@@ -16,14 +16,28 @@ public class RabbitConnector {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(RabbitConnector.class);
 
+    // TRIPS
+    // SubscriptionId = 3e246de5-d3ad-468f-834b-1aaebf52244c
+    // Use API 9853 to manually add xBOT to queue
+    private static final String QUEUE_NAME = "BEID_3.TRIPS";
+    private static final String USER_NAME = "BEID_3_TRIPS_HlTT";
+    private static final String PASSWORD = "xJR4C8hIqhHQw0sn";
+
+    // ALERTS
+    // SubscriptionId = 17c8100b-88a2-4cef-b40d-8dca4f93d311
+    // Use API 9853 to manually add xBOT to queue
+    // private static final String QUEUE_NAME = "BEID_3.ALERTS";
+    // private static final String USER_NAME = "BEID_3_ALERTS_nZs3";
+    // private static final String PASSWORD = "VyubhPnczKgTB2zJ";
+
     public static void main(String[] args) throws Exception {
         ConnectionFactory factory = new ConnectionFactory();
         factory.setVirtualHost("/");
         factory.setAutomaticRecoveryEnabled(true);
         factory.setPort(443);
         factory.setHost("not.sbx.idbt.translink.nl");
-        factory.setUsername("BEID_3_ALERTS_nZs3");
-        factory.setPassword("VyubhPnczKgTB2zJ");
+        factory.setUsername(USER_NAME);
+        factory.setPassword(PASSWORD);
         factory.useSslProtocol("TLSv1.2");
         factory.setExceptionHandler(new ForgivingExceptionHandler());
         Map<String, Object> configs = factory.getClientProperties();
@@ -33,7 +47,7 @@ public class RabbitConnector {
         Channel channel = connection.createChannel();
         DeliverCallback deliverCallback = initDeliverCallback(channel);
 
-        AMQP.Queue.DeclareOk queue = channel.queueDeclarePassive("BEID_3.ALERTS");
+        AMQP.Queue.DeclareOk queue = channel.queueDeclarePassive(QUEUE_NAME);
         LOGGER.info(
                 "Declared queue: " + queue.getQueue() + ", consumer count: " + queue.getConsumerCount() + ", message count: " +
                 queue.getMessageCount());
@@ -52,17 +66,39 @@ public class RabbitConnector {
             channel.basicAck(delivery.getEnvelope().getDeliveryTag(), false);
             LOGGER.info("Successfully acknowledged message with delivery tag: " + delivery.getEnvelope().getDeliveryTag());
 
-            LOGGER.info("Getting alert details via GBO API 8851...");
-            try {
-                String alertId = Helpers.getAlertId(message);
-                String xBot = Helpers.getXbot(message);
-                String gboBearerToken = Helpers.getGboBearerToken();
-
-                Helpers.getAlertDetails(alertId, xBot, gboBearerToken);
-
-            } catch (Exception e) {
-                throw new RuntimeException(e);
+            if (QUEUE_NAME.equals("BEID_3.TRIPS")) {
+                getTripDetails(message);
+            } else if (QUEUE_NAME.equals("BEID_3.ALERTS")) {
+                getAlertDetails(message);
             }
         };
     }
+
+    private static void getAlertDetails(String message) {
+        try {
+            String alertId = Helpers.getAlertId(message);
+            String xBot = Helpers.getXbot(message);
+            String gboBearerToken = Helpers.getGboBearerToken();
+
+            LOGGER.info("Getting alert details for xBOT {} and alertId {} via GBO API 8851...", xBot, alertId);
+            Helpers.getAlertDetails(alertId, xBot, gboBearerToken);
+
+        } catch (Exception e) {
+            throw new RuntimeException(e);
+        }
+    }
+
+    private static void getTripDetails(String message) {
+        try {
+            String tripId = Helpers.getTripId(message);
+            String xBot = Helpers.getXbot(message);
+            String gboBearerToken = Helpers.getGboBearerToken();
+
+            LOGGER.info("Getting trip details for xBOT {} and tripId {} via GBO API 8659...", xBot, tripId);
+            Helpers.getTripDetails(tripId, xBot, gboBearerToken);
+
+        } catch (Exception e) {
+            throw new RuntimeException(e);
+        }
+    }
 }

src/openapi/claims/claims-forms.yaml

@@ -17,10 +17,10 @@ paths:
       description: >
         Create a claim by sending a JSON as specified in the schema. By
         specifying the chipcardnumber under 'chipkaart',
-
-        a claim for OV chipcard will be send to the OVC API. If no
-        chipcardnumber is specified under 'chipkaart', a claim for EMV is send
-        to mendix.
+        a claim for OV chipcard will be sent to the OVC API. If no
+        chipcardnumber is specified under 'chipkaart', a claim for EMV/OV-pas is sent
+        to Mendix, where it can be handled according to the fields present 
+        (serviceRefId + totaalbedrag or ovPasNumber + verificationCode)
       parameters: []
       requestBody:
         content:
@@ -47,8 +47,6 @@ paths:
                   toelichting: string
                   lijn: '1'
                   vervoertype: '1'
-                  serviceRefId: '1'
-                  Totaalbedrag: 0
               EMV:
                 value:
                   aankomsthalte: '1'
@@ -67,8 +65,28 @@ paths:
                   toelichting: string
                   lijn: '1'
                   vervoertype: '1'
-                  serviceRefId: '1'
-                  Totaalbedrag: 0
+                  serviceRefId: 'NLOV1234567ABCDEFG'
+                  totaalbedrag: 3.14
+              OV-pas:
+                value:
+                  aankomsthalte: '1'
+                  instapdatum: '2024-03-06T15:20:44.549Z'
+                  instaptijd: '2024-03-06T15:20:44.549Z'
+                  ingecheckt: true
+                  uitgecheckt: true
+                  afgeschrevenbedrag: 0
+                  vertrekhalte: string
+                  korting: true
+                  iban: '1234123412341234'
+                  naam: string
+                  emailadres: user@example.com
+                  uitstaptijd: '2024-03-06T15:20:44.549Z'
+                  verwachtbedrag: 0
+                  toelichting: string
+                  lijn: '1'
+                  vervoertype: '1'
+                  ovPasNumber: '63AW974'
+                  verificationCode: '2FQ8'
       responses:
         '200':
           description: ok
@@ -103,18 +121,19 @@ paths:
             examples:
               EMV:
                 value:
-                  emailAddress: 'j.beek@htm.nl'
+                  emailAddress: 'stasjo@htm.nl'
                   orderNumber: 'ORD1000046'
                   serviceReferenceId: 'NLOVA5BCD124H3Z21X'
                   amount: 2305
                   iban: 'NL98INGB0003856625'
                   orderDate: '2025-01-13'
                   productName: 'HTM 20% korting'
-              OVpas:
+              OV-pas:
                 value:
-                  emailAddress: 'j.beek@htm.nl'
+                  emailAddress: 'stasjo@htm.nl'
                   orderNumber: 'ORD1000046'
                   ovpasNumber: '63AW974'
+                  verificationCode: '2FQ8'
                   iban: 'NL98INGB0003856625'
                   orderDate: '2025-01-13'
                   productName: 'HTM 20% korting'
@@ -181,7 +200,7 @@ components:
         iban:
           type: string
           description: String of length between 15 en 32 characters
-          example: '1234123412341234'
+          example: NL98INGB0003856625
         naam:
           type: string
         emailadres:
@@ -201,9 +220,16 @@ components:
           type: string
         serviceRefId:
           type: string
-        Totaalbedrag:
+          example: NLOV1234567ABCDEFG
+        totaalbedrag:
           type: number
           format: float
+        ovPasNumber:
+          type: string
+          example: 63AW974
+        verificationCode:
+          type: string
+          example: 2FQ8
     refundsEntity:
       required:
           - emailAddress
@@ -213,7 +239,7 @@ components:
         emailAddress:
           type: string
           format: email
-          example: j.beek@htm.nl
+          example: stasjo@htm.nl
         orderNumber:
           type: string
           example: ORD1000046
@@ -226,6 +252,9 @@ components:
         ovpasNumber:
           type: string
           example: 63AW974
+        verificationCode:
+          type: string
+          example: 2FQ8
         iban:
           type: string
           example: NL00RABO000001337

src/openapi/contracts/contracts-se.yaml

@@ -45,12 +45,36 @@ paths:
                         "contractStatus":
                           { "contractStatusId": 2, "name": "active" },
                         "productId": 1,
-                        "productName": "HTM Maand 20% korting",
-                        "termDuration": "P0Y1M0D",
+                        "productName": "HTM Maand 20% korting doorlopend",
+                        "termDuration": "P1M",
                         "billingDay": 15,
                         "highestInvoiceTerm": 1,
-                        "created": "2024-08-01 15:01:00.000",
+                        "created": "2024-08-01T15:01:00.000Z",
                         "ovPayTokenId": 1337,
+                        "contractVersions": [
+                          {
+                            "contractVersionId": 1,
+                            "termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
+                            "productId": 1,
+                            "productName": "HTM Maand 20% korting doorlopend",
+                            "taxCode": "V9",
+                            "taxPercentage": 9,
+                            "termAmountInclTax": 400,
+                            "start": "2024-08-01T15:01:00.000Z",
+                            "end": "2025-01-01T03:00:00.000Z"
+                          },
+                          {
+                            "contractVersionId": 2,
+                            "termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
+                            "productId": 1,
+                            "productName": "HTM Maand 20% korting doorlopend",
+                            "taxCode": "V9",
+                            "taxPercentage": 9,
+                            "termAmountInclTax": 500,
+                            "start": "2025-01-01T03:00:00.000Z",
+                            "end": null
+                          }
+                        ],
                         "_links":
                           {
                             "get_token":
@@ -68,14 +92,38 @@ paths:
                         "orderLineId": "42f68042-908f-41f4-9d9b-4cab843ff0e8",
                         "touchpointId": 2,
                         "contractStatus":
-                          { "contractStatusId": 1, "name": "new" },
+                          { "contractStatusId": 6, "name": "pending cancellation" },
                         "productId": 1,
-                        "productName": "HTM Maand 20% korting",
-                        "termDuration": "P0Y1M0D",
+                        "productName": "HTM 20% Korting doorlopend",
+                        "termDuration": "P1M",
                         "billingDay": 15,
                         "highestInvoiceTerm": 1,
-                        "created": "2024-08-01 15:01:00.000",
+                        "created": "2024-08-01T15:01:00.000Z",
                         "ovPayTokenId": 1338,
+                        "contractVersions": [
+                          {
+                            "contractVersionId": 1,
+                            "termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
+                            "productId": 1,
+                            "productName": "HTM 20% Korting doorlopend",
+                            "taxCode": "V9",
+                            "taxPercentage": 9,
+                            "termAmountInclTax": 400,
+                            "start": "2024-08-01T15:01:00.000Z",
+                            "end": "2025-01-01T03:00:00.000Z"
+                          },
+                          {
+                            "contractVersionId": 2,
+                            "termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
+                            "productId": 1,
+                            "productName": "HTM 20% Korting doorlopend",
+                            "taxCode": "V9",
+                            "taxPercentage": 9,
+                            "termAmountInclTax": 500,
+                            "start": "2025-01-01T03:00:00.000Z",
+                            "end": "2025-02-01T03:00:00.000Z"
+                          }
+                        ],
                         "_links":
                           {
                             "get_token":
@@ -154,8 +202,8 @@ paths:
                       "contractStatus":
                         { "contractStatusId": 2, "name": "active" },
                       "productId": 1,
-                      "productName": "HTM Maand 20% korting",
-                      "termDuration": "P0Y1M0D",
+                      "productName": "HTM 20% Korting doorlopend",
+                      "termDuration": "P1M",
                       "billingDay": 15,
                       "highestInvoiceTerm": 1,
                       "ovPayTokenId": 1337,
@@ -165,22 +213,22 @@ paths:
                             "contractVersionId": 1,
                             "termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
                             "productId": 1,
-                            "productName": "HTM Maand 20% korting",
+                            "productName": "HTM 20% Korting doorlopend",
                             "taxCode": "V9",
                             "taxPercentage": 9.0,
                             "termAmountInclTax": 400,
-                            "start": "2024-07-04 15:01:00.000",
-                            "end": "2024-12-31 15:01:00.000",
+                            "start": "2024-08-01T15:01:00.000Z",
+                            "end": "2025-01-01T03:00:00.000Z",
                           },
                           {
                             "contractVersionId": 2,
                             "termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
                             "productId": 1,
-                            "productName": "HTM Maand 20% korting",
+                            "productName": "HTM 20% Korting doorlopend",
                             "taxCode": "V9",
                             "taxPercentage": 9.0,
                             "termAmountInclTax": 400,
-                            "start": "2025-01-01 15:01:00.000",
+                            "start": "2025-01-01T03:00:00.000Z",
                           },
                         ],
                       "contractActions":
@@ -190,7 +238,7 @@ paths:
                             "actionType":
                               { "actionTypeId": 1, "name": "create" },
                             "user": "subid123456",
-                            "timestamp": "2024-07-02 15:01:00.000",
+                            "timestamp": "2024-07-02T15:01:00.000Z",
                             "details": "Contract created",
                             "correlationId": "976e7a4c-bf24-43d2-b444-55817556e7ee",
                           },
@@ -199,7 +247,7 @@ paths:
                             "actionType":
                               { "actionTypeId": 2, "name": "change" },
                             "user": "subid123456",
-                            "timestamp": "2024-07-03 15:01:00.000",
+                            "timestamp": "2024-07-03T15:01:00.000Z",
                             "details": "Contract changed",
                             "correlationId": "e2462347-6749-4841-b42a-cf8de19ec727",
                           },
@@ -211,8 +259,8 @@ paths:
                             "externalReference": "F2024-0001",
                             "term": 1,
                             "invoiceDate": "2024-07-02",
-                            "created": "2024-07-02 15:01:00.000",
-                            "updated": "2024-07-02 15:01:00.000",
+                            "created": "2024-07-02T15:01:00.000Z",
+                            "updated": "2024-07-02T15:01:00.000Z",
                             "state": "invoice_created",
                             "data": "{json}",
                             "isCredit": false,
@@ -270,8 +318,8 @@ paths:
                         "externalReference": "F2024-0001",
                         "term": 1,
                         "invoiceDate": "2024-07-02",
-                        "created": "2024-07-02 15:01:34.000",
-                        "updated": "2024-07-04 00:04:56.000",
+                        "created": "2024-07-02T15:01:34.000Z",
+                        "updated": "2024-07-04T00:04:56.000Z",
                         "state": "invoice_created",
                         "public_link": "http://mijnfactuurinzien.nl/F2024-0001",
                         "isCredit": false,
@@ -282,8 +330,8 @@ paths:
                         "externalReference": "F2024-0002",
                         "term": 2,
                         "invoiceDate": "2024-08-02",
-                        "created": "2024-08-02 15:01:34.000",
-                        "updated": "2024-08-04 00:04:56.000",
+                        "created": "2024-08-02T15:01:34.000Z",
+                        "updated": "2024-08-04T00:04:56.000Z",
                         "state": "invoice_created",
                         "public_link": "http://mijnfactuurinzien.nl/F2024-0002",
                         "isCredit": false,
@@ -328,8 +376,8 @@ paths:
                       "cancellationMoment": "termBound",
                       "termDuration": "P1M",
                       "billingDay": 18,
-                      "cancellationFrom": "2024-08-10T00:00:00",
-                      "cancellationUntil": "2026-08-10T00:00:00",
+                      "cancellationFrom": "2024-08-10T00:00:00Z",
+                      "cancellationUntil": "2026-08-10T00:00:00Z",
                     }
   /contracts/{contractId}/cancellationvalidation:
     parameters:
@@ -382,14 +430,14 @@ paths:
                     {
                       "validationResult": true,
                       "validationMessage": "",
-                      "end": "2024-08-10T03:59:59",
+                      "end": "2024-08-10T03:59:59Z",
                       "refundAmount": 2489,
                       "refundMethods": ["creditInvoice", "iDeal"],
                     }
-                Unsuccesful validation:
-                  summary: Unsuccesful validation
+                Unsuccessful validation:
+                  summary: Unsuccessful validation
                   description: |
-                    Unsuccesful validation. The response contains the error message.
+                    Unsuccessful validation. The response contains the error message.
                   value:
                     {
                       "validationResult": false,
@@ -451,7 +499,7 @@ paths:
                     the refund amount and refund method.
                   value:
                     {
-                      "end": "2024-08-10T03:59:59",
+                      "end": "2024-08-10T03:59:59Z",
                       "refundAmount": 2489,
                       "refundMethod": "creditInvoice",
                     }
@@ -516,8 +564,8 @@ paths:
                             "taxCode": "V9",
                             "taxPercentage": 9.0,
                             "termAmountInclTax": 400,
-                            "start": "2024-07-04 15:01:00.000",
-                            "end": "2024-12-31 15:01:00.000",
+                            "start": "2024-07-04T15:01:00.000Z",
+                            "end": "2024-12-31T15:01:00.000Z",
                           },
                           {
                             "contractVersionId": 2,
@@ -527,7 +575,8 @@ paths:
                             "taxCode": "V9",
                             "taxPercentage": 9.0,
                             "termAmountInclTax": 400,
-                            "start": "2025-01-01 15:01:00.000",
+                            "start": "2025-01-01T15:01:00.000Z",
+                            "end": null
                           },
                         ],
                       "contractActions":
@@ -537,7 +586,7 @@ paths:
                             "actionType":
                               { "actionTypeId": 1, "name": "create" },
                             "user": "subid123456",
-                            "timestamp": "2024-07-02 15:01:00.000",
+                            "timestamp": "2024-07-02T15:01:00.000Z",
                             "details": "Contract created",
                             "correlationId": "976e7a4c-bf24-43d2-b444-55817556e7ee",
                           },
@@ -546,7 +595,7 @@ paths:
                             "actionType":
                               { "actionTypeId": 2, "name": "change" },
                             "user": "subid123456",
-                            "timestamp": "2024-07-03 15:01:00.000",
+                            "timestamp": "2024-07-03T15:01:00.000Z",
                             "details": "Contract changed",
                             "correlationId": "e2462347-6749-4841-b42a-cf8de19ec727",
                           },
@@ -558,8 +607,8 @@ paths:
                             "externalReference": "F2024-0001",
                             "term": 1,
                             "invoiceDate": "2024-07-02",
-                            "created": "2024-07-02 15:01:00.000",
-                            "updated": "2024-07-02 15:01:00.000",
+                            "created": "2024-07-02T15:01:00.000Z",
+                            "updated": "2024-07-02T15:01:00.000Z",
                             "state": "invoice_created",
                             "data": "{json}",
                             "isCredit": false,
@@ -574,6 +623,267 @@ paths:
                             },
                         },
                     }
+  /contracts/{uuid}/changemoments:
+    parameters:
+      - in: header
+        name: X-HTM-JWT-AUTH-HEADER
+        schema:
+          type: string
+          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+        required: true
+        description: The JWT of the logged in customer.
+      - in: path
+        name: uuid
+        schema:
+          type: string
+          format: uuid
+          example: 9e224750-3065-471d-af57-85b9cffa7c89
+        required: true
+        description: The id of the contract to process.
+    get:
+      summary: Get all change moments for a given contract.
+      description: Get all change moments for a given contract.
+      tags:
+        - SE Contract Changes v2
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/unavailable"
+              examples:
+                All change moments of a contract:
+                  summary: All change moments of a contract
+                  description: |
+                    All change moments of a contract. The response contains the
+                    allowed change moments for the current contract term.
+                  value:
+                    {
+                      "changeMoment": "termBound",
+                      "termDuration": "P1M",
+                      "billingDay": 18,
+                      "changeFrom": "2024-08-10T00:00:00",
+                      "changeUntil": "2024-08-10T03:59:59",
+                    }
+  /contracts/{uuid}/changevalidation:
+    parameters:
+      - in: header
+        name: X-HTM-JWT-AUTH-HEADER
+        schema:
+          type: string
+          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+        required: true
+        description: The JWT of the logged in customer.
+      - in: path
+        name: uuid
+        schema:
+          type: string
+          format: uuid
+          example: 9e224750-3065-471d-af57-85b9cffa7c89
+        required: true
+        description: The id of the contract to process.
+    post:
+      summary: Validate a change for a given contract.
+      description: Validate a change for a given contract.
+      tags:
+        - SE Contract Changes v2
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/unavailable"
+            examples:
+              Validate a change to another product:
+                summary: Validate a change to another product
+                description: |
+                  Validate a change to another product. The response contains the allowed change moments for the current contract term.
+                value: { "productId": 124, "startDate": "2025-10-08" }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/unavailable"
+              examples:
+                Successfully validated change:
+                  summary: Successfully validated change
+                  description: |
+                    Successfully validated a change. The response contains the allowed change moments for the current contract term.
+                  value:
+                    {
+                      "validationResult": true,
+                      "validationMessage": "",
+                      "contract":
+                        {
+                          "contractId": "15b43d9b-367a-4952-87f6-3e0fa902486f",
+                          "contractNumber": "D123456",
+                          "customerProfileId": 42,
+                          "orderId": "eb3d08f7-7feb-4f31-9f5b-daa634e51f48",
+                          "orderLineId": "52efbbfc-8c28-4016-9ece-dc3ef9a70bd8",
+                          "touchpointId": 2,
+                          "contractStatus":
+                            { "contractStatusId": 2, "name": "active" },
+                          "productId": 1,
+                          "productName": "HTM Maand 20% korting",
+                          "termDuration": "P0Y1M0D",
+                          "billingDay": 15,
+                          "highestInvoiceTerm": 1,
+                          "created": "2024-08-01T15:01:00.000Z",
+                          "ovPayTokenId": 1337,
+                          "contractVersions":
+                            [
+                              {
+                                "contractVersionId": 2,
+                                "termsAndConditions": "https://www.htm.nl",
+                                "productId": 124,
+                                "productName": "Regiovrij Regio Centrum",
+                                "taxCode": "V9",
+                                "taxPercentage": 9.0,
+                                "termAmountInclTax": 12,
+                                "start": "2025-10-08",
+                              },
+                              {
+                                "contractVersionId": 1,
+                                "termsAndConditions": "https://www.htm.nl",
+                                "productId": 123,
+                                "productName": "Regiovrij Regio Zuid",
+                                "taxCode": "V9",
+                                "taxPercentage": 9.0,
+                                "termAmountInclTax": 10,
+                                "start": "2025-01-08",
+                                "end": "2025-10-07",
+                              },
+                            ],
+                        },
+                    }
+                Unsuccessful validation:
+                  summary: Unsuccessful validation
+                  description: |
+                    Unsuccessful validation. The response contains the error message.
+                  value:
+                    {
+                      "validationResult": false,
+                      "validationMessage": "Contract status is not ACTIVE",
+                      "contract": null,
+                    }
+  /contracts/{uuid}/change:
+    parameters:
+      - in: header
+        name: X-HTM-JWT-AUTH-HEADER
+        schema:
+          type: string
+          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+        required: true
+        description: The JWT of the logged in customer.
+      - in: path
+        name: uuid
+        schema:
+          type: string
+          format: uuid
+          example: 9e224750-3065-471d-af57-85b9cffa7c89
+        required: true
+        description: The id of the contract to process.
+    post:
+      summary: Change a contract.
+      description: Change a contract.
+      tags:
+        - SE Contract Changes v2
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/unavailable"
+            examples:
+              Change to another product:
+                summary: Change to another product
+                description: |
+                  Change to another product. The response contains the details of the changed contract.
+                value: { "productId": 124, "startDate": "2025-10-08" }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/unavailable"
+              examples:
+                Successfully changed contract:
+                  summary: Successfully changed contract
+                  description: |
+                    Successfully changed a contract. The response contains the details of the changed contract.
+                  value:
+                    {
+                      "contractId": "15b43d9b-367a-4952-87f6-3e0fa902486f",
+                      "contractNumber": "D123456",
+                      "customerProfileId": 42,
+                      "orderId": "eb3d08f7-7feb-4f31-9f5b-daa634e51f48",
+                      "orderLineId": "52efbbfc-8c28-4016-9ece-dc3ef9a70bd8",
+                      "touchpointId": 2,
+                      "contractStatus":
+                        { "contractStatusId": 2, "name": "active" },
+                      "productId": 1,
+                      "productName": "HTM Maand 20% korting",
+                      "termDuration": "P0Y1M0D",
+                      "billingDay": 15,
+                      "highestInvoiceTerm": 1,
+                      "created": "2024-08-01T15:01:00.000Z",
+                      "ovPayTokenId": 1337,
+                      "contractVersions":
+                        [
+                          {
+                            "contractVersionId": 2,
+                            "termsAndConditions": "https://www.htm.nl",
+                            "productId": 124,
+                            "productName": "Regiovrij Regio Centrum",
+                            "taxCode": "V9",
+                            "taxPercentage": 9.0,
+                            "termAmountInclTax": 12,
+                            "start": "2025-10-08",
+                          },
+                          {
+                            "contractVersionId": 1,
+                            "termsAndConditions": "https://www.htm.nl",
+                            "productId": 123,
+                            "productName": "Regiovrij Regio Zuid",
+                            "taxCode": "V9",
+                            "taxPercentage": 9.0,
+                            "termAmountInclTax": 10,
+                            "start": "2025-01-08",
+                            "end": "2025-10-07",
+                          },
+                        ],
+                    }
+        "400":
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/unavailable"
+              examples:
+                Unsuccessful change due to invalid productId:
+                  summary: Unsuccessful change due to invalid productId
+                  description: |
+                    Unsuccessful change due to invalid productId. The response contains the error message.
+                  value:
+                    {
+                      "type": "https://htm.nl/api/v1/probs/validationerror",
+                      "title": "Your request is not valid.",
+                      "detail": "The chosen parameters for this contract change are not valid.",
+                      "instance": "urn:uuid:4017fabc-1b28-11e8-accf-0ed5f89f718b",
+                      "errors":
+                        [
+                          {
+                            "code": "CHANGE_DATE_IN_THE_PAST",
+                            "detail": "Chosen date of contract change is in the past. This is not alllowed.",
+                            "path": "$.startDate",
+                            "parameter": null,
+                          },
+                        ],
+                    }
   /contractpayments:
     parameters:
       - in: header
@@ -597,9 +907,13 @@ paths:
               schema:
                 $ref: "#/components/schemas/unavailable"
               examples:
-                List all contract payments for a single debtor:
-                  summary: List all contract payments for a single debtor
-                  description: List all contract payments for single debtor with debtor number 'D123456'.
+                Empty list:
+                  summary: Empty list
+                  description: List all contract payments for a debtor with no payments.
+                  value: { "contractPayments": [] }
+                Successful direct debit:
+                  summary: Successful direct debit
+                  description: One payment for a debtor with a successful direct debit.
                   value:
                     {
                       "contractPayments":
@@ -607,8 +921,133 @@ paths:
                           {
                             "paymentId": "151845776",
                             "totalAmount": "26.62",
-                            "paymentMethod": "Twikey",
+                            "paymentMethod": "Automatische incasso",
                             "paymentDate": "2024-09-12",
+                            "iban": "NL25INGB******1337",
+                            "invoice":
+                              {
+                                "invoiceId": "147722263",
+                                "invoiceNumber": "F2024-0001",
+                                "description": "HTM Maandkorting 20%",
+                                "publicLink": "https://factuurinzien.nl/d/b0aac3f42f325f5dd6abc172f723caab5956524d/i/ddb245d6df67999eca48c4a71b5661b93038e20a",
+                              },
+                            "_links":
+                              {
+                                "get_contractdetails":
+                                  {
+                                    "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/contracts/5ca46c1a-cb9d-4c2d-960e-4471e8e28b6a",
+                                    "method": "GET",
+                                  },
+                              },
+                          },
+                        ],
+                    }
+                Direct debit reversal:
+                  summary: Direct debit reversal
+                  description: One payment for a debtor with a reversed direct debit.
+                  value:
+                    {
+                      "contractPayments":
+                        [
+                          {
+                            "paymentId": "151845776",
+                            "totalAmount": "-26.62",
+                            "paymentMethod": "Stornering",
+                            "paymentDate": "2024-09-12",
+                            "iban": "NL25INGB******1337",
+                            "invoice":
+                              {
+                                "invoiceId": "147722263",
+                                "invoiceNumber": "F2024-0001",
+                                "description": "HTM Maandkorting 20%",
+                                "publicLink": "https://factuurinzien.nl/d/b0aac3f42f325f5dd6abc172f723caab5956524d/i/ddb245d6df67999eca48c4a71b5661b93038e20a",
+                              },
+                            "_links":
+                              {
+                                "get_contractdetails":
+                                  {
+                                    "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/contracts/5ca46c1a-cb9d-4c2d-960e-4471e8e28b6a",
+                                    "method": "GET",
+                                  },
+                              },
+                          },
+                        ],
+                    }
+                iDEAL payment:
+                  summary: iDEAL payment
+                  description: One payment for a debtor with an iDEAL payment.
+                  value:
+                    {
+                      "contractPayments":
+                        [
+                          {
+                            "paymentId": "151845776",
+                            "totalAmount": "26.62",
+                            "paymentMethod": "iDEAL",
+                            "paymentDate": "2024-09-12",
+                            "iban": "NL25INGB******1337",
+                            "invoice":
+                              {
+                                "invoiceId": "147722263",
+                                "invoiceNumber": "F2024-0001",
+                                "description": "HTM Maandkorting 20%",
+                                "publicLink": "https://factuurinzien.nl/d/b0aac3f42f325f5dd6abc172f723caab5956524d/i/ddb245d6df67999eca48c4a71b5661b93038e20a",
+                              },
+                            "_links":
+                              {
+                                "get_contractdetails":
+                                  {
+                                    "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/contracts/5ca46c1a-cb9d-4c2d-960e-4471e8e28b6a",
+                                    "method": "GET",
+                                  },
+                              },
+                          },
+                        ],
+                    }
+                Bank transfer:
+                  summary: Bank transfer
+                  description: One payment for a debtor with a bank transfer.
+                  value:
+                    {
+                      "contractPayments":
+                        [
+                          {
+                            "paymentId": "151845776",
+                            "totalAmount": "26.62",
+                            "paymentMethod": "Overboeking",
+                            "paymentDate": "2024-09-12",
+                            "iban": "NL25INGB******1337",
+                            "invoice":
+                              {
+                                "invoiceId": "147722263",
+                                "invoiceNumber": "F2024-0001",
+                                "description": "HTM Maandkorting 20%",
+                                "publicLink": "https://factuurinzien.nl/d/b0aac3f42f325f5dd6abc172f723caab5956524d/i/ddb245d6df67999eca48c4a71b5661b93038e20a",
+                              },
+                            "_links":
+                              {
+                                "get_contractdetails":
+                                  {
+                                    "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/contracts/5ca46c1a-cb9d-4c2d-960e-4471e8e28b6a",
+                                    "method": "GET",
+                                  },
+                              },
+                          },
+                        ],
+                    }
+                List of four payments for one invoice:
+                  summary: List of four payments for one invoice
+                  description: Four payments for a debtor for one invoice; a direct debit, a direct debit reversal, a bank transfer and an iDEAL payment.
+                  value:
+                    {
+                      "contractPayments":
+                        [
+                          {
+                            "paymentId": "151845776",
+                            "totalAmount": "26.62",
+                            "paymentMethod": "Automatische incasso",
+                            "paymentDate": "2024-09-12",
+                            "iban": "NL25INGB******1337",
                             "invoice":
                               {
                                 "invoiceId": "147722263",
@@ -626,22 +1065,67 @@ paths:
                               },
                           },
                           {
-                            "paymentId": "151845851",
-                            "totalAmount": "45.21",
-                            "paymentMethod": "Twikey",
+                            "paymentId": "151845776",
+                            "totalAmount": "-26.62",
+                            "paymentMethod": "Stornering",
                             "paymentDate": "2024-09-12",
+                            "iban": "NL25INGB******1337",
                             "invoice":
                               {
-                                "invoiceId": "147722266",
-                                "invoiceNumber": "F2024-0002",
+                                "invoiceId": "147722263",
+                                "invoiceNumber": "F2024-0001",
                                 "description": "HTM Maandkorting 20%",
-                                "publicLink": "https://factuurinzien.nl/d/ddb245d6df67999eca48c4a71b5661b93038e20a/i/dp5h1i5cuu94nopiolkdst3u17vkmzo",
+                                "publicLink": "https://factuurinzien.nl/d/b0aac3f42f325f5dd6abc172f723caab5956524d/i/ddb245d6df67999eca48c4a71b5661b93038e20a",
                               },
                             "_links":
                               {
                                 "get_contractdetails":
                                   {
-                                    "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/contracts/7b2f8c1a-3d9d-4c2d-960e-4471e8e28b6a",
+                                    "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/contracts/5ca46c1a-cb9d-4c2d-960e-4471e8e28b6a",
+                                    "method": "GET",
+                                  },
+                              },
+                          },
+                          {
+                            "paymentId": "151845777",
+                            "totalAmount": "10.00",
+                            "paymentMethod": "Overboeking",
+                            "paymentDate": "2024-09-13",
+                            "iban": "NL25INGB******1337",
+                            "invoice":
+                              {
+                                "invoiceId": "147722263",
+                                "invoiceNumber": "F2024-0001",
+                                "description": "HTM Maandkorting 20%",
+                                "publicLink": "https://factuurinzien.nl/d/b0aac3f42f325f5dd6abc172f723caab5956524d/i/ddb245d6df67999eca48c4a71b5661b93038e20a",
+                              },
+                            "_links":
+                              {
+                                "get_contractdetails":
+                                  {
+                                    "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/contracts/5ca46c1a-cb9d-4c2d-960e-4471e8e28b6a",
+                                    "method": "GET",
+                                  },
+                              },
+                          },
+                          {
+                            "paymentId": "151845778",
+                            "totalAmount": "16.62",
+                            "paymentMethod": "iDEAL",
+                            "paymentDate": "2024-09-14",
+                            "iban": "NL25INGB******1337",
+                            "invoice":
+                              {
+                                "invoiceId": "147722263",
+                                "invoiceNumber": "F2024-0001",
+                                "description": "HTM Maandkorting 20%",
+                                "publicLink": "https://factuurinzien.nl/d/b0aac3f42f325f5dd6abc172f723caab5956524d/i/ddb245d6df67999eca48c4a71b5661b93038e20a",
+                              },
+                            "_links":
+                              {
+                                "get_contractdetails":
+                                  {
+                                    "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/contracts/5ca46c1a-cb9d-4c2d-960e-4471e8e28b6a",
                                     "method": "GET",
                                   },
                               },

src/openapi/customers/SE-customers.yaml

@@ -359,7 +359,6 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/CustomersResponse"   
-    
   /customers/tokens:
     get:
       tags:
@@ -491,6 +490,7 @@ paths:
                             "ovPayTokenId": 1,
                             "xTat": "32089cc8-d187-47ff-a3a9-5c2558def811",
                             "tokenType": { "tokenTypeId": 1, "name": "EMV" },
+                            "ovpasNumber": "", 
                             "alias": "MyToken",
                             "tokenStatus":
                               { "tokenStatusId": 2, "name": "Active" },
@@ -567,6 +567,7 @@ paths:
                             "xTat": "32089cc8-d187-47ff-a3a9-5c2558def811",
                             "tokenType":
                               { "tokenTypeId": 2, "name": "OV-pas physical" },
+                            "ovpasNumber": "OV34567", 
                             "alias": "MyToken",
                             "tokenStatus":
                               { "tokenStatusId": 2, "name": "Active" },
@@ -649,6 +650,7 @@ paths:
                             "xTat": "32089cc8-d187-47ff-a3a9-5c2558def811",
                             "tokenType":
                               { "tokenTypeId": 2, "name": "OV-pas physical" },
+                            "ovpasNumber": "OV34567", 
                             "alias": "MyToken",
                             "tokenStatus":
                               { "tokenStatusId": 2, "name": "Active" },
@@ -771,6 +773,7 @@ paths:
                             "xTat": "32089cc8-d187-47ff-a3a9-5c2558def811",
                             "tokenType":
                               { "tokenTypeId": 2, "name": "OV-pas physical" },
+                            "ovpasNumber": "OV34567", 
                             "alias": "MyToken",
                             "tokenStatus":
                               { "tokenStatusId": 2, "name": "Active" },
@@ -868,6 +871,7 @@ paths:
                             "xTat": "32089cc8-d187-47ff-a3a9-5c2558def811",
                             "tokenType":
                               { "tokenTypeId": 2, "name": "OV-pas physical" },
+                            "ovpasNumber": "OV34567", 
                             "alias": "MyToken",
                             "tokenStatus":
                               { "tokenStatusId": 2, "name": "Active" },
@@ -983,6 +987,7 @@ paths:
                             "xTat": "e7fa3392-646b-40e2-95a6-c417dc0b0969",
                             "tokenType":
                               { "tokenTypeId": 2, "name": "OV-pas physical" },
+                            "ovpasNumber": "OV34567", 
                             "alias": "MyToken",
                             "tokenStatus":
                               { "tokenStatusId": 2, "name": "Active" },
@@ -1003,6 +1008,7 @@ paths:
                             "xTat": "e7fa3392-646b-40e2-95a6-c417dc0b0969",
                             "tokenType":
                               { "tokenTypeId": 2, "name": "OV-pas physical" },
+                            "ovpasNumber": "OV31236", 
                             "alias": "MyToken",
                             "tokenStatus":
                               { "tokenStatusId": 3, "name": "Replaced (*)" },
@@ -1024,6 +1030,7 @@ paths:
                             "xTat": "e7fa3392-646b-40e2-95a6-c417dc0b0969",
                             "tokenType":
                               { "tokenTypeId": 2, "name": "OV-pas physical" },
+                            "ovpasNumber": "OV36897", 
                             "alias": "MyToken",
                             "tokenStatus":
                               { "tokenStatusId": 4, "name": "On stock" },
@@ -1045,6 +1052,7 @@ paths:
                             "xTat": "e7fa3392-646b-40e2-95a6-c417dc0b0969",
                             "tokenType":
                               { "tokenTypeId": 2, "name": "OV-pas physical" },
+                            "ovpasNumber": "OV33489", 
                             "alias": "Mijn OV Pas",
                             "tokenStatus":
                               { "tokenStatusId": 5, "name": "Suspended" },
@@ -1066,6 +1074,7 @@ paths:
                             "xTat": "e7fa3392-646b-40e2-95a6-c417dc0b0969",
                             "tokenType":
                               { "tokenTypeId": 2, "name": "OV-pas physical" },
+                            "ovpasNumber": "OV48965", 
                             "alias": "Mijn OV Pas",
                             "tokenStatus":
                               {
@@ -1111,6 +1120,7 @@ paths:
                             "xTat": "e7fa3392-646b-40e2-95a6-c417dc0b0969",
                             "tokenType":
                               { "tokenTypeId": 2, "name": "OV-pas physical" },
+                            "ovpasNumber": "OV13458", 
                             "alias": "My found token",
                             "tokenStatus":
                               { "tokenStatusId": 7, "name": "Renewed Active" },
@@ -1950,7 +1960,7 @@ paths:
             type: integer
             example: 1
           required: true
-      summary: Replace an OVpay token with another (+ transfer products) - V2 (for Integratielaag)
+      summary: "**INTERNAL USE ONLY** Replace an OVpay token with another (+ transfer products) - V2"
       description: |
         Transfer products from one OVpay token to another, and replace the tokens in the database.
         This endpoint is for usage by integratielaag only. Touch points should use 
@@ -2239,11 +2249,6 @@ paths:
                             "contractId": "56B17EF-C436-9043-B76C-481797WEB464F",
                             "_links":
                               {
-                                "self":
-                                  {
-                                    "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens/1/productinstances/1",
-                                    "method": "GET",
-                                  },
                                 "get_order":
                                   {
                                     "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E",
@@ -2403,7 +2408,7 @@ paths:
                         },
                       "_links":
                         {
-                          "transfer_token":
+                          "transfer":
                             {
                               "href": "https://services.dev.api.htm.nl/abt/touchpoint/1.0/customers/tokens/1/transfer",
                               "method": "POST",
@@ -3788,11 +3793,23 @@ components:
                         example: GET
     OvPayTokenProductInstancesResponse:
       type: object
+      required:
+        - productInstances
       properties:
         productInstances:
           type: array
           items:
             type: object
+            required:
+              - productId
+              - name
+              - status
+              - isRenewable
+              - productCategory
+              - fromInclusive
+              - orderId
+              - orderLineId
+              - _links
             properties:
               productId:
                 type: integer
@@ -3854,20 +3871,20 @@ components:
                         example: GET
                   get_order:
                     type: object
+                    description: Always present for any HTM product-instance
                     properties:
                       href:
                         type: string
-                        description: Always present for any HTM product-instance
                         example: https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E
                       method:
                         type: string
                         example: GET
                   get_contract:
                     type: object
+                    description: Only present for subscriptions/contracts
                     properties:
                       href:
                         type: string
-                        description: Only present for subscriptions/contracts
                         example: https://api.integratielaag.nl/abt/touchpoint/1.0/customers/contracts/56B17EF-C436-9043-B76C-481797WEB464F
                       method:
                         type: string

src/openapi/customers/SE-tat-security.yaml

@@ -0,0 +1,341 @@
+openapi: 3.0.1
+info:
+  title: Service Engine APIs for TAT security
+  description: >-
+    Service Engine APIs for TAT security. These are NOT the raw GBO APIs to access TAT security at GBO directly.
+    To be used by touch points to get secure a TAT.
+  version: "2.0"
+servers:
+  - url: https://services.acc.api.htm.nl/abt/touchpoint/2.0
+tags:
+  - name: TAT Security
+paths:
+  /tokens/securetoken:
+    parameters:
+    - name: X-HTM-JWT-AUTH-HEADER
+      in: header
+      schema:
+        type: string
+        example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+      required: false
+      description: The JWT of a customer in case of touchpoint were customer logs in themselves
+    - name: X-HTM-CUSTOMER-PROFILE-ID-HEADER
+      in: header
+      schema:
+        type: integer
+        example: 323
+      required: false
+      description: The id of the customer Profile
+    - name: X-HTM-ROLE-HEADER
+      in: header
+      schema:
+        type: string
+        example: Customer
+      required: false
+      description: The role of the HTM employee in the case of the SMP
+    post:
+      tags:
+        - TAT Security
+      summary: Request additional OV-pas security for a token either in profile or anonymous.
+      description: Request additional OV-pas security for a token either in profile or anonymous
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/SecureTokenRequest"
+            examples:
+              With customer account:
+                value:
+                  ovPayTokenId: 42
+                  emailAddress: stasjo@htm.nl
+              Without customer account:
+                value:
+                  xtat: 62914b49-2c7f-437f-b4b0-2ad61a9f902d
+                  emailAddress: stasjo@htm.nl
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+               $ref: "#/components/schemas/EmailNotPreApprovedResponse"
+              example:
+                uid: 7594f3ee-cd3d-40a3-8e82-73b90d16c481
+                recipient: xxxxxx.user@gmail.com
+                key: 123456789123456789123456789abcde
+                description: OTP Sent
+        "400":
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+              examples:
+                Missing Parameters:
+                  value:
+                    status: 400
+                    title: Missing Mandatory Parameter
+                    detail: Required parameter {0} is missing.
+                Invalid Parameters:
+                  value:
+                    status: 400
+                    title: Invalid Parameter
+                    detail: Required parameter {0} is invalid.
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+              examples:
+                Unauthorized:
+                  value:
+                    status: 401
+                    title: Unauthorized
+                    detail: Invalid Access Token
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+              examples:
+                TAT not found:
+                  value:
+                    status: 404
+                    title: Not Found
+                    detail: TAT Account Not Found
+        "409":
+          description: Conflict
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                TAT Already Secured:
+                  value:
+                    status: 409
+                    title: Conflict
+                    detail: TAT Already Secured
+        "500":
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+              example:
+                error: An unknown error has occurred
+  /tokens/verifyotp:
+    parameters:
+    - name: X-HTM-JWT-AUTH-HEADER
+      in: header
+      schema:
+        type: string
+        example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+      required: false
+      description: The JWT of a customer in case of touchpoint were customer logs in themselves
+    - name: X-HTM-CUSTOMER-PROFILE-ID-HEADER
+      in: header
+      schema:
+        type: integer
+        example: 323
+      required: false
+      description: The id of the customer Profile
+    - name: X-HTM-ROLE-HEADER
+      in: header
+      schema:
+        type: string
+        example: Customer
+      required: false
+      description: The role of the HTM employee in the case of the SMP
+    post:
+      tags:
+        - TAT Security
+      summary: Submit an OTP for a triggered OTP flow.
+      description: |
+        Submit an OTP for a triggered OTP flow. This can either be result of an AGO activation, or
+        result of an AGO authorization flow. Since the backoffice behaves slightly different depending 
+        on which use case is executed, the calling TP needs to provide an `action` in the request body.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/VerifyOtpRequest"
+            examples:
+              OTP verification for TAT security activation for token in customer account:
+                value:
+                  ovPayTokenId: 42
+                  otp: 123456
+                  action: secure
+              OTP verification for TAT security authorization for anonymous token:
+                value:
+                  xtat: 0f0defe8-828c-48e5-97e5-26d1d0179ef0
+                  otp: 123456
+                  action: authorize  
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VerifyOtpResponse'
+              examples:
+                Tat Secured:
+                  value:
+                    status: Success
+                    description: TAT Secured
+                Tat Unsecured:
+                  value:
+                    status: Success
+                    description: TAT Unsecured
+                Tat Authorized:
+                  value:
+                    status: Success
+                    description: TAT Authorized
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+              examples:
+                Missing Parameters:
+                  value:
+                    status: 400
+                    title: Missing Mandatory Parameter
+                    detail: Required parameter {0} is missing.
+                Invalid Parameters:
+                  value:
+                    status: 400
+                    title: Invalid Parameter
+                    detail: Required parameter {0} is invalid.
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+              examples:
+                Unauthorized:
+                  value:
+                    status: 401
+                    title: Unauthorized
+                    detail: Invalid Access Token
+        "500":
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+              example:
+                error: An unknown error has occurred
+components:
+  schemas:
+    unavailable:
+      type: object
+    GenerateTatOutput:
+      type: object
+      properties:
+        uid:
+          type: string
+          description: >-
+            An uid IS A unique identifier THAT is associated with the
+            user.
+        recipient:
+          type: string
+          description: >-
+            A recipient IS A unique identifier THAT is associated with the
+            TAT owner.
+        key:
+          type: string
+          description: >-
+            A key IS a 32 character string THAT uniquely identifies the
+            OTP session.
+    EmailNotPreApprovedResponse:
+      type: object
+      description: >-
+        EmailNotPreApprovedResponse IS AN object THAT represents the response of
+        email pre-approval check.
+      properties:
+        uid:
+          type: string
+          description: A uid IS A unique identifier THAT is associated with the user.
+          example: 7594f3ee-cd3d-40a3-8e82-73b90d16c481
+        recipient:
+          type: string
+          description: >-
+            A recipient IS A unique identifier THAT is associated with the TAT
+            owner.
+          example: xxxxxx.user@gmail.com
+        key:
+          type: string
+          description: >-
+            A key IS a 32 character string THAT uniquely identifies the OTP
+            session.
+          example: 123456789123456789123456789abcde
+        description:
+          type: string
+          description: >-
+            A description IS A string THAT describes the reason why the email is
+            not pre-approved.
+          example: OTP Sent
+    SecureTokenRequest:
+      type: object
+      properties:
+        ovPayTokenId:
+          type: integer
+          example: 42
+        xtat:
+          type: string
+          format: uuid
+          example: 6134db53-9ae5-41d1-a343-36656b60b510
+        emailAddress:
+          type: string
+          format: email
+          example: stasjo@htm.nl
+      required:
+        - ovPayTokenId
+    VerifyOtpRequest:
+      type: object
+      properties:
+        ovPayTokenId:
+          type: integer
+          example: 42
+        xtat:
+          type: string
+          format: uuid
+          example: f3474452-e1d4-428c-b366-e5ad5965eb8c
+        otp:
+          type: string
+          example: 123456
+        action:
+          type: string
+          example: secure
+      required:
+        - otp
+        - action
+    VerifyOtpResponse:
+      type: object
+      properties:
+        status:
+          type: string
+          example: Success
+        description: 
+          type: string
+          example: TAT Secured
+    ErrorResponse:
+      description: Default response when an invalid request has been sent
+      type: object
+      properties:
+        status:
+          type: integer
+          description: >-
+            A status IS An integer that represents the HTTP status code of the
+            response.
+          example: 400
+        title:
+          type: string
+          description: A title IS A string that provides a brief summary of the error.
+        detail:
+          type: string
+          description: A detail IS A string that provides more details about the error.

src/openapi/customers/customers-crud-v2.yaml

@@ -243,7 +243,7 @@ paths:
                           suffix: PhD
                           dateOfBirth: "2002-10-29"
                           emailAddresses: TEST@HTM.NL
-                          isEmailVerified: True
+                          isEmailVerified: false
                           addresses:
                             - addressId: 1
                               street: mystreet
@@ -332,14 +332,6 @@ paths:
                             user: user
                             timestamp: "2023-10-20T17:05:52.000+02:00"
                             correlationId: 01c6d8b4-1cd3-4f9b-85ea-c9adca53ce95
-                        _links:
-                          {
-                            "self":
-                              {
-                                "href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/customers?customerProfileId=1",
-                                "method": "GET",
-                              },
-                          }
                       - customerProfileId: 12
                         customerNumber: 1000002
                         debtorNumber: DB100121
@@ -377,7 +369,7 @@ paths:
                           suffix: PhD
                           dateOfBirth: "2002-10-29"
                           emailAddresses: TEST@HTM.NL
-                          isEmailVerified: False
+                          isEmailVerified: false
                           address:
                             - addressId: 1
                               street: mystreet
@@ -467,32 +459,7 @@ paths:
                             user: user
                             timestamp: "2023-10-20T17:05:52.000+02:00"
                             correlationId: 01c6d8b4-1cd3-4f9b-85ea-c9adca53ce95
-                        _links:
-                          {
-                            "self":
-                              {
-                                "href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/customers?customerProfileId=12",
-                                "method": "GET",
-                              },
-                          }
-                    _links:
-                      {
-                        "self":
-                          {
-                            "href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/customers?offset=20",
-                            "method": "GET",
-                          },
-                        "prev":
-                          {
-                            "href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/customers",
-                            "method": "GET",
-                          },
-                        "next":
-                          {
-                            "href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/customers?offset=40",
-                            "method": "GET",
-                          },
-                      }
+                    href: "https://api.integratielaag.nl/abt/abtcustomers/2.0/customers?offset=20&limit=20"                    
                 getCustomerActive:
                   summary: getCustomerActive
                   description: >-
@@ -526,7 +493,7 @@ paths:
                           suffix: PhD
                           dateOfBirth: "2002-10-29"
                           emailAddresses: TEST@HTM.NL
-                          isEmailVerified: False
+                          isEmailVerified: false
                           addresses:
                             - addressId: 1
                               street: mystreet
@@ -615,22 +582,7 @@ paths:
                             user: user
                             timestamp: "2023-10-20T17:05:52.000+02:00"
                             correlationId: 01c6d8b4-1cd3-4f9b-85ea-c9adca53ce95
-                        _links:
-                          {
-                            "self":
-                              {
-                                "href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/customers?customerProfileId=1",
-                                "method": "GET",
-                              },
-                          }
-                    _links:
-                      {
-                        "self":
-                          {
-                            "href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/customers",
-                            "method": "GET",
-                          },
-                      }
+                    href: https://api.integratielaag.nl/abt/abtcustomers/2.0/customers?offset=20&limit=20    
                 getCustomerBlocked:
                   summary: getCustomerBlocked
                   description: >-
@@ -669,7 +621,7 @@ paths:
                           suffix: PhD
                           dateOfBirth: "2002-10-29"
                           emailAddresses: TEST@HTM.NL
-                          isEmailVerified: True
+                          isEmailVerified: false
                           addresses:
                             - addressId: 1
                               street: mystreet
@@ -758,22 +710,7 @@ paths:
                             user: user
                             timestamp: "2023-10-20T17:05:52.000+02:00"
                             correlationId: 01c6d8b4-1cd3-4f9b-85ea-c9adca53ce95
-                        _links:
-                          {
-                            "self":
-                              {
-                                "href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/customers?customerProfileId=1",
-                                "method": "GET",
-                              },
-                          }
-                    _links:
-                      {
-                        "self":
-                          {
-                            "href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/customers",
-                            "method": "GET",
-                          },
-                      }
+                    href: https://api.integratielaag.nl/abt/abtcustomers/2.0/customers?offset=20&limit=20    
         400:
           description: Bad Request
           content:
@@ -835,7 +772,7 @@ paths:
                     suffix: jr
                     dateOfBirth: "1970-01-01"
                     emailAddress: j.jansen@hatseflats.nl
-                    isEmailVerified: False
+                    isEmailVerified: false
                     addresses:
                       - street: Laan van Meerdervoort
                         houseNumber: 5
@@ -934,7 +871,7 @@ paths:
                       suffix: "jr",
                       dateOfBirth: "1970-01-01",
                       emailAddress: "TEST@TEST1.NL",
-                      isEmailVerified: False
+                      isEmailVerified: false
                     }
               updateCompleteEntity:
                 value:                  
@@ -946,7 +883,7 @@ paths:
                       suffix: "jr",
                       dateOfBirth: "1970-01-01",
                       emailAddress: "TEST@TEST1.NL",
-                      isEmailVerified: True
+                      isEmailVerified: false
                     }
         required: true
       responses:
@@ -1303,7 +1240,6 @@ paths:
           name: externalDeviceId
           schema:
             type: string
-            format: uuid
             example: c5545584-04af-4c60-a955-d6a70baab848
           required: false
           description: The external id of the device.
@@ -1439,13 +1375,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/getDevices"
-              examples:
-                updateDeviceResponse:
-                  value:
-                    deviceId: "5bedce29-af0c-4f3c-b182-2caa8a1f9377"
-                    externalDeviceId: "7122a988-a00a-417d-a5b4-da2d91354976"
-                    alias: "iPhone zakelijk"
+                $ref: "#/components/schemas/patchDeviceResponse"
                       
       security:
         - default: []
@@ -1608,24 +1538,7 @@ paths:
                         "replacedByTokenId": 12,
                       },
                     ],
-                  "_links":
-                    {
-                      "self":
-                        {
-                          "href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/ovPayTokens?offset=20",
-                          "method": "GET",
-                        },
-                      "prev":
-                        {
-                          "href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/ovPayTokens",
-                          "method": "GET",
-                        },
-                      "next":
-                        {
-                          "href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/ovPayTokens?offset=40",
-                          "method": "GET",
-                        },
-                    },
+                  "href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/ovPayTokens?offset=20&limit=20"
                 }
   /customers/{customerProfileId}/ovpaytokens:
     post:
@@ -1944,9 +1857,10 @@ paths:
                             "created": "2024-10-20T17:05:52.000",
                           },
                         ],
+                        "href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/billingInformations?offset=20&limit=20"
                     }
                 getBillingInformationSingleSpecificCustomer:
-                  summary: Get singel billing information entity for a specific customers
+                  summary: Get single billing information entity for a specific customers
                   description: >-
                     Found one billing information matching the search parameters
                   value:
@@ -2136,59 +2050,7 @@ paths:
                             "updateTimestamp": "2024-03-22T08:55:00",
                           },
                         ],
-                      "_links":
-                        {
-                          "self":
-                            {
-                              "href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/directdebitmandates",
-                              "method": "GET",
-                            },
-                          "next":
-                            {
-                              "href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/directdebitmandates?offset=20",
-                              "method": "GET",
-                            },
-                        },
-                    }
-                getDirectDebitMandateWithNextPageandPreviousPage:
-                  value:
-                    {
-                      "directDebitMandates":
-                        [
-                          {
-                            "directDebitMandateId": 71,
-                            "customerProfileId": 12,
-                            "billingInformationId": 51,
-                            "directDebitMandateType":
-                              {
-                                "directDebitMandateTypeId": 1,
-                                "name": "import",
-                                "description": "import",
-                              },
-                            "created": "2024-03-22T08:55:00",
-                            "mandateReference": "CORE01",
-                            "mandateState": "SIGNED",
-                            "updateTimestamp": "2024-03-22T08:55:00",
-                          },
-                        ],
-                      "_links":
-                        {
-                          "self":
-                            {
-                              "href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/directdebitmandates?offset=20",
-                              "method": "GET",
-                            },
-                          "prev":
-                            {
-                              "href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/directdebitmandates",
-                              "method": "GET",
-                            },
-                          "next":
-                            {
-                              "href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/directdebitmandates?offset=40",
-                              "method": "GET",
-                            },
-                        },
+                      "href": "https://api.integratielaag.nl/abt/abtcustomers/2.0/directdebitmandates?offset=20&limit=20"
                     }
   /billingInformation/{billingInformationId}/directdebitmandates:
     post:
@@ -2480,7 +2342,6 @@ components:
           format: uuid
         externalDeviceId:
           type: string
-          format: uuid
         alias:
           type: string
       required:
@@ -2599,7 +2460,6 @@ components:
       properties:
         externalDeviceId:
           type: string
-          format: uuid
         alias:
           type: string
     defaultCustomerProfileResponse:
@@ -2846,7 +2706,7 @@ components:
         emailAddress:
           type: string
         isEmailVerified:
-          type: string
+          type: boolean
     postOvPayTokenResponse:
       type: object
       properties:
@@ -2860,6 +2720,14 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/getDeviceEntity"
+    patchDeviceResponse:
+      type: object
+      properties:
+        deviceId:
+          type: string
+          format: uuid
+          example: "b2c8a8c6-3d1c-4b6b-8f8d-3a6a1b6a1b6a"
+        
     getDeviceEntity:
       type: object
       properties:
@@ -2870,7 +2738,6 @@ components:
           type: integer
         externalDeviceId:
           type: string
-          format: uuid
         alias:
           type: string
       required:

src/openapi/customers/customers_reference-crud.yaml

@@ -417,38 +417,56 @@ paths:
               example:
                 Entries:
                   phoneTypes:
-                    - name: mobile
+                    - name: Mobiel
                       id: 1
-                    - name: fixed line
+                    - name: Thuis
                       id: 2
+                    - name: Ouders
+                      id: 3
+                    - name: Bewindvoerder
+                      id: 4
+                    - name: Home
+                      id: 5
+                    - name: Mobile
+                      id: 6
+                    - name: Work
+                      id: 7
+                    - name: Noodtelefoon
+                      id: 8
                   addressTypes:
-                    - name: home
+                    - name: Shipping
                       id: 1
-                    - name: office
+                    - name: Billing
                       id: 2
                   customerStatuses:
-                    - name: active
+                    - name: Inactive
                       id: 1
-                    - name: blocked
+                    - name: Active
                       id: 2
-                    - name: inactive
+                    - name: Blocked
                       id: 3
-                    - name: new
+                    - name: Frozen
                       id: 4
+                    - name: Cleared
+                      id: 5
                   tokenTypes:
-                    - name: Debit card
+                    - name: EMV
                       id: 1
-                    - name: Credit card
-                      id: 2
                     - name: OVPas physical
-                      id: 3
+                      id: 2
                     - name: OVPas digital
-                      id: 4
+                      id: 3
                   directDebitMandateTypes:
                     - name: Paper Contract
                       id: 1
                     - name: PIN transaction
                       id: 2
+                    - name: SEPA eMandate
+                      id: 3
+                    - name: Digital signature
+                      id: 4
+                    - name: IDEAL transaction
+                      id: 5
                   tokenStatuses:
                     - name: Expired
                       id: 1

src/openapi/fiko/fiko-crud.yaml

@@ -2999,8 +2999,12 @@ paths:
                   transactionItems:
                   - transactionItemId: d8ee7035-fa3d-400e-9ad5-4fe8c4c73eb7
                     status: returned to src
+                    aggregationReference: null
+                    accountingSystemReference: null
                   - transactionItemId: 88910e83-4b1e-4fde-ab13-bd8bb60cbcd3
                     status: returned to src
+                    aggregationReference: null
+                    accountingSystemReference: null
               List of transactions items to return:
                 summary: List of transaction items to return to transaction database
                 description: List of transaction items to return to transaction database in bulk.
@@ -3008,8 +3012,12 @@ paths:
                   transactionItems:
                   - transactionItemId: eacb9bdc-c6b5-4277-942b-cebb102944f5
                     status: returned to trx-db
+                    aggregationReference: null
+                    accountingSystemReference: null
                   - transactionItemId: 2f361bfb-9df0-4e0f-af7c-7b9be3e7bc61
                     status: returned to trx-db
+                    aggregationReference: null
+                    accountingSystemReference: null
       responses:
         "202":
           description: Accepted
@@ -3061,10 +3069,32 @@ paths:
                     Body of a batch of transaction items that was successfully patched. 
                     A number of transaction items were patched.
                   value:
+                    startTime: 2025-02-14T05:32:47.067Z
+                    status: Finished
+                    clientTrackingId: 08584620957189579629541919368CU00
                     summary:
                       created: 0
                       updated: 15
                       total: 15
+        "202":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GetResponseStatus"
+              examples:
+                Batch is still being processed:
+                  summary: Batch is still being processed
+                  description: |
+                    Batch is still being processed
+                  value:
+                    startTime: 2025-02-14T05:32:47.067Z
+                    status: Running
+                    clientTrackingId: 08584620957189579629541919368CU00
+                    summary:
+                      created: 0
+                      updated: 0
+                      total: 0
       security:
         - default: []
       x-auth-type: Application & Application User
@@ -3089,8 +3119,10 @@ paths:
                   processingFailures:
                   - processingFailureId: d8ee7035-fa3d-400e-9ad5-4fe8c4c73eb7
                     resolved: true
+                    change: Configuratie aangepast voor artikelnummer 1337.
                   - processingFailureId: 88910e83-4b1e-4fde-ab13-bd8bb60cbcd3
                     resolved: true
+                    change: Configuratie aangepast voor artikelnummer 1337.
       responses:
         "202":
           description: Accepted
@@ -3142,10 +3174,32 @@ paths:
                     Body of a batch of processing failures that was successfully patched. 
                     A number of processing failures were patched.
                   value:
+                    startTime: 2025-02-14T05:32:47.067Z
+                    status: Finished
+                    clientTrackingId: 08584620957189579629541919368CU00
                     summary:
                       created: 0
                       updated: 15
                       total: 15
+        "202":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GetResponseStatus"
+              examples:
+                Batch is still being processed:
+                  summary: Batch is still being processed
+                  description: |
+                    Batch is still being processed
+                  value:
+                    startTime: 2025-02-14T05:32:47.067Z
+                    status: Running
+                    clientTrackingId: 08584620957189579629541919368CU00
+                    summary:
+                      created: 0
+                      updated: 0
+                      total: 0
       security:
         - default: []
       x-auth-type: Application & Application User

src/openapi/orders/orders-crud.yaml

@@ -5,6 +5,12 @@ info:
   description: CRUD APIs for ABT Orders database. These are NOT the functional APIs from Service Engine.
 servers:
   - url: https://services.acc.api.htm.nl/abt/abtorder/1.0
+tags:
+ - name: Order
+ - name: Order Line
+ - name: Payment
+ - name: Customer
+ - name: Order Voucher
 paths:
   /orders:
     get:
@@ -50,6 +56,13 @@ paths:
             example: 1
           required: false
           description: The id of the touch point where the order was initiated.
+        - in: query
+          name: externalDeviceId
+          schema:
+            type: string
+            example: "7a28bd54-7ca9-499a-a722-d15ab858ab99"
+          required: false
+          description: The external id of the device used to place the order.
         - in: query
           name: languageId
           schema:
@@ -119,6 +132,7 @@ paths:
                           "touchPointId": 1,
                           "name": "Perplex"
                         },
+                        "externalDeviceId": "42e77532-d831-41da-b07a-7edb9bb7f004",
                         "language":
                           {
                             "languageId": 1,
@@ -148,6 +162,30 @@ paths:
                               "description": "Betaling in behandeling",
                             },
                           ],
+                        "orderVouchers": [
+                          {
+                            "orderVoucherId": "399bd3b3-9721-4f09-a936-d64637de1621",
+                            "issuedVoucher":{
+                              "issuedVoucherId": "a0996218-bc5e-4826-9020-cda98a32838d",
+                              "voucherCode": "Voucher1234",
+                              "purchasedProductId": 31,
+                              "fromInclusive": "2025-03-22T08:55:00",
+                              "untillInclusive": "2026-03-22T08:55:00"
+                            },
+                            "orderLineId": null
+                          },
+                          {
+                            "orderVoucherId": "f6c7ac42-1811-4e4d-82af-53e18fe16110",
+                            "issuedVoucher":{
+                              "issuedVoucherId": "54668baf-4905-4e9a-af02-09c170f295ed",
+                              "voucherCode": "Voucher124",
+                              "purchasedProductId": 35,
+                              "fromInclusive": "2025-03-22T08:55:00",
+                              "untillInclusive": "2026-03-22T08:55:00"
+                            },
+                            "orderLineId": "7a7a9d1a-3fc8-4058-a28b-082860aaa311"
+                          }
+                        ],
                         "orderLines":
                           [
                             {
@@ -277,7 +315,7 @@ paths:
                                 {
                                   "orderCustomerAddressId": "aa50047c-58ac-4f15-9448-ee000dfc6893",
                                   "addressType":
-                                    { "addressTypeId": 3, "name": "Billing" },
+                                    { "addressTypeId": 2, "name": "Billing" },
                                   "street": "Kon. Julianaplein",
                                   "houseNumber": 10,
                                   "houseNumberSuffix": "a",
@@ -327,19 +365,22 @@ paths:
                   "customerProfileId": 1337,
                   "totalAmount": 121,
                   "touchPointId": 1,
+                  "externalDeviceId": "b8ca9fdf-0bb9-4e49-b48d-41e395563377",
                   "languageId": 1,
                   "createdOn": "2024-03-22T09:00:00",
                   "order_OrderStatus":
                     [
                       {
-                        "orderStatusId": 4,
-                        "createdOn": "2024-03-22T09:00:00",
-                        "description": "Order succesvol betaald",
-                      },
-                      {
-                        "orderStatusId": 3,
+                        "orderStatusId": 1,
                         "createdOn": "2024-03-22T08:55:00",
-                        "description": "Betaling in behandeling",
+                        "description": "Concept order",
+                      },
+                    ],
+                    "orderVouchers":
+                    [
+                      {
+                        "issuedVoucherId": "e81b2197-a6c2-45b6-9560-8ce8442e8604",
+                        "orderLineId": "97824d2e-5189-456d-b6da-4cca511a7685"
                       },
                     ],  
                   "orderLines":
@@ -390,57 +431,6 @@ paths:
                           ],
                       },
                     ],
-                  "payments":
-                    [
-                      {
-                        "createdOn": "2024-03-22T09:00:00",
-                        "amountDebit": 121,
-                        "paymentMethodId": 1,
-                        "touchPointId": 1,
-                        "isRefund": false,
-                        "htmPaymentReference": "HTM-1234",
-                        "pspPaymentReference": "Buckaroo-1234",
-                        "paymentStatuses":
-                          [
-                            {
-                              "createdOn": "2024-03-22T09:00:00",
-                              "statusCode": "190",
-                              "statusDescription": "Success",
-                              "statusSubCode": "S001",
-                              "statusSubDescription": "PaymentSuccessFul",
-                            },
-                          ],
-                        "mandateInput":
-                          {
-                            "directDebitMandateTypeId": 1,
-                            "createdOn": "2024-03-22T09:00:00",
-                            "bic": "RABONL2U",
-                            "iban": "NL44RABO0123456789",
-                            "ascription": "J. de Vries",
-                            "place": "Den Haag",
-                          },
-                      },
-                    ],
-                  "orderCustomer":
-                    {
-                      "birthname": "Jan",
-                      "surname": "Vries",
-                      "prefix": "de",
-                      "emailAddress": "jandevries@outlook.com",
-                      "dateOfBirth": "1970-01-01",
-                      "orderCustomerAddresses":
-                        [
-                          {
-                            "addressTypeId": 1,
-                            "street": "Kon. Julianaplein",
-                            "houseNumber": 10,
-                            "houseNumberSuffix": "a",
-                            "postalCode": "2595 AA",
-                            "city": "Den Haag",
-                            "country": "NL",
-                          },
-                        ],
-                    },
                 }
       responses:
         "201":
@@ -487,6 +477,7 @@ paths:
                     "touchPointId": 1,
                     "name": "Perplex"
                    },
+                   "externalDeviceId": null,
                   "language":
                     {
                       "languageId": 1,
@@ -512,6 +503,7 @@ paths:
                         "description": "Betaling in behandeling",
                       },
                     ],
+                  "orderVouchers": null,
                   "orderLines":
                     [
                       {
@@ -634,7 +626,7 @@ paths:
                           {
                             "orderCustomerAddressId": "aa50047c-58ac-4f15-9448-ee000dfc6893",
                             "addressType":
-                              { "addressTypeId": 3, "name": "Billing" },
+                              { "addressTypeId": 2, "name": "Billing" },
                             "street": "Kon. Julianaplein",
                             "houseNumber": 10,
                             "houseNumberSuffix": "a",
@@ -658,6 +650,7 @@ paths:
             example:
               {
                 "customerProfileId": 1337,
+                "externalDeviceId": "fe68e624-b75f-48ca-a179-d5f86a8ab7d5",
                 "totalAmount": 121,
                 "languageId": 1,
                 "lastUpdatedOn": "2024-03-22T09:00:00",
@@ -678,6 +671,7 @@ paths:
       responses:
         "200":
           description: OK
+ 
   /orders/{orderId}/statuses:
     parameters:
       - in: path
@@ -715,6 +709,143 @@ paths:
                 {
                   "order_orderStatusId": "b9cf0096-4211-4be6-ac21-7bc34bc8e066",
                 }
+  /orders/{orderId}/ordervouchers:
+    parameters:
+      - in: path
+        name: orderId
+        schema:
+          type: string
+          format: uuid
+          example: d1dd439b-6072-4b97-89c9-724268865b93
+        required: true
+        description: The id of the order to process.
+    post:
+      summary: Add an order voucher.
+      description: Add an order voucher.
+      tags:
+        - Order Voucher
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/unavailable"
+            example:
+              {
+                "issuedVoucherId": "eec6af41-1a60-49f6-a92e-440054a92f13",
+                "orderLineId": "7a9d6e15-7c5c-421d-9ea9-00b9bb6dbe67"
+              }
+      responses:
+        "201":
+          description: Created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/unavailable"
+              example:
+                {
+                  "orderVoucherId": "b9cf0096-4211-4be6-ac21-7bc34bc8e066",
+                }
+  /ordervouchers:
+    parameters:
+      - in: query
+        name: orderVoucherId
+        schema:
+          type: string
+          format: uuid
+          example: d1dd439b-6072-4b97-89c9-724268865b93
+        required: false
+        description: The id of the orderVoucher you are looking for.
+      - in: query
+        name: orderId
+        schema:
+          type: string
+          example: 90c926b9-3178-4757-acca-34cff66b980c
+        required: false
+        description: The id of the order
+      - in: query
+        name: orderLineId
+        schema:
+          type: string
+          example: 9e3363c8-e776-4675-b108-99b8c2e38eb6
+        required: false
+        description: The id of the orderLine
+    get:
+      summary: Find vouchers on the order
+      description: Find vouchers on the order
+      tags:
+        - Order Voucher
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/unavailable"
+              example:
+                 [
+                  {
+                    "orderVoucherId": "19ef6882-8eda-43bf-b48e-9b4ff8745a50",
+                    "issuedVoucher":{
+                        "issuedVoucherId": "54668baf-4905-4e9a-af02-09c170f295ed",
+                        "voucherCode": "Voucher124",
+                        "purchasedProductId": 35,
+                        "fromInclusive": "2025-03-22T08:55:00",
+                        "untillInclusive": "2026-03-22T08:55:00"
+                    },
+                    "orderId": "f59e4769-53a0-4156-8991-6f9119ba629f",
+                    "orderLineId": "eeb86071-4f59-405d-b2be-7d7a77044bfa"
+                  }
+                ]
+  /ordervouchers/{ordervoucherId}:
+    parameters:
+      - in: path
+        name: ordervoucherId
+        schema:
+          type: string
+          format: uuid
+          example: d1dd439b-6072-4b97-89c9-724268865b93
+        required: true
+        description: The id of the order to process.
+    patch:
+      summary: Update an order voucher.
+      description: Update an order voucher.
+      tags:
+        - Order Voucher
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/unavailable"
+            example:
+              {
+                "issuedVoucherId": "eec6af41-1a60-49f6-a92e-440054a92f13",
+                "orderLineId": "7a9d6e15-7c5c-421d-9ea9-00b9bb6dbe67"
+              }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/unavailable"
+              example:
+                {
+                  "orderVoucherId": "b9cf0096-4211-4be6-ac21-7bc34bc8e066",
+                }
+    delete:
+      summary: Delete an order voucher.
+      description: Delete an order voucher.
+      tags:
+        - Order Voucher
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/unavailable"
+              example:
+                {}
   /orders/{orderId}/orderlines:
     parameters:
       - in: path
@@ -820,7 +951,7 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/unavailable"
-            example:
+            examples:
               Minimum orderline requestBody:
                 value:
                   {
@@ -906,7 +1037,7 @@ paths:
                     "orderCustomerAddresses":
                       [
                         {
-                          "addressTypeId": 3,
+                          "addressTypeId": 2,
                           "street": "Kon. Julianaplein",
                           "houseNumber": 10,
                           "houseNumberSuffix": "a",
@@ -2187,7 +2318,7 @@ paths:
                         {
                           "orderCustomerAddressId": "aa50047c-58ac-4f15-9448-ee000dfc6893",
                           "addressType":
-                            { "addressTypeId": 3, "name": "Billing" },
+                            { "addressTypeId": 2, "name": "Billing" },
                           "street": "Kon. Julianaplein",
                           "houseNumber": 10,
                           "houseNumberSuffix": "a",
@@ -2257,7 +2388,7 @@ paths:
               $ref: "#/components/schemas/unavailable"
             example:
               {
-                "addressTypeId": 3,
+                "addressTypeId": 2,
                 "street": "Kon. Julianaplein",
                 "houseNumber": 10,
                 "houseNumberSuffix": "a",
@@ -2307,7 +2438,7 @@ paths:
               type: integer
           explode: false
           required: false
-          description: Filter on possible types of addresses. 1 = Shipping, 3 = Billing.
+          description: Filter on possible types of addresses. 1 = Shipping, 2 = Billing.
         - in: query
           name: street
           schema:
@@ -2363,7 +2494,7 @@ paths:
                     "orderCustomerAddressId": "aa50047c-58ac-4f15-9448-ee000dfc6893",
                     "orderCustomerId": "540d8b7a-d626-443f-8f99-c24398604d7a",
                     "orderId": "73cca95a-81d1-468f-a8bf-99b36367001a",
-                    "addressType": { "addressTypeId": 3, "name": "Billing" },
+                    "addressType": { "addressTypeId": 2, "name": "Billing" },
                     "street": "Kon. Julianaplein",
                     "houseNumber": 10,
                     "houseNumberSuffix": "a",

src/openapi/products/SE-products-SE.yaml

@@ -313,6 +313,7 @@ paths:
                     {
                       "productId": 24,
                       "parentProductId": null,
+                      "needsVoucher": false,
                       "layerInfo": null,
                       "fikoArticleNumber": "1234",
                       "gboPackageTemplateId": "30901",
@@ -429,6 +430,7 @@ paths:
                     {
                       "productId": 126,
                       "parentProductId": null,
+                      "needsVoucher": false,
                       "layerInfo": {
                         "layerInfoId": 1,
                         "choiceKey": "isRenewable",
@@ -537,6 +539,7 @@ paths:
                           {
                             "productId": 119,
                             "parentProductId": 126,
+                            "needsVoucher": false,
                             "layerInfo": null,
                             "fikoArticleNumber": "1234",
                             "gboPackageTemplateId": "30001",
@@ -652,6 +655,7 @@ paths:
                           {
                             "productId": 120,
                             "parentProductId": 126,
+                            "needsVoucher": false,
                             "layerInfo": null,
                             "fikoArticleNumber": "1234",
                             "gboPackageTemplateId": "30001",
@@ -779,6 +783,7 @@ paths:
                     {
                       "productId": 49,
                       "parentProductId": null,
+                      "needsVoucher": false,
                       "layerInfo": {
                         "layerInfoId": 2,
                         "choiceKey": "regio",
@@ -926,6 +931,7 @@ paths:
                           {
                             "productId": 109,
                             "parentProductId": 49,
+                            "needsVoucher": false,
                             "layerInfo": {
                               "layerInfoId": 3,
                               "choiceKey": "allowedGboAgeProfiles",
@@ -1076,6 +1082,7 @@ paths:
                                 {
                                   "productId": 114,
                                   "parentProductId": 109,
+                                  "needsVoucher": false,
                                   "layerInfo": {
                                     "layerInfoId": 1,
                                     "choiceKey": "isRenewable",
@@ -1226,6 +1233,7 @@ paths:
                                 {
                                   "productId": 115,
                                   "parentProductId": 109,
+                                  "needsVoucher": false,
                                   "layerInfo": {
                                     "layerInfoId": 1,
                                     "choiceKey": "isRenewable",
@@ -1377,6 +1385,7 @@ paths:
                                       {
                                         "productId": 116,
                                         "parentProductId": 115,
+                                        "needsVoucher": false,
                                         "layerInfo": null,
                                         "fikoArticleNumber": "1234",
                                         "gboPackageTemplateId": "33615",
@@ -1526,6 +1535,7 @@ paths:
                                       {
                                         "productId": 117,
                                         "parentProductId": 115,
+                                        "needsVoucher": false,
                                         "layerInfo": null,
                                         "fikoArticleNumber": "1234",
                                         "gboPackageTemplateId": "33615",
@@ -1679,6 +1689,7 @@ paths:
                           {
                             "productId": 112,
                             "parentProductId": 49,
+                            "needsVoucher": false,
                             "layerInfo": {
                               "layerInfoId": 3,
                               "choiceKey": "allowedGboAgeProfiles",
@@ -2150,6 +2161,10 @@ components:
         parentProductId:
           type: integer
           example: 1
+        needsVoucher:
+          type: boolean
+          description: Indicates if the product needs a voucher (with this productId as requiredProductId) to be bought - if false, this is optional, but still allowed
+          example: false
         layerInfo:
           $ref: '#/components/schemas/LayerInfoResponse'
         fikoArticleNumber:

src/openapi/products/SE-products-TP.yaml

@@ -313,6 +313,7 @@ paths:
                     {
                       "productId": 24,
                       "parentProductId": null,
+                      "needsVoucher": false,
                       "layerInfo": null,
                       "fikoArticleNumber": "1234",
                       "gboPackageTemplateId": "30901",
@@ -429,6 +430,7 @@ paths:
                     {
                       "productId": 126,
                       "parentProductId": null,
+                      "needsVoucher": false,
                       "layerInfo": {
                         "layerInfoId": 1,
                         "choiceKey": "isRenewable",
@@ -537,6 +539,7 @@ paths:
                           {
                             "productId": 119,
                             "parentProductId": 126,
+                            "needsVoucher": false,
                             "layerInfo": null,
                             "fikoArticleNumber": "1234",
                             "gboPackageTemplateId": "30001",
@@ -652,6 +655,7 @@ paths:
                           {
                             "productId": 120,
                             "parentProductId": 126,
+                            "needsVoucher": false,
                             "layerInfo": null,
                             "fikoArticleNumber": "1234",
                             "gboPackageTemplateId": "30001",
@@ -779,6 +783,7 @@ paths:
                     {
                       "productId": 49,
                       "parentProductId": null,
+                      "needsVoucher": false,
                       "layerInfo": {
                         "layerInfoId": 2,
                         "choiceKey": "regio",
@@ -926,6 +931,7 @@ paths:
                           {
                             "productId": 109,
                             "parentProductId": 49,
+                            "needsVoucher": false,
                             "layerInfo": {
                               "layerInfoId": 3,
                               "choiceKey": "allowedGboAgeProfiles",
@@ -1076,6 +1082,7 @@ paths:
                                 {
                                   "productId": 114,
                                   "parentProductId": 109,
+                                  "needsVoucher": false,
                                   "layerInfo": {
                                     "layerInfoId": 1,
                                     "choiceKey": "isRenewable",
@@ -1226,6 +1233,7 @@ paths:
                                 {
                                   "productId": 115,
                                   "parentProductId": 109,
+                                  "needsVoucher": false,
                                   "layerInfo": {
                                     "layerInfoId": 1,
                                     "choiceKey": "isRenewable",
@@ -1377,6 +1385,7 @@ paths:
                                       {
                                         "productId": 116,
                                         "parentProductId": 115,
+                                        "needsVoucher": false,
                                         "layerInfo": null,
                                         "fikoArticleNumber": "1234",
                                         "gboPackageTemplateId": "33615",
@@ -1526,6 +1535,7 @@ paths:
                                       {
                                         "productId": 117,
                                         "parentProductId": 115,
+                                        "needsVoucher": false,
                                         "layerInfo": null,
                                         "fikoArticleNumber": "1234",
                                         "gboPackageTemplateId": "33615",
@@ -1679,6 +1689,7 @@ paths:
                           {
                             "productId": 112,
                             "parentProductId": 49,
+                            "needsVoucher": false,
                             "layerInfo": {
                               "layerInfoId": 3,
                               "choiceKey": "allowedGboAgeProfiles",
@@ -2150,6 +2161,10 @@ components:
         parentProductId:
           type: integer
           example: 1
+        needsVoucher:
+          type: boolean
+          description: Indicates if the product needs a voucher (with this productId as requiredProductId) to be bought - if false, this is optional, but still allowed
+          example: false
         layerInfo:
           $ref: '#/components/schemas/LayerInfoResponse'
         fikoArticleNumber:

src/openapi/products/SE-vouchers-TP.yaml

@@ -0,0 +1,400 @@
+openapi: 3.0.1
+info:
+  title: Service Engine APIs for HTM voucher for sales Touchpoint
+  description: Service Engine APIs for HTM vouchers. These are NOT the CRUD APIs to the data hub. These ARE the APIs for sales touchpoints.
+  version: "1.0"
+servers:
+  - url: https://services.acc.api.htm.nl/abt/abtvouchersTouchpoint/1.0
+paths:
+  /issuedvouchers/{voucherCode}:
+    get:
+      summary: Get details of a voucher, that was issued for a specific touchpoint
+      description:
+        Get details of an issued voucher for a specific touchpoint. This means that only products that the calling touchpoint is allowed to see or sell
+        (i.e. has active sellingPeriods for touchPointId of the calling touchpoint) are returned.
+      parameters:
+        - name: voucherCode
+          in: path
+          required: true
+          description: The unique code of the issued voucher to retrieve.
+          schema:
+            type: string
+            example: VOUCHER123
+      tags:
+        - Vouchers
+      responses:
+        "200":
+          description: Successful retrieval of voucher instance
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/salesTouchpointIssuedVoucherResponse"
+              examples:
+                Voucher that grants a voucher-only product for free:
+                  summary: Voucher that grants a voucher-only product for free
+                  description: |-
+                    Voucher that grants a product (that can only be acquired via a voucher) for free.
+                    In this case, the voucher has an amountInclTax of 0. If the requiredProduct has a
+                    non-zero sellingPrice (amountInclTax), the difference between sellingPrice and 
+                    voucher amountInclTax represents the granted discount. If the requiredProduct has 
+                    a sellingPrice of 0, no "discount" is shown; just the voucher's amountInclTax.
+                  value:
+                    {
+                      "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
+                      "voucherCode": "HTM-A7J-128-PYT",
+                      "fromInclusive": "2024-10-04T00:00:00.000",
+                      "untilInclusive": "2024-11-04T00:00:00.000",
+                      "voucherStatus": { "voucherStatusId": 2, "name": "issued" },
+                      "product":
+                        {
+                          "productId": 263,
+                          "productName": "Voucher Ooievaarspas-product AOW",
+                          "productDescription": "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": 0,
+                          "requiredProducts":
+                            [
+                              {
+                                "productId": 982,
+                                "productName": "Ooievaarspas voor AOW-ers in Den Haag",
+                                "productDescription": "Vrij reizen bij HTM voor Haagse AOW-gerechtigden met een Ooievaarspas.",
+                                "productCategory": 
+                                  {
+                                    "productCategoryId": 2,
+                                    "isTravelProduct": true,
+                                    "name": "Afgekocht reisrecht",
+                                  },
+                                "amountInclTax": 0,
+                                "_links":
+                                  {
+                                    "get_details":
+                                      {
+                                        "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/982",
+                                        "method": "GET",
+                                      },
+                                  },
+                              },
+                            ]
+                        },
+                      "mandatoryCustomerDataItems":
+                        [
+                          {
+                            "mandatoryCustomerDataItemId": 8,
+                            "customerDataItem": "padBirthDate"
+                          }
+                        ]
+                    }
+                Voucher that grants a hybrid product for a reduced price:
+                  summary: Voucher that grants a hybrid product for a reduced price
+                  description: |-
+                    Voucher that grants a hybrid product (that can be acquired via voucher or via ordinary order flow) 
+                    for a reduced price. In this case, the voucher has an amountInclTax > 0, which dictates the (modified) 
+                    total amount that needs to be paid for said product. If the requiredProduct has a 
+                    non-zero sellingPrice (amountInclTax), the difference between sellingPrice and 
+                    voucher amountInclTax represents the granted discount. If the requiredProduct has 
+                    a sellingPrice of 0, no "discount" is shown; just the voucher's amountInclTax./
+                    Specifically, in this example, the product "HTM 20% Korting" can be purchased for 1 euro instead of 5 euro.
+                  value:
+                    {
+                      "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
+                      "voucherCode": "HTM-A7J-128-PYT",
+                      "fromInclusive": "2024-10-04T00:00:00.000",
+                      "untilInclusive": "2024-11-04T00:00:00.000",
+                      "voucherStatus": { "voucherStatusId": 2, "name": "issued" },
+                      "product":
+                        {
+                          "productId": 264,
+                          "productName": "Kortingsvoucher HTM 20% Korting ",
+                          "productDescription": "Voucher waarmee het product \"HTM 20% Korting\" voor een lagere prijs kan worden aangeschaft.",
+                          "amountInclTax": 100,
+                          "requiredProducts":
+                            [
+                              {
+                                "productId": 984,
+                                "productName": "HTM 20% Korting",
+                                "productDescription": "Reis met 20% korting op je betaalpas bij HTM.",
+                                "productCategory": 
+                                  {
+                                    "productCategoryId": 1,
+                                    "isTravelProduct": true,
+                                    "name": "Kortingsabonnement",
+                                  },
+                                "amountInclTax": 500,
+                                "_links":
+                                  {
+                                    "get_details":
+                                      {
+                                        "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/products/984",
+                                        "method": "GET",
+                                      },
+                                  },
+                              },
+                            ]
+                        },
+                      "mandatoryCustomerDataItems": []
+                    }
+                Voucher that grants a discount for a whole order:
+                  summary: Voucher that grants a discount for a whole order
+                  description: |-
+                    Voucher that grants a discount for a whole order. In this case, no requiredProduct is specified, and 
+                    the voucher has an amountInclTax < 0. 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).
+                  value:
+                    {
+                      "issuedVoucherId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
+                      "voucherCode": "HTM-A7J-128-PYT",
+                      "fromInclusive": "2024-10-04T00:00:00.000",
+                      "untilInclusive": "2024-11-04T00:00:00.000",
+                      "voucherStatus": { "voucherStatusId": 2, "name": "issued" },
+                      "product":
+                        {
+                          "productId": 265,
+                          "productName": "Voucher 10 euro korting",
+                          "productDescription": "Voucher die 10 euro korting geeft op je gehele winkelmand.",
+                          "amountInclTax": -1000,
+                          "requiredProducts": []
+                        },
+                      "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",
+                    }
+        "400":
+          description: Bad request
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/rfc9457"
+              examples:
+                Invalid voucher code:
+                  summary: Invalid voucher code
+                  value:
+                    {
+                      "type": "https://example.com/probs/bad-request",
+                      "title": "Invalid voucher code",
+                      "detail": "No valid voucher found for code VOUCHER123.",
+                      "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:
+    salesTouchpointIssuedVoucherResponse:
+      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-offset
+          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+02:00"
+        untilInclusive:
+          type: string
+          format: date-time-offset
+          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+01:00"
+        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 (modified) 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:
+      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

src/openapi/products/productreference-crud.yaml

@@ -1553,6 +1553,9 @@ components:
         - productCategoryId: 8
           name: Saldo
           isTravelProduct: true
+        - productCategoryId: 9
+          name: Voucher
+          isTravelProduct: false
       type: array
       items:
         $ref: '#/components/schemas/productCategoryGetEntity'    
@@ -1811,7 +1814,7 @@ components:
         - mandatoryCustomerDataItemId: 5
           customerDataItem: address
         - mandatoryCustomerDataItemId: 6
-          customerDataItem: phone
+          customerDataItem: voucher
         - mandatoryCustomerDataItemId: 7
           customerDataItem: ovPayToken
         - mandatoryCustomerDataItemId: 8
@@ -1820,6 +1823,8 @@ components:
           customerDataItem: shippingAddress
         - mandatoryCustomerDataItemId: 10
           customerDataItem: billingAddress
+        - mandatoryCustomerDataItemId: 11
+          customerDataItem: startDate
       items:
         $ref: '#/components/schemas/mandatoryCustomerDataItemGetEntity'
       type: array

src/openapi/products/products-crud.yaml

@@ -46,6 +46,13 @@ paths:
             when false, return only non-archived products (isArchived = false).
           schema:
             type: boolean
+        - name: onlyVouchers
+          in: query
+          required: false
+          description: |-
+            When omitted, defaults to false (i.e. return all normal products that are NOT voucher definitions); when true, return only voucher definitions
+          schema:
+            type: boolean
       responses:
         '200':
           description: OK
@@ -387,6 +394,7 @@ paths:
                     "fikoArticleNumber": "1234",
                     "isValid": true,
                     "isArchived": false,
+                    "needsVoucher": false,
                     "gboPackageTemplateId": "30901",
                     "productName": "HTM pilot 90% korting",
                     "productDescription": "Reis met 90% korting gedurende de eerste F&F pilot!",
@@ -474,6 +482,7 @@ paths:
                     "fikoArticleNumber": "1234",
                     "isValid": true,
                     "isArchived": false,
+                    "needsVoucher": false,
                     "gboPackageTemplateId": "30901",
                     "productName": "HTM pilot 90% korting",
                     "productDescription": "Reis met 90% korting gedurende de eerste F&F pilot!",
@@ -560,6 +569,7 @@ paths:
                     "fikoArticleNumber": "1234",
                     "isValid": true,
                     "isArchived": false,
+                    "needsVoucher": false,
                     "gboPackageTemplateId": "30901",
                     "productName": "HTM pilot 90% korting",
                     "productDescription": "Reis met 90% korting gedurende de eerste F&F pilot!",
@@ -680,6 +690,7 @@ paths:
                     "fikoArticleNumber": "1234",
                     "isValid": true,
                     "isArchived": false,
+                    "needsVoucher": false,
                     "gboPackageTemplateId": "33610",
                     "productName": "HTM Regio Vrij DH73",
                     "productDescription": "Voor een vast bedrag onbeperkt reizen met EBS, HTM en RET in het gekozen gebied in de regio Rotterdam Den Haag.",
@@ -866,6 +877,7 @@ paths:
                       "fikoArticleNumber": "1234",
                       "isValid": true,
                       "isArchived": false,
+                      "needsVoucher": false,
                       "gboPackageTemplateId": "30901",
                       "tapConnectProductCode": null,
                       "productName": "HTM pilot 90% korting",
@@ -1028,6 +1040,7 @@ paths:
                       "fikoArticleNumber": "1234",
                       "isValid": true,
                       "isArchived": false,
+                      "needsVoucher": false,
                       "gboPackageTemplateId": "30901",
                       "tapConnectProductCode": null,
                       "productName": "HTM pilot 90% korting",
@@ -1270,6 +1283,7 @@ paths:
                       "fikoArticleNumber": "1234",
                       "isValid": true,
                       "isArchived": false,
+                      "needsVoucher": false,
                       "gboPackageTemplateId": "33610",
                       "tapConnectProductCode": null,
                       "productName": "HTM Regio Vrij DH73",
@@ -1475,6 +1489,7 @@ paths:
                       "fikoArticleNumber": "1234",
                       "isValid": true,
                       "isArchived": false,
+                      "needsVoucher": false,
                       "gboPackageTemplateId": null,
                       "tapConnectProductCode": null,
                       "productName": "IBAN wijzigen functioneel product",
@@ -1672,6 +1687,7 @@ paths:
                       "fikoArticleNumber": "1234",
                       "isValid": true,
                       "isArchived": false,
+                      "needsVoucher": false,
                       "gboPackageTemplateId": null,
                       "tapConnectProductCode": null,
                       "productName": "OV-pas saldo (1 eurocent)",
@@ -2775,6 +2791,10 @@ components:
           type: boolean
           description: Indicates if the product is archived - if true, the Service Engine will prevent touchpoints from seeing this product
           example: false
+        needsVoucher:
+          type: boolean
+          description: Indicates if the product needs a voucher (with this productId as requiredProductId) to be bought - if false, this is optional, but still allowed
+          example: false
         gboPackageTemplateId:
           type: string
           example: '30901'
@@ -3132,6 +3152,10 @@ components:
           type: boolean
           description: Indicates if the product is archived - if true, the Service Engine will prevent touchpoints from seeing this product
           example: false
+        needsVoucher:
+          type: boolean
+          description: Indicates if the product needs a voucher (with this productId as requiredProductId) to be bought - if false, this is optional, but still allowed
+          example: false
         gboPackageTemplateId:
           type: string
           description: >-
@@ -3503,6 +3527,10 @@ components:
           type: boolean
           description: Indicates if the product is archived - if true, the Service Engine will prevent touchpoints from seeing this product
           example: false
+        needsVoucher:
+          type: boolean
+          description: Indicates if the product needs a voucher (with this productId as requiredProductId) to be bought - if false, this is optional, but still allowed
+          example: false
         gboPackageTemplateId:
           type: string
           description: >-

src/openapi/products/purchased_products-crud.yaml

@@ -128,7 +128,7 @@ paths:
                                   "createdOn": "2024-10-04T12:34:56.000",
                                   "lastUpdatedOn": "2024-10-04T12:34:56.000",
                                   "createdBy": "someuser",
-                                  "lastUpdatedBy": null,
+                                  "lastUpdatedBy": null
                                 },
                               ],
                             "purchasedTapconnectTickets": [],
@@ -154,7 +154,7 @@ paths:
                                   "purchasedProductResourceId": "06dae996-cdfe-45f1-833a-720201c35114",
                                   "resourceName":
                                     { "resourceNameId": 2, "name": "orders" },
-                                  "resourceIdentifier": "f809a6e1-1c8d-4f8e-8a6e-0d0b1e1e1e1e",
+                                  "resourceIdentifier": "f809a6e1-1c8d-4f8e-8a6e-0d0b1e1e1e1e"
                                 },
                               ],
                             "purchasedGboProducts": [],
@@ -170,6 +170,11 @@ paths:
                                   "lastUpdatedOn": "2024-10-04T12:34:56.000",
                                   "createdBy": "user",
                                   "lastUpdatedBy": "user",
+                                  "externalDeviceId": "c5545584-04af-4c60-a955-d6a70baab848",
+                                  "serviceId": "HTM-1234-7654-8945",
+                                  "activateBefore": "2024-10-08",
+                                  "validityStart": "2024-10-05T12:34:56.000",
+                                  "validityEnd": "2024-10-06T12:34:56.000"
                                 },
                               ],
                             "issuedVouchers": [],
@@ -243,143 +248,6 @@ paths:
                         ],
                       "href": null,
                     }
-    post:
-      tags:
-        - Purchased Product
-      summary: Create a new purchased product.
-      description: Create a new purchased product.
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/unavailable"
-            examples:
-              Create Purchased GBO Product:
-                value:
-                  {
-                    "productId": 11,
-                    "createdOn": "2024-10-04T12:34:56.000",
-                    "lastUpdatedOn": "2024-10-04T12:34:56.000",
-                    "purchasedProductResources":
-                      [
-                        {
-                          "resourceNameId": 1,
-                          "resourceIdentifier": "408eefa9-b393-4bb3-8439-b2e51833abc7",
-                        },
-                        {
-                          "resourceNameId": 2,
-                          "resourceIdentifier": "f809a6e1-1c8d-4f8e-8a6e-0d0b1e1e1e1e",
-                        },
-                      ],
-                    "purchasedGboProducts":
-                      [
-                        {
-                          "salesTimestamp": "2024-10-04T12:34:56.000",
-                          "refundTimestamp": "2024-10-04T12:34:56.000",
-                          "fromInclusive": "2024-10-04T12:34:56.000",
-                          "untilInclusive": "2024-10-04T12:34:56.000",
-                          "packageTemplateId": "30003",
-                          "xBot": "f15efe6f-7353-4968-b134-60ba6fc2da8b",
-                          "xTat": "42efebf7-132e-4ee0-9cbb-4037a9a54ad8",
-                          "xSpit": "d67b2f72-918a-4e6c-957d-a39ed9c9e16b",
-                          "customerTokenId": "b6492322-c458-4857-9ac3-a109c1887b9f",
-                          "ovPayTokenId": 13,
-                          "createdOn": "2024-10-04T12:34:56.000",
-                          "lastUpdatedOn": "2024-10-04T12:34:56.000",
-                          "createdBy": "someuser",
-                          "lastUpdatedBy": null,
-                        },
-                      ],
-                    "purchasedTapconnectTickets": [],
-                    "issuedVouchers": [],
-                  }
-              Create Purchased TapConnet Ticket:
-                value:
-                  {
-                    "productId": 11,
-                    "createdOn": "2024-10-04T12:34:56.000",
-                    "lastUpdatedOn": "2024-10-04T12:34:56.000",
-                    "purchasedProductResources":
-                      [
-                        {
-                          "resourceNameId": 1,
-                          "resourceIdentifier": "408eefa9-b393-4bb3-8439-b2e51833abc7",
-                        },
-                        {
-                          "resourceNameId": 2,
-                          "resourceIdentifier": "f809a6e1-1c8d-4f8e-8a6e-0d0b1e1e1e1e",
-                        },
-                      ],
-                    "purchasedGboProducts": [],
-                    "purchasedTapconnectTickets":
-                      [
-                        {
-                          "issuedAt": "2024-10-04T12:34:56.000",
-                          "activatedAt": "2024-10-04T12:34:56.000",
-                          "cancelledAt": null,
-                          "ticketReference": "KJj43nejhbTxhr897287",
-                          "createdOn": "2024-10-04T12:34:56.000",
-                          "lastUpdatedOn": "2024-10-04T12:34:56.000",
-                          "createdBy": "user",
-                          "lastUpdatedBy": "user",
-                        },
-                      ],
-                    "issuedVouchers": [],
-                  }
-              Create Issued Voucher:
-                value:
-                  {
-                    "productId": 11,
-                    "createdOn": "2024-10-04T12:34:56.000",
-                    "lastUpdatedOn": "2024-10-04T12:34:56.000",
-                    "purchasedProductResources":
-                      [
-                        {
-                          "resourceNameId": 1,
-                          "resourceIdentifier": "408eefa9-b393-4bb3-8439-b2e51833abc7",
-                        },
-                        {
-                          "resourceNameId": 2,
-                          "resourceIdentifier": "f809a6e1-1c8d-4f8e-8a6e-0d0b1e1e1e1e",
-                        },
-                      ],
-                    "purchasedGboProducts": [],
-                    "purchasedTapconnectTickets": [],
-                    "issuedVouchers":
-                      [
-                        {
-                          "voucherCode": "VOUCHER123",
-                          "voucherStatusInstances":
-                            [
-                              {
-                                "voucherStatusId": 1,
-                                "createdOn": "2024-10-04T12:34:56.000",
-                              },
-                            ],
-                          "voucherClaims":
-                            [
-                              {
-                                "mandatoryCustomerDataItemId": 8,
-                                "value": "1999-12-31",
-                              },
-                              {
-                                "mandatoryCustomerDataItemId": 4,
-                                "value": "vlad.harkonnen@househarkonnen.net",
-                              },
-                            ],
-                        },
-                      ],
-                  }
-      responses:
-        "201":
-          description: Created
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/unavailable"
-              example:
-                { "purchasedProductId": "a9b3dea5-fb8a-4b1e-9fe6-90cad31c0cfd" }
   /purchasedproducts/{purchasedProductId}:
     parameters:
       - in: path
@@ -478,6 +346,11 @@ paths:
                             "lastUpdatedOn": "2024-10-04T12:34:56.000",
                             "createdBy": "user",
                             "lastUpdatedBy": "user",
+                            "externalDeviceId": "c5545584-04af-4c60-a955-d6a70baab848",
+                            "serviceId": "HTM-1234-7654-8945",
+                            "activateBefore": "2024-10-08",
+                            "validityStart": "2024-10-05T12:34:56.000",
+                            "validityEnd": "2024-10-06T12:34:56.000"
                           },
                         ],
                       "issuedVouchers": [],
@@ -912,18 +785,7 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/unavailable"
-            example:
-              {
-                "issuedAt": "2024-10-04T12:34:56.000",
-                "activatedAt": "2024-10-04T12:34:56.000",
-                "cancelledAt": null,
-                "ticketReference": "KJj43nejhbTxhr897287",
-                "createdOn": "2024-10-04T12:34:56.000",
-                "lastUpdatedOn": "2024-10-04T12:34:56.000",
-                "createdBy": "user",
-                "lastUpdatedBy": "user",
-              }
+              $ref: "#/components/schemas/PostPurchasedTapConnectTicketRequest"
       responses:
         "201":
           description: Created
@@ -1044,6 +906,60 @@ paths:
             type: string
             example: user
           description: The user that last updated the purchased Tapconnect ticket.
+        - in: query
+          name: externalDeviceId
+          schema:
+            type: string
+            example: c5545584-04af-4c60-a955-d6a70baab848
+          description: The external id of the device.
+        - in: query
+          name: serviceId
+          schema:
+            type: string
+            example: HTM-1234-7654-8945
+          description: A printable id that needs to be next to the printed barcode on the ticket, which is used when the customer contacts the service desk.
+        - in: query
+          name: activateBeforeBefore
+          schema:
+            type: string
+            format: date
+            example: 2024-10-04
+          description: Return only PurchasedTapConnectTickets that have `activateBefore` before this date.
+        - in: query
+          name: activateBeforeAfter
+          schema:
+            type: string
+            format: date-time
+            example: 2024-10-04
+          description: Return only PurchasedTapConnectTickets that have `activateBefore` after this date.
+        - in: query
+          name: validityStartBefore
+          schema:
+            type: string
+            format: date-time
+            example: 2024-10-04T12:34:56.000
+          description: Return only PurchasedTapConnectTickets that have `validityStart` before this timestamp.
+        - in: query
+          name: validityStartAfter
+          schema:
+            type: string
+            format: date-time
+            example: 2024-10-04T12:34:56.000
+          description: Return only PurchasedTapConnectTickets that have `validityStart` after this timestamp.
+        - in: query
+          name: validityEndBefore
+          schema:
+            type: string
+            format: date-time
+            example: 2024-10-04T12:34:56.000
+          description: Return only PurchasedTapConnectTickets that have `validityEnd` before this timestamp.
+        - in: query
+          name: validityEndAfter
+          schema:
+            type: string
+            format: date-time
+            example: 2024-10-04T12:34:56.000
+          description: Return only PurchasedTapConnectTickets that have `validityEnd` after this timestamp.
       responses:
         "200":
           description: OK
@@ -1066,6 +982,11 @@ paths:
                         "lastUpdatedOn": "2024-10-04T12:34:56.000",
                         "createdBy": "user",
                         "lastUpdatedBy": "user",
+                        "externalDeviceId": "c5545584-04af-4c60-a955-d6a70baab848",
+                        "serviceId": "HTM-1234-7654-8945",
+                        "activateBefore": "2024-10-08",
+                        "validityStart": "2024-10-05T12:34:56.000",
+                        "validityEnd": "2024-10-06T12:34:56.000"
                       },
                     ],
                 }
@@ -1095,6 +1016,8 @@ paths:
                 "activatedAt": "2024-10-05T12:34:56.000",
                 "cancelledAt": "2024-10-06T12:34:56.000",
                 "lastUpdatedOn": "2024-10-05T12:34:56.000",
+                "validityStart": "2024-10-05T12:34:56.000",
+                "validityEnd": "2024-10-06T12:34:56.000"
               }
       responses:
         "200":
@@ -1105,7 +1028,7 @@ paths:
                 $ref: "#/components/schemas/unavailable"
               example:
                 {
-                  "purchasedTapconnectTicketId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
+                  "purchasedTapconnectTicketId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90"
                 }
   /purchasedproducts/{purchasedProductId}/issuedvouchers:
     parameters:
@@ -1146,6 +1069,8 @@ paths:
                       "value": "vlad.harkonnen@househarkonnen.net",
                     },
                   ],
+                "fromInclusive": "2024-10-04T12:34:56.000",
+                "untilInclusive": "2025-10-04T12:34:56.000",
               }
       responses:
         "201":
@@ -1177,6 +1102,12 @@ paths:
             format: uuid
             example: 058a1af7-897f-45d5-b691-9cc9161e387f
           description: The id of the purchased product.
+        - in: query
+          name: productId
+          schema:
+            type: integer
+            example: 1
+          description: The id of the product and the issuedVouchers related to it
         - in: query
           name: voucherCode
           schema:
@@ -1192,6 +1123,14 @@ paths:
           explode: false
           required: false
           description: The moest recent status id of the voucher.
+        - in: query
+          name: orderBy
+          schema:
+            type: string
+            enum: [PurchasedProductCreatedOn, PurchasedProductLastUpdatedOn]
+          explode: false
+          required: false
+          description: The ordering of the issuedVouchers in the list
       responses:
         "200":
           description: OK
@@ -1241,6 +1180,8 @@ paths:
                               "value": "vlad.harkonnen@househarkonnen.net",
                             },
                           ],
+                        "fromInclusive": "2024-10-04T12:34:56.000",
+                        "untilInclusive": "2025-10-04T12:34:56.000",
                       },
                     ],
                 }
@@ -1311,6 +1252,117 @@ components:
   schemas:
     unavailable:
       type: object
+    PostPurchasedTapConnectTicketRequest:
+      type: object
+      required:
+        - issuedAt
+        - ticketReference
+        - createdOn
+        - lastUpdatedOn
+        - createdBy
+        - serviceId
+        - activateBefore
+      properties:
+        issuedAt:
+          type: string
+          format: date-time
+          example: 2024-10-04T12:34:56.000
+        activatedAt:
+          type: string
+          format: date-time
+          example: 2024-10-04T12:34:56.000
+        cancelledAt:
+          type: string
+          format: date-time
+          example: 2024-10-04T12:34:56.000
+        ticketReference:
+          type: string
+          example: KJj43nejhbTxhr897287
+        createdOn:
+          type: string
+          format: date-time
+          example: 2024-10-04T12:34:56.000
+        lastUpdatedOn:
+          type: string
+          format: date-time
+          example: 2024-10-04T12:34:56.000
+        createdBy:
+          type: string
+          example: John Doe
+        lastUpdatedBy:
+          type: string
+          example: John Doe
+        externalDeviceId:
+          type: string
+          example: c5545584-04af-4c60-a955-d6a70baab848
+        serviceId:
+          type: string
+          example: HTM-1234-7654-8945
+        activateBefore:
+          type: string
+          format: date
+          description: Tickets can only be activated BEFORE this date. Should be equal to TapConnect's `lifeSpanEnd + P1D`
+          example: 2024-10-08
+        validityStart:
+          type: string
+          format: date-time
+          description: The date-time at which the ticket will become valid for for traveling. The ticket will not be valid before this date/time.
+          example: 2024-10-05T12:34:56.000
+        validityEnd:
+          type: string  
+          format: date-time
+          description: The date-time at which the ticket will become invalid for traveling. The ticket will not be valid after this date/time.
+          example: 2024-10-06T12:34:56.000
+    BulkResponseBody:
+      type: object
+      properties:
+        startTime:
+          type: string
+          format: date-time
+          example: 2025-02-14T05:32:47.0672237Z
+        status:
+          type: string
+          example: Running
+        clientTrackingId:
+          type: string
+          example: 08584620957189579629541919368CU00
+        callbackurl:
+          type: string
+          format: uri
+          example: https://services.api.htm.nl/purchasedproducts/responsestatus/runtime/webhooks/workflow/scaleUnits/prod-00/workflows/6fd466916c
+        retryAfter:
+          type: integer
+          example: 10
+        summary:
+          $ref: "#/components/schemas/summaryBody"
+      required:
+        - startTime
+        - status
+        - clientTrackingId
+        - callbackurl
+        - retryAfter
+        - summary
+    summaryBody:
+      type: object
+      properties:
+        summary:
+          type: object
+          properties:
+            created:
+              type: integer
+              example: 15
+            updated:
+              type: integer
+              example: 2
+            total:
+              type: integer
+              example: 17
+          required:
+            - created
+            - total
+            - updated
+      required:
+        - summary
     rfc9457:
       type: object
       properties:

src/openapi/tapconnect/tapconnect.yaml

@@ -0,0 +1,477 @@
+openapi: 3.0.1
+info:
+  title: TapConnect
+  description: >-
+    Welcome to the TapConnect Issuing API documentation. These pages describe the endpoints available within TapConnect. Please note that for historical reasons, Date/times are always in the "Europe/Amsterdam" timezone. The endpoints in this document are grouped as follows:
+      
+      - **Export endpoints**: Export related endpoints return information about events related to tickets that have been issued. This can be used for Business Intelligence purposes or for financial record keeping.
+      - **Product endpoints**: Product related endpoints return information about products that are available to you as a sales partner and the details of each of these products.
+      - **Ticket endpoints**: Ticket related endpoints allow you to manage tickets throughout their lifecycle. This includes ticket creation, retrieving ticket information, or retrieving the barcode for a ticket.
+      - **Journey endpoints**: Used to calculate the price of a journey and to issue a ticket for that journey using the external fare calculation engine.
+
+    For more information on TapConnect please visit [https://tapconnect.io](https://tapconnect.io) or [https://documentation.tapconnect.io](https://documentation.tapconnect.io).
+  version: '1.0'
+servers:
+  - url: https://services.acc.api.htm.nl/tapconnect/1.0
+tags:
+  - name: Export
+    description: >-
+      Export data that can be used to generate reports about issued tickets
+      and related information
+paths:
+  /v5/ticket-events-export:
+    get:
+      summary: Elastic Search ticket events export
+      description: "Exports ticket events data from Elastic Search.\n\nBoth parameters\
+        \ are a string, and they have to represent a date. Consider the list of valid\
+        \ formats below:\n1. 2021 - searches for all events in a year\n2. 2021-02\
+        \ - searches for all events in a month\n3. 2021-02-02 - searches for all events\
+        \ in a day\n4. 2021-02-02T12 - searches for all events in a specific hour\n\
+        5. 2021-02-02T12:00 - searches for all events in a specific minute\n6. 2021-02-02T12:00:00\
+        \ - searches for all events in a specific second\n\nIf an error occur, the\
+        \ last element returned will be a message with \"An error occurred on Elasticsearch\"\
+        \ and it \nmeans that not all the results are returned.\n_Keep in mind that\
+        \ the above timestamps would also be accepted as Zulu: 2021-02-02T11:00:00Z\
+        \ (winter time)_\n"
+      parameters:
+      - explode: true
+        in: query
+        name: start
+        required: true
+        description: The date to be considered as the interval starting date
+        schema:
+          example: 2021-02-01T00:00:00
+          type: string      
+        style: form
+      - explode: true
+        in: query
+        name: end
+        required: true
+        description: The date to be considered as the interval ending date
+        schema:
+          example: 2021-02-02T00:00:00
+          type: string
+        style: form
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/v5_ticket_events_export_response'
+          description: Returns a JSON chunked array of ticket events exported from elastic search.
+        "400":
+          description: |
+            The request could not be validated. The request body or parameters contain incomplete or incorrect parameters. The body of the response will contain information about the problem.
+        "401":
+          description: |
+            Unauthorized call, you are not authorized to call this endpoint with the api key provided in the Authorization header. Please verify that your api key is correct and/or if you are authorized to call this endpoint.
+        "403":
+          description: |
+            Unauthorized call, you are not authorized to call this endpoint with the api key provided in the Authorization header. Please verify that your api key is correct and/or if you are authorized to call this endpoint.
+        "404":
+          description: |
+            The requested URL does not exist, or the requested object was not found.
+        "406":
+          description: |
+            The request was not accepted by the server. The body of the response will contain information about the problem.
+      tags:
+      - Export
+components:
+  schemas:
+    v5_ticket_events_export_response:
+      type: array
+      items:
+        anyOf:
+        - $ref: '#/components/schemas/ActivateTicketEvent'
+        - $ref: '#/components/schemas/CreateBarcodeEvent'
+        - $ref: '#/components/schemas/CreateTicketEvent'
+        - $ref: '#/components/schemas/TapEvent'
+        - $ref: '#/components/schemas/InspectTicketEvent'
+        - $ref: '#/components/schemas/NotifyEvent'
+    ActivateTicketEvent:
+      properties:
+        eventId:
+          example: 1
+          type: number
+        eventType:
+          example: ACTIVATE_TICKET
+          type: string
+        occurredAt:
+          example: 2021-06-07T08:42:00.791992000Z
+          type: string
+        receivedAt:
+          example: 2021-06-07T08:42:00.791992000Z
+          type: string
+        timeToDie:
+          example: 2445836980
+          type: number
+        operators:
+          items:
+            example: HTM
+            type: string
+          type: array
+        createdBy:
+          example: HTM
+          type: string
+        definedBy:
+          example: HTM
+          type: string
+        ticketId:
+          example: hkbu3415fbidswd803nfdg7
+          type: string
+        validityStart:
+          example: 2021-06-06T22:00:00.000000000Z
+          type: string
+        validityEnd:
+          example: 2021-06-07T23:40:00.000000000Z
+          type: string
+        validityType:
+          example: FIXED
+          type: string
+    CreateBarcodeEvent:
+      properties:
+        eventId:
+          example: 2
+          type: number
+        eventType:
+          example: CREATE_BARCODE
+          type: string
+        occurredAt:
+          example: 2021-06-07T08:42:01.629279000Z
+          type: string
+        receivedAt:
+          example: 2021-06-07T08:42:01.629279000Z
+          type: string
+        timeToDie:
+          example: 2445836980
+          type: number
+        operators:
+          items:
+            example: HTM
+            type: string
+          type: array
+        createdBy:
+          example: HTM
+          type: string
+        definedBy:
+          example: HTM
+          type: string
+        ticketId:
+          example: 2huCpR99LHjGfiq8ZJoF
+          type: string
+        barcodeSignatureKeyId:
+          example: TCT07
+          type: string
+        barcodeValidityStart:
+          example: 2021-06-06T22:00:00.000000000Z
+          type: string
+        barcodeValidityEnd:
+          example: 2021-06-07T23:40:00.000000000Z
+          type: string
+    CreateTicketEvent:
+      properties:
+        eventId:
+          example: 0
+          type: number
+        eventType:
+          example: CREATE_TICKET
+          type: string
+        occurredAt:
+          example: 2021-06-07T08:42:00.790992000Z
+          type: string
+        receivedAt:
+          example: 2021-06-07T08:42:00.790992000Z
+          type: string
+        reportedAt:
+          example: 2021-06-07T08:42:00.790992000Z
+          type: string
+        timeToDie:
+          example: 2445836980
+          type: number
+        operators:
+          items:
+            example: HTM
+            type: string
+          type: array
+        createdBy:
+          example: HTM
+          type: string
+        definedBy:
+          example: HTM
+          type: string
+        ticketId:
+          example: 344BEuHcFkEChOPm06sY
+          type: string
+        serviceId:
+          example: HTM-0987-7477-0993
+          type: string
+        productName:
+          example: HTM Kinder Dagkaart
+          type: string
+        productCode:
+          example: "303"
+          type: string
+        productValidityPeriodUnit:
+          example: "DAYS"
+          type: string
+        productValidityPeriod:
+          example: 1
+          type: number
+        lifespanStart:
+          example: 2021-06-07
+          type: string
+        lifespanEnd:
+          example: 2021-06-08
+          type: string
+        language:
+          example: NL
+          type: string
+        salesChannelId:
+          example: "9999"
+          type: string
+        salesChannelName:
+          example: HTM App
+          type: string
+        startStation:
+          example: Haarlem
+          type: string
+        endStation:
+          example: Leiden Centraal
+          type: string
+        barcodeType:
+          example: UIC
+          type: string
+        validityType:
+          example: FIXED
+          type: string
+        refundable:
+          example: true
+          type: boolean
+        priceInCents:
+          example: 150,
+          type: number
+        numberOfAdults:
+          example: 1
+          type: number
+        numberOfChildren:
+          example: 0
+          type: number
+        roundToBusinessDay:
+          example: true
+          type: boolean
+        modalities:
+          example: ["BUS", "TRAM"]
+          type: array
+          items:
+            example: BUS
+            type: string
+    TapEvent:
+      properties:
+        eventId:
+          example: 5
+          type: number
+        eventType:
+          example: TAP
+          type: string
+        occurredAt:
+          example: 2021-06-07T08:42:00.790992000Z
+          type: string
+        receivedAt:
+          example: 2021-06-07T08:42:00.790992000Z
+          type: string
+        timeToDie:
+          example: 2445836980
+          type: number
+        validationAction:
+          example: CHECK_OUT
+          type: string
+        validationResult:
+          example: Approved
+          type: string
+        tapId:
+          example: a9aea0ae-52de-42cd-a2f1-93b80d9af389
+          type: string
+        operators:
+          items:
+            example: HTM
+            type: string
+          type: array
+        createdBy:
+          example: HTM
+          type: string
+        definedBy:
+          example: HTM
+          type: string
+        ticketId:
+          example: hkbu3415fbidswd803nfdg7
+          type: string
+        modality:
+          example: BUS
+          type: string
+        line:
+          example: "25"
+          type: string
+        trip:
+          example: "240"
+          type: string
+        vehicle:
+          example: "1512"
+          type: string
+        deviceId:
+          example: "13513A"
+          type: string
+        deviceType:
+          example: VBS
+          type: string
+        lastStopId:
+          example: "3409"
+          type: string
+        lastStopName:
+          example: Gramsbergenlaan
+          type: string
+        nextStopId:
+          example: "3409"
+          type: string
+        nextStopName:
+          example: Gramsbergenlaan
+          type: string
+        location:
+          type: object
+          properties:
+            lat:
+              example: 52.00089453333333
+              type: number
+            lon:
+              example: 4.004570666666667
+              type: number
+    InspectTicketEvent:
+      properties:
+        eventId:
+          example: 3
+          type: number
+        eventType:
+          example: INSPECT_TICKET
+          type: string
+        occurredAt:
+          example: 2021-06-07T08:42:00.790992000Z
+          type: string
+        receivedAt:
+          example: 2021-06-07T08:42:00.790992000Z
+          type: string
+        timeToDie:
+          example: 2445836980
+          type: number
+        operators:
+          items:
+            example: HTM
+            type: string
+          type: array
+        createdBy:
+          example: HTM
+          type: string
+        definedBy:
+          example: HTM
+          type: string
+        ticketId:
+          example: uv1hzvrRd7Xd1Fs9vTxi
+          type: string
+        modality:
+          example: BUS
+          type: string
+        deviceId:
+          example: 6959bd00eaec8e68
+          type: string
+        deviceType:
+          example: IBS
+          type: string
+        validationResult:
+          example: Approved
+          type: string
+    NotifyEvent:
+      properties:
+        eventId:
+          example: 1185
+          type: number
+        eventType:
+          example: NOTIFY
+          type: string
+        occurredAt:
+          example: 2021-06-07T08:42:00.790992000Z
+          type: string
+        receivedAt:
+          example: 2021-06-07T08:42:00.790992000Z
+          type: string
+        timeToDie:
+          example: 2445836980
+          type: number
+        tapId:
+          example: a9aea0ae-52de-42cd-a2f1-93b80d9af389
+          type: string
+        sequence:
+          example: 2
+          type: number
+        tapResponseTimeMillis:
+          example: 402
+          type: number
+        validationAction:
+          example: CHECK_OUT
+          type: string
+        validationMethod:
+          example: ONLINE
+          type: string
+        validationResult:
+          example: Approved
+          type: string
+        operators:
+          items:
+            example: HTM
+            type: string
+          type: array
+        createdBy:
+          example: HTM
+          type: string
+        definedBy:
+          example: HTM
+          type: string
+        modality:
+          example: TRAM
+          type: string
+        line:
+          example: "3"
+          type: string
+        trip:
+          example: "692"
+          type: string
+        vehicle:
+          example: "4058"
+          type: string
+        deviceId:
+          example: "13A886"
+          type: string
+        deviceType:
+          example: VBS
+          type: string
+        lastStopId:
+          example: "2005"
+          type: string
+        lastStopName:
+          example: Fahrenheitstraat
+          type: string
+        nextStopId:
+          example: "2011"
+          type: string
+        nextStopName:
+          example: Valkenbosplein
+          type: string
+        ticketId:
+          example: hkbu3415fbidswd803nfdg7
+          type: string
+        location:
+          type: object
+          properties:
+            lat:
+              example: 52.001300283333336
+              type: number
+            lon:
+              example: 4.004586633333333
+              type: number