openapi: "3.0.3"
info:
  title: ABT Contracts Service Engine APIs v2
  version: "1.0"
  description: Service Engine APIs for ABT Contracts v2. These are NOT the CRUD APIs to the data hub.
servers:
  - url: https://services.acc.api.htm.nl/abt/touchpoint/1.0
paths:
  /customers/contracts:
    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.
    get:
      summary: List all contracts for a certain customer profile.
      description: List all contracts for a certain customer profile.
      tags:
        - SE Contracts v2
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unavailable"
              examples:
                List all contracts for a single customer profile:
                  summary: List all contracts for a single customer profile
                  description: |
                    List all contracts for single customer profile with customer
                    number 'D123456'.
                  value:
                    [
                      {
                        "contractId": "5a3876a1-e9a1-4278-8983-4679a8d583c2",
                        "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,
                        "_links":
                          {
                            "get_token":
                              {
                                "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens?ovPayTokenId=1337",
                                "method": "GET",
                              },
                          },
                      },
                      {
                        "contractId": "f07253e6-c364-474c-a342-a10a4a7cf305",
                        "contractNumber": "D123456",
                        "customerProfileId": 42,
                        "orderId": "945d43e6-516e-425b-8847-9aba41289acd",
                        "orderLineId": "42f68042-908f-41f4-9d9b-4cab843ff0e8",
                        "touchpointId": 2,
                        "contractStatus":
                          { "contractStatusId": 1, "name": "new" },
                        "productId": 1,
                        "productName": "HTM Maand 20% korting",
                        "termDuration": "P0Y1M0D",
                        "billingDay": 15,
                        "highestInvoiceTerm": 1,
                        "created": "2024-08-01 15:01:00.000",
                        "ovPayTokenId": 1338,
                        "_links":
                          {
                            "get_token":
                              {
                                "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens?ovPayTokenId=1338",
                                "method": "GET",
                              },
                          },
                      },
                    ]
  /customers/contracts/{contractId}:
    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: contractId
        schema:
          type: string
          format: uuid
          example: 9e224750-3065-471d-af57-85b9cffa7c89
        required: true
        description: The id of the contract to process.
    get:
      summary: Get contract details for a certain customer profile.
      description: Get contract details for a certain customer profile.
      tags:
        - SE Contracts v2
      parameters:
        - in: query
          name: versionLimit
          schema:
            type: integer
            example: 2
          required: false
          description: Limit the number of contract versions in the response body to this number. Contract versions are ordered by start date (descending).
        - in: query
          name: invoiceLimit
          schema:
            type: integer
            example: 2
          required: false
          description: Limit the number of invoices in the response body to this number. Invoices are ordered by created date (descending).
        - in: query
          name: actionLimit
          schema:
            type: integer
            example: 2
          required: false
          description: Limit the number of actions in the response body to this number. Actions are ordered by created date (descending).
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unavailable"
              examples:
                Full contract details of a single contract:
                  summary: Full contract details of a single contract
                  description: |
                    Full contract details of a single contract with contract
                    number 'D123456'.
                  value:
                    {
                      "contractId": "5a3876a1-e9a1-4278-8983-4679a8d583c2",
                      "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,
                      "ovPayTokenId": 1337,
                      "contractVersions":
                        [
                          {
                            "contractVersionId": 1,
                            "termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
                            "productId": 1,
                            "productName": "HTM Maand 20% korting",
                            "taxCode": "V9",
                            "taxPercentage": 9.0,
                            "termAmountInclTax": 400,
                            "start": "2024-07-04 15:01:00.000",
                            "end": "2024-12-31 15:01:00.000",
                          },
                          {
                            "contractVersionId": 2,
                            "termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
                            "productId": 1,
                            "productName": "HTM Maand 20% korting",
                            "taxCode": "V9",
                            "taxPercentage": 9.0,
                            "termAmountInclTax": 400,
                            "start": "2025-01-01 15:01:00.000",
                          },
                        ],
                      "contractActions":
                        [
                          {
                            "contractActionId": "67687851-59dd-4bbc-aa74-0f7abd26c883",
                            "actionType":
                              { "actionTypeId": 1, "name": "create" },
                            "user": "subid123456",
                            "timestamp": "2024-07-02 15:01:00.000",
                            "details": "Contract created",
                            "correlationId": "976e7a4c-bf24-43d2-b444-55817556e7ee",
                          },
                          {
                            "contractActionId": "ea9ad287-9cd3-4e76-bcb9-d71db551cf55",
                            "actionType":
                              { "actionTypeId": 2, "name": "change" },
                            "user": "subid123456",
                            "timestamp": "2024-07-03 15:01:00.000",
                            "details": "Contract changed",
                            "correlationId": "e2462347-6749-4841-b42a-cf8de19ec727",
                          },
                        ],
                      "contractInvoices":
                        [
                          {
                            "contractInvoiceId": "8699d72a-cf4d-4e6b-9e9c-549d837ca51f",
                            "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",
                            "state": "invoice_created",
                            "data": "{json}",
                            "isCredit": false,
                          },
                        ],
                      "_links":
                        {
                          "get_token":
                            {
                              "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens?ovPayTokenId=1337",
                              "method": "GET",
                            },
                        },
                    }
  /customers/contracts/{contractId}/invoices:
    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: contractId
        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 invoices for a given contract.
      description: Get all invoices for a given contract.
      tags:
        - SE Contracts v2
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unavailable"
              examples:
                Get all invoices of a single contract:
                  summary: Get all invoices of a single contract
                  description: |
                    Get all invoices of a single contract with contract number
                    'D123456'.
                  value:
                    [
                      {
                        "contractInvoiceId": "8699d72a-cf4d-4e6b-9e9c-549d837ca51f",
                        "contractId": "9e224750-3065-471d-af57-85b9cffa7c89",
                        "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",
                        "state": "invoice_created",
                        "public_link": "http://mijnfactuurinzien.nl/F2024-0001",
                        "isCredit": false,
                      },
                      {
                        "contractInvoiceId": "0e729101-2c84-44db-8b18-d8f759e968e0",
                        "contractId": "9e224750-3065-471d-af57-85b9cffa7c89",
                        "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",
                        "state": "invoice_created",
                        "public_link": "http://mijnfactuurinzien.nl/F2024-0002",
                        "isCredit": false,
                      },
                    ]
  /contracts/{contractId}/cancellationmoments:
    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: contractId
        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 cancellation moments for a given contract.
      description: Get all cancellation moments for a given contract.
      tags:
        - SE Contract Cancellation v2
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unavailable"
              examples:
                All cancellation moments of a term bound contract:
                  summary: All cancellation moments of a term bound contract
                  description: |
                    All cancellation moments of a term bound contract.
                  value:
                    {
                      "cancellationMoment": "termBound",
                      "termDuration": "P1M",
                      "billingDay": 18,
                      "cancellationFrom": "2024-08-10T00:00:00",
                      "cancellationUntil": "2026-08-10T00:00:00",
                    }
  /contracts/{contractId}/cancellationvalidation:
    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: contractId
        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 cancellation for a given contract.
      description: Validate a cancellation for a given contract.
      tags:
        - SE Contract Cancellation v2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/unavailable"
            examples:
              Validate a cancellation of a given end date:
                summary: Validate a cancellation of a given end date
                description: |
                  Validate a cancellation of a given end date.
                value: { "end": "2024-08-10T00:00:00" }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unavailable"
              examples:
                Successfully validated cancellation:
                  summary: Successfully validated cancellation
                  description: |
                    Successfully validated a cancellation. The response contains
                    the refund amount and refund methods.
                  value:
                    {
                      "validationResult": true,
                      "validationMessage": "",
                      "end": "2024-08-10T03:59:59",
                      "refundAmount": 2489,
                      "refundMethods": ["creditInvoice", "iDeal"],
                    }
                Unsuccessful validation:
                  summary: Unsuccessful validation
                  description: |
                    Unsuccessful validation. The response contains the error message.
                  value:
                    {
                      "validationResult": false,
                      "validationMessage": "Cancellation end date not allowed",
                      "end": null,
                      "refundAmount": null,
                      "refundMethods": [],
                    }
  /contracts/{contractId}/cancellation:
    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: contractId
        schema:
          type: string
          format: uuid
          example: 9e224750-3065-471d-af57-85b9cffa7c89
        required: true
        description: The id of the contract to process.
    post:
      summary: Cancel a contract.
      description: Cancel a contract.
      tags:
        - SE Contract Cancellation v2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/unavailable"
            examples:
              Cancellation request for credit invoice:
                summary: Cancellation request for credit invoice
                description: |
                  Cancellation request for credit invoice.
                value:
                  {
                    "end": "2024-08-10T00:00:00",
                    "refundMethod": "creditInvoice",
                  }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unavailable"
              examples:
                Successfully cancelled contract:
                  summary: Successfully cancelled contract
                  description: |
                    Successfully cancelled a contract. The response contains
                    the refund amount and refund method.
                  value:
                    {
                      "end": "2024-08-10T03:59:59",
                      "refundAmount": 2489,
                      "refundMethod": "creditInvoice",
                    }
  /contracts/{contractId}/undocancellation:
    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: contractId
        schema:
          type: string
          format: uuid
          example: 9e224750-3065-471d-af57-85b9cffa7c89
        required: true
        description: The id of the contract to process.
    post:
      summary: Undo a pending cancellation of a contract.
      description: Undo a pending cancellation of a contract.
      tags:
        - SE Contract Cancellation v2
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unavailable"
              examples:
                Successfully undid cancellation of contract:
                  summary: Successfully undid pending cancellation
                  description: |
                    Successfully undid a pending cancellation of a contract. The contract
                    is active again.
                  value:
                    {
                      "contractId": "9e224750-3065-471d-af57-85b9cffa7c89",
                      "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,
                      "ovPayTokenId": 1337,
                      "contractVersions":
                        [
                          {
                            "contractVersionId": 1,
                            "termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
                            "productId": 1,
                            "productName": "HTM Maand 20% korting",
                            "taxCode": "V9",
                            "taxPercentage": 9.0,
                            "termAmountInclTax": 400,
                            "start": "2024-07-04 15:01:00.000",
                            "end": "2024-12-31 15:01:00.000",
                          },
                          {
                            "contractVersionId": 2,
                            "termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/",
                            "productId": 1,
                            "productName": "HTM Maand 20% korting",
                            "taxCode": "V9",
                            "taxPercentage": 9.0,
                            "termAmountInclTax": 400,
                            "start": "2025-01-01 15:01:00.000",
                          },
                        ],
                      "contractActions":
                        [
                          {
                            "contractActionId": "67687851-59dd-4bbc-aa74-0f7abd26c883",
                            "actionType":
                              { "actionTypeId": 1, "name": "create" },
                            "user": "subid123456",
                            "timestamp": "2024-07-02 15:01:00.000",
                            "details": "Contract created",
                            "correlationId": "976e7a4c-bf24-43d2-b444-55817556e7ee",
                          },
                          {
                            "contractActionId": "ea9ad287-9cd3-4e76-bcb9-d71db551cf55",
                            "actionType":
                              { "actionTypeId": 2, "name": "change" },
                            "user": "subid123456",
                            "timestamp": "2024-07-03 15:01:00.000",
                            "details": "Contract changed",
                            "correlationId": "e2462347-6749-4841-b42a-cf8de19ec727",
                          },
                        ],
                      "contractInvoices":
                        [
                          {
                            "contractInvoiceId": "8699d72a-cf4d-4e6b-9e9c-549d837ca51f",
                            "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",
                            "state": "invoice_created",
                            "data": "{json}",
                            "isCredit": false,
                          },
                        ],
                      "_links":
                        {
                          "get_token":
                            {
                              "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens?ovPayTokenId=1337",
                              "method": "GET",
                            },
                        },
                    }
  /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-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
        name: X-HTM-JWT-AUTH-HEADER
        schema:
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
        required: true
        description: The JWT of the logged in customer.
    get:
      summary: List all contract payments for a certain debtor.
      description: |
        List all contract payments for a certain debtor. The source of these payments is the accounts receivable management system (Payt).
      tags:
        - SE Contract Payments v2
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unavailable"
              examples:
                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":
                        [
                          {
                            "paymentId": "151845776",
                            "totalAmount": "26.62",
                            "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",
                                "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": "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",
                                  },
                              },
                          },
                          {
                            "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",
                                  },
                              },
                          },
                        ],
                    }
components:
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    unavailable:
      type: object
    rfc9457:
      type: object
      properties:
        type:
          type: string
          format: url
          example: https://example.com/probs/out-of-credit
        title:
          type: string
          example: You do not have enough credit.
        detail:
          type: string
          example: Your current balance is 30, but that costs 50.
        instance:
          type: string
          example: /account/12345/msgs/abc
        balance:
          type: string
          example: 30
        accounts:
          type: array
          items:
            type: string
            example:
              - /account/12345
              - /account/67890
