From f033ab6bbed7fa57a96b20c617391cb2d6540192 Mon Sep 17 00:00:00 2001 From: Max Martens Date: Fri, 27 Mar 2026 11:12:25 +0100 Subject: [PATCH] Move /purchasedproducts endpoint to SE-customers-V2 --- src/openapi/customers/SE-customers-v2.yaml | 971 +++++++++++++-------- src/openapi/customers/SE-customers.yaml | 641 +------------- 2 files changed, 630 insertions(+), 982 deletions(-) diff --git a/src/openapi/customers/SE-customers-v2.yaml b/src/openapi/customers/SE-customers-v2.yaml index 6f76888..7aeeffa 100644 --- a/src/openapi/customers/SE-customers-v2.yaml +++ b/src/openapi/customers/SE-customers-v2.yaml @@ -1939,288 +1939,6 @@ paths: }, } /customers/tokens/{ovPayTokenId}: - post: - tags: - - Customers - 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: string - example: feaaef83-a551-4283-8419-340b1ada3b55 - required: false - description: The customerProfileId of a customer in the case of the SMP - - name: X-HTM-ROLE-HEADER - in: header - schema: - type: string - example: Customer - required: false - - name: ovPayTokenId - in: path - schema: - type: integer - example: 1 - required: true - summary: Replace an OVpay token with another (+ transfer products) - V2 (for touch point) - description: | - Transfer products from one OVpay token to another, and replace the tokens in the database. - This endpoint is for touch point usage and will be replaced by `/customers/tokens/{ovPayTokenId}/transfer`. - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/unavailable" - examples: - Replace with new EMV token by SRID: - summary: Replace with new token by SRID - description: Replace with new token by service reference ID and amount. - value: - { - "ovPayToken": - { - "newTokenId": null, - "tokenTypeId": 1, - "serviceReferenceId": "NLOV1234567ABCDEFG", - "amount": 230, - "alias": "Nieuw token", - }, - } - Replace with existing EMV token from profile: - summary: Replace with existing token from profile - description: Replace with existing token from customer profile. - value: { "ovPayToken": { "newTokenId": 10 } } - Replace with new OV pas token: - summary: Replace with new OV pas token - description: Replace with new OV pas token by OV-pas number. - value: - { - "ovPayToken": - { - "tokenTypeId": 2, - "ovpasNumber": "OV34567", - "verificationCode": "211", - "alias": "Mijn token", - }, - } - responses: - "201": - description: Created - content: - application/json: - schema: - $ref: "#/components/schemas/unavailable" - examples: - Replace with new EMV token: - summary: Replace with new EMV token - description: Replace with new EMV token - value: - { - "ovPayToken": - { - "customerProfileId": 1, - "ovPayTokenId": 5, - "xTat": "32089cc8-d187-47ff-a3a9-5c2558def811", - "tokenType": { "tokenTypeId": 1, "name": "EMV" }, - "lastDigits": null, - "ovpasNumber": null, - "alias": "Mijn token", - "tokenStatus": - { "tokenStatusId": 2, "name": "Active" }, - "expirationDate": "2028-08-31T23:59:00+02:00", - "replacedByTokenId": null, - "autoReloadRegistration": null, - "ePurse": null, - "personalAccountData": - { "name": null, "birthdate": null, "photo": null }, - "gboAgeProfile": null, - "_links": - { - "self": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens?ovPaytokenId=5", - "method": "GET", - }, - "partial_edit": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens/5", - "method": "PATCH", - }, - "delete_token": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens/5", - "method": "DELETE", - }, - "get_productinstances": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens/5/productinstances", - "method": "GET", - }, - "get_trips": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens/5/trips", - "method": "GET", - }, - "add_personal-data": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/personal-data/32089cc8-d187-47ff-a3a9-5c2558def811", - "method": "POST", - }, - "compare_token": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens/5/compare", - "method": "POST", - }, - }, - }, - } - Replace with new OV pas token: - summary: Replace with new OV pas token - description: Replace with new OV pas token - value: - { - "ovPayToken": - { - "customerProfileId": 1, - "ovPayTokenId": 5, - "xTat": "32089cc8-d187-47ff-a3a9-5c2558def811", - "tokenType": - { "tokenTypeId": 2, "name": "OV-pas physical" }, - "lastDigits": null, - "ovpasNumber": "OV34567", - "alias": "Mijn token", - "tokenStatus": - { "tokenStatusId": 2, "name": "Active" }, - "expirationDate": "2028-08-31T23:59:00+02:00", - "replacedByTokenId": null, - "autoReloadRegistration": null, - "ePurse": - { - "e-PurseBalance": - { "currency": "EUR", "amount": 350 }, - "status": "ACTIVE", - "originDate": "2024-07-16T11:00:00+02:00", - }, - "personalAccountData": - { "name": null, "birthdate": null, "photo": null }, - "gboAgeProfile": null, - "_links": - { - "self": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens?ovPaytokenId=5", - "method": "GET", - }, - "partial_edit": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens/5", - "method": "PATCH", - }, - "delete_token": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens/5", - "method": "DELETE", - }, - "get_productinstances": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens/5/productinstances", - "method": "GET", - }, - "get_trips": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens/5/trips", - "method": "GET", - }, - "add_personal-data": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/personal-data/32089cc8-d187-47ff-a3a9-5c2558def811", - "method": "POST", - }, - "compare_token": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens/5/compare", - "method": "POST", - }, - }, - }, - } - "200": - description: Ok - content: - application/json: - schema: - $ref: "#/components/schemas/unavailable" - examples: - Replace with existing EMV token: - summary: Replace with existing EMV token - description: Replace with existing EMV token - value: - { - "ovPayToken": - { - "customerProfileId": 1, - "ovPayTokenId": 10, - "xTat": "32089cc8-d187-47ff-a3a9-5c2558def811", - "tokenType": { "tokenTypeId": 1, "name": "EMV" }, - "lastDigits": null, - "ovpasNumber": null, - "alias": "Mijn bestaande token", - "tokenStatus": - { "tokenStatusId": 2, "name": "Active" }, - "expirationDate": "2028-08-31T23:59:00+02:00", - "replacedByTokenId": null, - "autoReloadRegistration": null, - "ePurse": null, - "personalAccountData": - { "name": null, "birthdate": null, "photo": null }, - "gboAgeProfile": null, - "_links": - { - "self": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens?ovPaytokenId=10", - "method": "GET", - }, - "partial_edit": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens/10", - "method": "PATCH", - }, - "delete_token": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens/10", - "method": "DELETE", - }, - "get_productinstances": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens/10/productinstances", - "method": "GET", - }, - "get_trips": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens/10/trips", - "method": "GET", - }, - "add_personal-data": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/personal-data/32089cc8-d187-47ff-a3a9-5c2558def811", - "method": "POST", - }, - "compare_token": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens/10/compare", - "method": "POST", - }, - }, - }, - } patch: tags: - Customers @@ -3184,7 +2902,7 @@ paths: type: integer example: 1 post: - summary: "Transfer old OVpay token to new OVpay token." + summary: "**INTEGRATIELAAG** Transfer old OVpay token to new OVpay token." description: |- **Note that this directly calls the integratielaag and not the Service Engine!** First transfers all personal account data (if present), then all products, of an existing OVpay token @@ -3318,7 +3036,7 @@ paths: get: tags: - Token Replace v2 - summary: "Get the status of the initiated token transfer process." + summary: "**INTEGRATIELAAG** Get the status of the initiated token transfer process." description: | **Note that this directly calls the integratielaag and not the Service Engine!** Get the status of the asynchronous token transfer processing. @@ -3597,90 +3315,323 @@ paths: }, ], } - /customers/devices: + /purchasedproducts: + 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 a touchpoint where customer logs in themselves + - name: X-HTM-CUSTOMER-PROFILE-ID-HEADER + in: header + schema: + type: string + example: feaaef83-a551-4283-8419-340b1ada3b55 + required: false + description: The customerProfileId of a customer in the case of the SMP + - name: X-HTM-ROLE-HEADER + in: header + schema: + type: string + example: Customer + required: false + - name: deviceId + in: query + description: Id of the device you want to get the purchased HTM products for. + schema: + type: string + format: uuid + - name: externalDeviceId + in: query + description: External id of the device you want to get the purchased HTM products for. + schema: + type: string + - name: ovpayTokenId + in: query + description: Id of the OVpay-token you want to get the purchased HTM products for. + schema: + type: string + format: uuid get: - summary: Retrieve devices for a customer. - description: Retrieve devices for a customer. + summary: Get a list of all purchased HTM products for a specific device or token of the given customer. At least one of the query parameters should be filled in. + description: |- + Get a list of all purchased HTM products for a specific device or token of the given customer. At least one of the query parametersshould be filled in. + Only HTM products are returned. + Where relevant, operations to be performed are returned as HATEOAS links per purchased product. tags: - - Devices - 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 - - name: deviceId - in: query - schema: - type: string - format: uuid - example: 3fc3e1d2-cbca-4c67-9210-77601301fd75 - - name: externalDeviceId - in: query - schema: - type: string - example: dsafdefaere5435255 - - name: customerProfileId - in: query - schema: - type: integer - example: 1 + - Purchased Products responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/unavailable" + $ref: "#/components/schemas/PurchasedProductsResponse" examples: - One device found: + getEmptyPurchasedProducts: + summary: No purchased products found + value: + purchasedProducts: { + "ovPayProducts":[], + "barcodeTickets": [], + "vouchers":[] + } + getTwoBarcodePurchasedProductsForDevice: + summary: Two BarcodeTicket purchased products, one PendingActivation and one Active + description: |- + The first ticket (PendingActivation) shows the 30-day range in which the ticket can be activated + (using the PATCH endpoint) in the validityStart and validityEnd fields. The second ticket (Active) + shows the actual validity period of the ticket after activation. value: { - "devices": - [ - { - "customerProfileId": 1, - "deviceId": "0f0981bf-6d60-4b06-bc55-de1ba325f366", - "externalDeviceId": "dee7d80e-9288-4508-a3ed-c067e619179f", - "alias": "My iPhone 13" - } - ] - } - Multiple devices found: - value: - { - "devices": - [ - { - "customerProfileId": 1, - "deviceId": "5bedce29-af0c-4f3c-b182-2caa8a1f9377", - "externalDeviceId": "c5545584-04af-4c60-a955-d6a70baab848", - "alias": "iPhone prive", - }, - { - "customerProfileId": 1, - "deviceId": "d7683e89-b2ad-4e79-85b3-dbb42aad0325", - "externalDeviceId": "7122a988-a00a-417d-a5b4-da2d91354976", - "alias": "iPhone zakelijk", - } - ] + "purchasedProducts":{ + "ovPayProducts":[], + "barcodeTickets":[ + { + "purchasedProductId": "0f0981bf-6d60-4b06-bc55-de1ba325f366", + "productId": 14, + "name": "HTM 2 uurskaart", + "status": "PendingActivation", + "productCategory": + { + "productCategoryId": 5, + "name": "Barcode", + }, + "orderId": "501B17EF-36C4-4039-B92C-6517969B464E", + "orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E", + "ticketReference": "KJj43nejhbTxhrfef287", + "serviceId": "DEF-4321-7654-7659", + "issuedAt": "2026-03-21T09:01:35", + "activatedAt": null, + "blocked": false, + "cancelledAt": null, + "validityStart": "2026-03-21T09:01:35", + "validityEnd": "2026-04-21T23:59:59", + "barcode": "barcodeBytes", + "externalDeviceId": "e2be51ae-2701-4803-a2d7-97d4b714482d", + "_links": { + "get_order": { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E", + "method": "GET" + }, + "patch_purchasedproduct": { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/purchasedproducts/0f0981bf-6d60-4b06-bc55-de1ba325f366", + "method": "PATCH" + } + } + }, + { + "purchasedProductId": "0f0981bf-6d60-4b06-bc55-de1ba325f366", + "productId": 14, + "name": "HTM 2 uurskaart", + "status": "Active", + "productCategory": + { + "productCategoryId": 5, + "name": "Barcode", + }, + "orderId": "501B17EF-36C4-4039-B92C-6517969B464E", + "orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E", + "ticketReference": "KJj43nejhbTxhr897287", + "serviceId": "ABC-1234-7654-8945", + "issuedAt": "2026-03-21T10:01:12", + "activatedAt": "2026-03-21T12:45:01", + "blocked": false, + "cancelledAt": null, + "validityStart": "2026-03-21T12:45:01", + "validityEnd": "2026-03-21T14:45:01", + "barcode": "barcodeBytes", + "externalDeviceId": "e2be51ae-2701-4803-a2d7-97d4b714482d", + "_links": { + "get_order": { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E", + "method": "GET" + } + } + } + ], + "vouchers":[] + } } + getSingleOvpayPurchasedProductForSpecificOvPayToken: + summary: One Ovpay purchased product + value: + { + "purchasedProducts":{ + "ovPayProducts":[ { + "purchasedProductId": "26d41861-f77e-4666-9cde-2c5c66ace0a2", + "productId": 1, + "name": "HTM 90% Korting", + "status": "Active", + "isRenewable": true, + "productCategory": + { + "productCategoryId": 1, + "name": "Kortingsabonnement", + }, + "fromInclusive": "2024-11-25T13:25:00+01:00", + "untilInclusive": "2024-12-25T03:59:59+01:00", + "orderId": "501B17EF-36C4-4039-B92C-6517969B464E", + "orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E", + "contractId": "56B17EF-C436-9043-B76C-481797WEB464F", + "ovPayTokenId": 42, + "_links": + { + "get_order": + { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E", + "method": "GET", + }, + "get_contract": + { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/contracts/56B17EF-C436-9043-B76C-481797WEB464F", + "method": "GET", + }, + }, + }, + ], + "barcodeTickets":[], + "vouchers":[] + } + } + getSingleVoucherPurchasedProductForCustomer: + summary: One voucher purchased product + value: + { + "purchasedProducts":{ + "ovPayProducts":[], + "barcodeTickets":[], + "vouchers":[ + { + "purchasedProductId": "07a55d42-ea42-4f5c-896a-b340ab084309", + "productId": 81, + "name": "HTM ooivaarspas voucher", + "productCategory": + { + "productCategoryId": 9, + "name": "Voucher", + }, + "voucherCode": "HTM45253", + "fromInclusive": "2026-01-01T00:00:00", + "untilInclusive": "2026-12-31T23:59:99", + "voucherStatus": { + "voucherStatusId": 2, + "name": "issued" + }, + "mandatoryCustomerDataItems": + [ + { + "mandatoryCustomerDataItemId": 8, + "customerDataItem": "padBirthDate", + }, + { + "mandatoryCustomerDataItemId": 4, + "customerDataItem": "emailAddress", + }, + ] + } + ] + } + } + /purchasedproducts/{purchasedProductId}: + 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 a touchpoint where customer logs in themselves + - name: X-HTM-CUSTOMER-PROFILE-ID-HEADER + in: header + schema: + type: string + example: feaaef83-a551-4283-8419-340b1ada3b55 + required: false + description: The customerProfileId of a customer in the case of the SMP + - name: X-HTM-ROLE-HEADER + in: header + schema: + type: string + example: Customer + required: false + - name: purchasedProductId + in: path + required: true + style: simple + description: Id of the purchased product you want to change + schema: + type: string + format: uuid + example: 0f0981bf-6d60-4b06-bc55-de1ba325f366 + patch: + summary: Update a purchased product + description: |- + Update the given purchased product. Currently only used to activate a barcode ticket. + tags: + - Purchased Products + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/unavailable" + examples: + Activate a TapConnect purchased product: + value: + { + "status": "Active" + } + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/PurchasedProductsResponse" + examples: + Activate a TapConnect purchased product: + summary: Activate a TapConnect purchased product + value: + { + "purchasedProducts": { + "ovPayProducts": [], + "barcodeTickets": [ + { + "purchasedProductId": "0f0981bf-6d60-4b06-bc55-de1ba325f366", + "productId": 14, + "name": "HTM 2 uurskaart", + "status": "Active", + "productCategory": { + "productCategoryId": 5, + "name": "Barcode" + }, + "orderId": "501B17EF-36C4-4039-B92C-6517969B464E", + "orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E", + "ticketReference": "KJj43nejhbTxhr897287", + "serviceId": "ABC-1234-7654-8945", + "issuedAt": "2026-03-21T10:01:12", + "activatedAt": "2026-03-21T12:45:01", + "blocked": false, + "cancelledAt": null, + "validityStart": "2026-03-21T12:45:01", + "validityEnd": "2026-03-21T14:45:01", + "barcode": "barcodeBytes", + "externalDeviceId": "e2be51ae-2701-4803-a2d7-97d4b714482d", + "_links": { + "get_order": { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E", + "method": "GET" + } + } + } + ], + "vouchers": [] + } + } + + /customers/devices: post: summary: Add a new device to a customer profile. description: Add a new device to a customer profile. @@ -4324,4 +4275,312 @@ components: type: integer isPreferred: type: boolean + PurchasedProductsResponse: + type: object + required: + - purchasedProducts + properties: + purchasedProducts: + type: object + required: + - ovPayProducts + - barcodeTickets + - vouchers + properties: + ovPayProducts: + type: array + items: + type: object + required: + - purchasedProductId + - productId + - name + - status + - isRenewable + - productCategory + - fromInclusive + - orderId + - orderLineId + - _links + properties: + purchasedProductId: + type: string + format: uuid + example: 0f0981bf-6d60-4b06-bc55-de1ba325f366 + productId: + type: integer + example: 1 + name: + type: string + example: HTM 90% Korting + status: + type: string + enum: ["Active", "Ended", "Refunded"] + example: Active + isRenewable: + type: boolean + example: true + productCategory: + type: object + description: The category of the originating HTM product definition + properties: + productCategoryId: + type: integer + example: 1 + name: + type: string + example: Kortingsabonnement + fromInclusive: + type: string + format: date-time-offset + example: "2024-11-25T13:25:00+01:00" + untilInclusive: + type: string + format: date-time-offset + description: >- + If not present, this purchased product represents a subscription/contract without a real end date. If present, it can be either the natural end date or the refund timestamp. + example: "2024-12-25T03:59:59+01:00" + orderId: + type: string + format: uuid + example: 501B17EF-36C4-4039-B92C-6517969B464E + orderLineId: + type: string + format: uuid + example: 38B17EF-36C4-4039-B92C-4817969B464E + contractId: + type: string + format: uuid + example: 56B17EF-C436-9043-B76C-481797WEB464F + description: Only present for subscriptions/contracts + _links: + type: object + properties: + self: + type: object + properties: + href: + type: string + example: https://api.integratielaag.nl/abt/touchpoint/1.0/purchasedproducts + method: + type: string + example: GET + get_order: + type: object + properties: + href: + type: string + description: Always present for any HTM purchased product + example: https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E + method: + type: string + example: GET + get_contract: + type: object + 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 + example: GET + barcodeTickets: + type: array + items: + type: object + required: + - purchasedProductId + - productId + - name + - status + - productCategory + - orderId + - orderLineId + - ticketReference + - serviceId + - issuedAt + - blocked + - validityStart + - validityEnd + - _links + properties: + purchasedProductId: + type: string + format: uuid + example: 0f0981bf-6d60-4b06-bc55-de1ba325f366 + productId: + type: integer + example: 1 + name: + type: string + example: HTM 2 uurskaart + status: + type: string + enum: ["PendingActivation", "Active", "Ended", "Blocked", "Refunded"] + example: Active + productCategory: + type: object + description: The category of the originating HTM product definition + properties: + productCategoryId: + type: integer + example: 5 + name: + type: string + example: Barcode + orderId: + type: string + format: uuid + example: 501B17EF-36C4-4039-B92C-6517969B464E + orderLineId: + type: string + format: uuid + example: 38B17EF-36C4-4039-B92C-4817969B464E + ticketReference: + type: string + example: KJj43nejhbTxhr897287 + serviceId: + type: string + example: ABC-1234-7654-8945 + issuedAt: + type: string + format: date-time-offset + example: "2024-11-25T13:25:00+01:00" + activatedAt: + type: string + format: date-time-offset + description: Only present for active and ended barcode tickets + example: "2024-11-25T13:25:00+01:00" + blocked: + type: boolean + example: false + cancelledAt: + type: string + format: date-time-offset + example: "2024-11-25T13:25:00+01:00" + validityStart: + description: |- + The date-time at which the ticket will become valid for traveling. The ticket will not be valid before this date. + For tickets that require activation: Before activation this field will show the lower bound of the range in which + a ticket can be activated, after activation the value of this field is updated to the final start of the validity + range. For example: a 1 hour product that has to be activated within 7 days. Before ticket activation (activatedAt + field returns null) this value (together with validityEnd) will return the 7 day range, after activation (activatedAt + field returns a date-time) the value will show the start of the final 1 hour validity range. + type: string + format: date-time-offset + example: "2024-11-25T13:25:00+01:00" + validityEnd: + description: |- + The date-time at which the ticket will become valid for traveling. The ticket will not be valid before this date. + For tickets that require activation: Before activation this field will show the upper bound of the range in which + a ticket can be activated, after activation the value of this field is updated to the final end of the validity + range. For example: a 1 hour product that has to be activated within 7 days. Before ticket activation (activatedAt + field returns null) this value (together with validityStart) will return the 7 day range, after activation (activatedAt + field returns a date-time) the value will show the end of the final 1 hour validity range. + type: string + format: date-time-offset + example: "2024-11-25T15:25:00+01:00" + barcode: + type: string + example: barcodeBytes + externalDeviceId: + type: string + example: e2be51ae-2701-4803-a2d7-97d4b714482d + _links: + type: object + properties: + self: + type: object + properties: + href: + type: string + example: https://api.integratielaag.nl/abt/touchpoint/1.0/purchasedproducts + method: + type: string + example: GET + get_order: + type: object + properties: + href: + type: string + description: Always present for any HTM purchased product + example: https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E + method: + type: string + example: GET + patch_purchasedproduct: + type: object + properties: + href: + type: string + description: Only present for purchased products that are PATCHable + example: https://api.integratielaag.nl/abt/touchpoint/1.0/purchasedproducts/56B17EF-C436-9043-B76C-481797WEB464F + method: + type: string + example: PATCH + vouchers: + type: array + items: + type: object + required: + - purchasedProductId + - productId + - name + - productCategory + - voucherCode + - fromInclusive + - voucherStatus + properties: + purchasedProductId: + type: string + format: uuid + example: 0f0981bf-6d60-4b06-bc55-de1ba325f366 + productId: + type: integer + example: 81 + name: + type: string + example: HTM ooivaarspas voucher + productCategory: + type: object + description: The category of the originating HTM product definition + properties: + productCategoryId: + type: integer + example: 6 + name: + type: string + example: Voucher + voucherCode: + type: string + example: HKV-A7J-128-PYT + fromInclusive: + type: string + format: date-time-offset + example: "2024-11-25T13:25:00+01:00" + untilInclusive: + type: string + format: date-time-offset + example: "2024-12-25T03:59:59+01:00" + voucherStatus: + type: object + properties: + voucherStatusId: + type: integer + example: 2 + name: + type: string + example: issued + mandatoryCustomerDataItems: + type: array + items: + type: object + properties: + mandatoryCustomerDataItemId: + type: integer + example: 4 + customerDataItem: + type: string + example: emailAddress \ No newline at end of file diff --git a/src/openapi/customers/SE-customers.yaml b/src/openapi/customers/SE-customers.yaml index 414655f..6f3a59d 100644 --- a/src/openapi/customers/SE-customers.yaml +++ b/src/openapi/customers/SE-customers.yaml @@ -1960,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 @@ -3403,321 +3403,6 @@ paths: responses: "200": description: OK - /purchasedproducts: - 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 a touchpoint where customer logs in themselves - - name: X-HTM-CUSTOMER-PROFILE-ID-HEADER - in: header - schema: - type: string - example: feaaef83-a551-4283-8419-340b1ada3b55 - required: false - description: The customerProfileId of a customer in the case of the SMP - - name: X-HTM-ROLE-HEADER - in: header - schema: - type: string - example: Customer - required: false - - name: deviceId - in: query - description: Id of the device you want to get the purchased HTM products for. - schema: - type: string - format: uuid - - name: externalDeviceId - in: query - description: External id of the device you want to get the purchased HTM products for. - schema: - type: string - - name: ovpayTokenId - in: query - description: Id of the OVpay-token you want to get the purchased HTM products for. - schema: - type: string - format: uuid - get: - summary: Get a list of all purchased HTM products for a specific device or token of the given customer. At least one of the query parameters should be filled in. - description: |- - Get a list of all purchased HTM products for a specific device or token of the given customer. At least one of the query parametersshould be filled in. - Only HTM products are returned. - Where relevant, operations to be performed are returned as HATEOAS links per purchased product. - tags: - - Purchased Products - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/PurchasedProductsResponse" - examples: - getEmptyPurchasedProducts: - summary: No purchased products found - value: - purchasedProducts: { - "ovPayProducts":[], - "barcodeTickets": [], - "vouchers":[] - } - getTwoBarcodePurchasedProductsForDevice: - summary: Two BarcodeTicket purchased products, one PendingActivation and one Active - description: |- - The first ticket (PendingActivation) shows the 30-day range in which the ticket can be activated - (using the PATCH endpoint) in the validityStart and validityEnd fields. The second ticket (Active) - shows the actual validity period of the ticket after activation. - value: - { - "purchasedProducts":{ - "ovPayProducts":[], - "barcodeTickets":[ - { - "purchasedProductId": "0f0981bf-6d60-4b06-bc55-de1ba325f366", - "productId": 14, - "name": "HTM 2 uurskaart", - "status": "PendingActivation", - "productCategory": - { - "productCategoryId": 5, - "name": "Barcode", - }, - "orderId": "501B17EF-36C4-4039-B92C-6517969B464E", - "orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E", - "ticketReference": "KJj43nejhbTxhrfef287", - "serviceId": "DEF-4321-7654-7659", - "issuedAt": "2026-03-21T09:01:35", - "activatedAt": null, - "blocked": false, - "cancelledAt": null, - "validityStart": "2026-03-21T09:01:35", - "validityEnd": "2026-04-21T23:59:59", - "barcode": "barcodeBytes", - "externalDeviceId": "e2be51ae-2701-4803-a2d7-97d4b714482d", - "_links": { - "get_order": { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E", - "method": "GET" - }, - "patch_purchasedproduct": { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/purchasedproducts/0f0981bf-6d60-4b06-bc55-de1ba325f366", - "method": "PATCH" - } - } - }, - { - "purchasedProductId": "0f0981bf-6d60-4b06-bc55-de1ba325f366", - "productId": 14, - "name": "HTM 2 uurskaart", - "status": "Active", - "productCategory": - { - "productCategoryId": 5, - "name": "Barcode", - }, - "orderId": "501B17EF-36C4-4039-B92C-6517969B464E", - "orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E", - "ticketReference": "KJj43nejhbTxhr897287", - "serviceId": "ABC-1234-7654-8945", - "issuedAt": "2026-03-21T10:01:12", - "activatedAt": "2026-03-21T12:45:01", - "blocked": false, - "cancelledAt": null, - "validityStart": "2026-03-21T12:45:01", - "validityEnd": "2026-03-21T14:45:01", - "barcode": "barcodeBytes", - "externalDeviceId": "e2be51ae-2701-4803-a2d7-97d4b714482d", - "_links": { - "get_order": { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E", - "method": "GET" - } - } - } - ], - "vouchers":[] - } - } - getSingleOvpayPurchasedProductForSpecificOvPayToken: - summary: One Ovpay purchased product - value: - { - "purchasedProducts":{ - "ovPayProducts":[ { - "purchasedProductId": "26d41861-f77e-4666-9cde-2c5c66ace0a2", - "productId": 1, - "name": "HTM 90% Korting", - "status": "Active", - "isRenewable": true, - "productCategory": - { - "productCategoryId": 1, - "name": "Kortingsabonnement", - }, - "fromInclusive": "2024-11-25T13:25:00+01:00", - "untilInclusive": "2024-12-25T03:59:59+01:00", - "orderId": "501B17EF-36C4-4039-B92C-6517969B464E", - "orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E", - "contractId": "56B17EF-C436-9043-B76C-481797WEB464F", - "ovPayTokenId": 42, - "_links": - { - "get_order": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E", - "method": "GET", - }, - "get_contract": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/contracts/56B17EF-C436-9043-B76C-481797WEB464F", - "method": "GET", - }, - }, - }, - ], - "barcodeTickets":[], - "vouchers":[] - } - } - getSingleVoucherPurchasedProductForCustomer: - summary: One voucher purchased product - value: - { - "purchasedProducts":{ - "ovPayProducts":[], - "barcodeTickets":[], - "vouchers":[ - { - "purchasedProductId": "07a55d42-ea42-4f5c-896a-b340ab084309", - "productId": 81, - "name": "HTM ooivaarspas voucher", - "productCategory": - { - "productCategoryId": 9, - "name": "Voucher", - }, - "voucherCode": "HTM45253", - "fromInclusive": "2026-01-01T00:00:00", - "untilInclusive": "2026-12-31T23:59:99", - "voucherStatus": { - "voucherStatusId": 2, - "name": "issued" - }, - "mandatoryCustomerDataItems": - [ - { - "mandatoryCustomerDataItemId": 8, - "customerDataItem": "padBirthDate", - }, - { - "mandatoryCustomerDataItemId": 4, - "customerDataItem": "emailAddress", - }, - ] - } - ] - } - } - /purchasedproducts/{purchasedProductId}: - 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 a touchpoint where customer logs in themselves - - name: X-HTM-CUSTOMER-PROFILE-ID-HEADER - in: header - schema: - type: string - example: feaaef83-a551-4283-8419-340b1ada3b55 - required: false - description: The customerProfileId of a customer in the case of the SMP - - name: X-HTM-ROLE-HEADER - in: header - schema: - type: string - example: Customer - required: false - - name: purchasedProductId - in: path - required: true - style: simple - description: Id of the purchased product you want to change - schema: - type: string - format: uuid - example: 0f0981bf-6d60-4b06-bc55-de1ba325f366 - patch: - summary: Update a purchased product - description: |- - Update the given purchased product. Currently only used to activate a barcode ticket. - tags: - - Purchased Products - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/unavailable" - examples: - Activate a TapConnect purchased product: - value: - { - "status": "Active" - } - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/PurchasedProductsResponse" - examples: - Activate a TapConnect purchased product: - summary: Activate a TapConnect purchased product - value: - { - "purchasedProducts": { - "ovPayProducts": [], - "barcodeTickets": [ - { - "purchasedProductId": "0f0981bf-6d60-4b06-bc55-de1ba325f366", - "productId": 14, - "name": "HTM 2 uurskaart", - "status": "Active", - "productCategory": { - "productCategoryId": 5, - "name": "Barcode" - }, - "orderId": "501B17EF-36C4-4039-B92C-6517969B464E", - "orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E", - "ticketReference": "KJj43nejhbTxhr897287", - "serviceId": "ABC-1234-7654-8945", - "issuedAt": "2026-03-21T10:01:12", - "activatedAt": "2026-03-21T12:45:01", - "blocked": false, - "cancelledAt": null, - "validityStart": "2026-03-21T12:45:01", - "validityEnd": "2026-03-21T14:45:01", - "barcode": "barcodeBytes", - "externalDeviceId": "e2be51ae-2701-4803-a2d7-97d4b714482d", - "_links": { - "get_order": { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E", - "method": "GET" - } - } - } - ], - "vouchers": [] - } - } components: schemas: unavailable: @@ -4108,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 @@ -4174,329 +3871,21 @@ 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 example: GET - PurchasedProductsResponse: - type: object - required: - - purchasedProducts - properties: - purchasedProducts: - type: object - required: - - ovPayProducts - - barcodeTickets - - vouchers - properties: - ovPayProducts: - type: array - items: - type: object - required: - - purchasedProductId - - productId - - name - - status - - isRenewable - - productCategory - - fromInclusive - - orderId - - orderLineId - - _links - properties: - purchasedProductId: - type: string - format: uuid - example: 0f0981bf-6d60-4b06-bc55-de1ba325f366 - productId: - type: integer - example: 1 - name: - type: string - example: HTM 90% Korting - status: - type: string - enum: ["Active", "Ended", "Refunded"] - example: Active - isRenewable: - type: boolean - example: true - productCategory: - type: object - description: The category of the originating HTM product definition - properties: - productCategoryId: - type: integer - example: 1 - name: - type: string - example: Kortingsabonnement - fromInclusive: - type: string - format: date-time-offset - example: "2024-11-25T13:25:00+01:00" - untilInclusive: - type: string - format: date-time-offset - description: >- - If not present, this purchased product represents a subscription/contract without a real end date. If present, it can be either the natural end date or the refund timestamp. - example: "2024-12-25T03:59:59+01:00" - orderId: - type: string - format: uuid - example: 501B17EF-36C4-4039-B92C-6517969B464E - orderLineId: - type: string - format: uuid - example: 38B17EF-36C4-4039-B92C-4817969B464E - contractId: - type: string - format: uuid - example: 56B17EF-C436-9043-B76C-481797WEB464F - description: Only present for subscriptions/contracts - _links: - type: object - properties: - self: - type: object - properties: - href: - type: string - example: https://api.integratielaag.nl/abt/touchpoint/1.0/purchasedproducts - method: - type: string - example: GET - get_order: - type: object - properties: - href: - type: string - description: Always present for any HTM purchased product - example: https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E - method: - type: string - example: GET - get_contract: - type: object - 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 - example: GET - barcodeTickets: - type: array - items: - type: object - required: - - purchasedProductId - - productId - - name - - status - - productCategory - - orderId - - orderLineId - - ticketReference - - serviceId - - issuedAt - - blocked - - validityStart - - validityEnd - - _links - properties: - purchasedProductId: - type: string - format: uuid - example: 0f0981bf-6d60-4b06-bc55-de1ba325f366 - productId: - type: integer - example: 1 - name: - type: string - example: HTM 2 uurskaart - status: - type: string - enum: ["PendingActivation", "Active", "Ended", "Blocked", "Refunded"] - example: Active - productCategory: - type: object - description: The category of the originating HTM product definition - properties: - productCategoryId: - type: integer - example: 5 - name: - type: string - example: Barcode - orderId: - type: string - format: uuid - example: 501B17EF-36C4-4039-B92C-6517969B464E - orderLineId: - type: string - format: uuid - example: 38B17EF-36C4-4039-B92C-4817969B464E - ticketReference: - type: string - example: KJj43nejhbTxhr897287 - serviceId: - type: string - example: ABC-1234-7654-8945 - issuedAt: - type: string - format: date-time-offset - example: "2024-11-25T13:25:00+01:00" - activatedAt: - type: string - format: date-time-offset - description: Only present for active and ended barcode tickets - example: "2024-11-25T13:25:00+01:00" - blocked: - type: boolean - example: false - cancelledAt: - type: string - format: date-time-offset - example: "2024-11-25T13:25:00+01:00" - validityStart: - description: |- - The date-time at which the ticket will become valid for traveling. The ticket will not be valid before this date. - For tickets that require activation: Before activation this field will show the lower bound of the range in which - a ticket can be activated, after activation the value of this field is updated to the final start of the validity - range. For example: a 1 hour product that has to be activated within 7 days. Before ticket activation (activatedAt - field returns null) this value (together with validityEnd) will return the 7 day range, after activation (activatedAt - field returns a date-time) the value will show the start of the final 1 hour validity range. - type: string - format: date-time-offset - example: "2024-11-25T13:25:00+01:00" - validityEnd: - description: |- - The date-time at which the ticket will become valid for traveling. The ticket will not be valid before this date. - For tickets that require activation: Before activation this field will show the upper bound of the range in which - a ticket can be activated, after activation the value of this field is updated to the final end of the validity - range. For example: a 1 hour product that has to be activated within 7 days. Before ticket activation (activatedAt - field returns null) this value (together with validityStart) will return the 7 day range, after activation (activatedAt - field returns a date-time) the value will show the end of the final 1 hour validity range. - type: string - format: date-time-offset - example: "2024-11-25T15:25:00+01:00" - barcode: - type: string - example: barcodeBytes - externalDeviceId: - type: string - example: e2be51ae-2701-4803-a2d7-97d4b714482d - _links: - type: object - properties: - self: - type: object - properties: - href: - type: string - example: https://api.integratielaag.nl/abt/touchpoint/1.0/purchasedproducts - method: - type: string - example: GET - get_order: - type: object - properties: - href: - type: string - description: Always present for any HTM purchased product - example: https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E - method: - type: string - example: GET - patch_purchasedproduct: - type: object - properties: - href: - type: string - description: Only present for purchased products that are PATCHable - example: https://api.integratielaag.nl/abt/touchpoint/1.0/purchasedproducts/56B17EF-C436-9043-B76C-481797WEB464F - method: - type: string - example: PATCH - vouchers: - type: array - items: - type: object - required: - - purchasedProductId - - productId - - name - - productCategory - - voucherCode - - fromInclusive - - voucherStatus - properties: - purchasedProductId: - type: string - format: uuid - example: 0f0981bf-6d60-4b06-bc55-de1ba325f366 - productId: - type: integer - example: 81 - name: - type: string - example: HTM ooivaarspas voucher - productCategory: - type: object - description: The category of the originating HTM product definition - properties: - productCategoryId: - type: integer - example: 6 - name: - type: string - example: Voucher - voucherCode: - type: string - example: HKV-A7J-128-PYT - fromInclusive: - type: string - format: date-time-offset - example: "2024-11-25T13:25:00+01:00" - untilInclusive: - type: string - format: date-time-offset - example: "2024-12-25T03:59:59+01:00" - voucherStatus: - type: object - properties: - voucherStatusId: - type: integer - example: 2 - name: - type: string - example: issued - mandatoryCustomerDataItems: - type: array - items: - type: object - properties: - mandatoryCustomerDataItemId: - type: integer - example: 4 - customerDataItem: - type: string - example: emailAddress