From 105e81b5c4aff0b43e21d5f4cc9bbee439559d97 Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Mon, 23 Feb 2026 14:42:07 +0100 Subject: [PATCH] OVPAY-2201 - Added endpoints for contract changes. --- src/openapi/contracts/contracts-se.yaml | 272 +++++++++++++++++++++++- 1 file changed, 269 insertions(+), 3 deletions(-) diff --git a/src/openapi/contracts/contracts-se.yaml b/src/openapi/contracts/contracts-se.yaml index 48509a6..83c4745 100644 --- a/src/openapi/contracts/contracts-se.yaml +++ b/src/openapi/contracts/contracts-se.yaml @@ -386,10 +386,10 @@ paths: "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, @@ -574,6 +574,272 @@ 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: + { + "changeMoments": + [ + { + "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-01 15:01:00.000", + "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-01 15:01:00.000", + "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