openapi: "3.0.3" info: title: ABT Contracts CRUD APIs version: "1.0" description: CRUD APIs for ABT Contract database. These are NOT the functional APIs from Service Engine. servers: - url: https://api.integratielaag.nl/v1 paths: /customers/{customerNumber}/contracts/: parameters: - in: path name: customerNumber schema: type: integer example: 1001337 required: true description: The customerNumber. get: summary: List all contracts for a certain customer profile. description: List all contracts for a certain customer profile. tags: - Contract parameters: - in: query name: contractStatusId schema: type: integer example: 1 required: false description: Filter on possible contract status. 1 = new, 2 = active, 3 = suspended, 4 = cancelled, 5 = terminated. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Contract" example: { "contracts": [ { "contractId": "5a3876a1-e9a1-4278-8983-4679a8d583c2", "contractNumber": "D123456", "customerProfileId": "bfe6174e-52aa-4fd7-927b-7802256bc054", "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, "xSpit": "1c345237-4d84-47f0-93c2-7b94338e3355", "created": "2024-08-01 15:01:00.000", }, { "contractId": "f07253e6-c364-474c-a342-a10a4a7cf305", "contractNumber": "D123456", "customerProfileId": "bfe6174e-52aa-4fd7-927b-7802256bc054", "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, "xSpit": "1c345237-4d84-47f0-93c2-7b94338e3355", "created": "2024-08-01 15:01:00.000", }, ], } post: summary: Create a contract for an existing customer profile. description: Create a contract for an existing customer profile. tags: - Contract requestBody: content: application/json: schema: $ref: "#/components/schemas/Contract" example: { "contract": { "orderId": "eb3d08f7-7feb-4f31-9f5b-daa634e51f48", "orderLineId": "52efbbfc-8c28-4016-9ece-dc3ef9a70bd8", "touchpointId": 2, "contractStatusId": 1, "productId": 1, "productName": "HTM Maand 20% korting", "termDuration": "P0Y1M0D", "billingDay": 15, "highestInvoiceTerm": 0, "xSpit": "1c345237-4d84-47f0-93c2-7b94338e3355", "contractVersions": [ { "termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/", "termAmountExclTax": 1200, "taxCode": "V21", "taxAmount": 108, "termAmountInclTax": 1308, "start": "2024-07-04 15:01:00.000", "end": "", }, ], "contractActions": [ { "actionTypeId": 1, "user": "subid123456", "details": "Contract created", "correlationId": "976e7a4c-bf24-43d2-b444-55817556e7ee", }, ], }, } responses: "201": description: CREATED content: application/json: schema: $ref: "#/components/schemas/Contract" example: { "contract": { "contractId": "5a3876a1-e9a1-4278-8983-4679a8d583c2", "contractNumber": "123456", }, } /contracts: get: summary: Get all contracts. description: Get all contracts. tags: - Contract parameters: - in: query name: contractStatusId schema: type: array items: type: integer explode: false required: false description: Filter on possible contract status. 1 = new, 2 = active, 3 = suspended, 4 = cancelled, 5 = terminated. - in: query name: billingDay schema: type: integer example: 13 required: false description: Filter on billingDay. In case of weekly termDuration, Sunday = 0, Monday = 1, etc. - in: query name: termDuration schema: type: string example: P1M required: false description: Filter on termDuration. - in: query name: invoiceLimit schema: type: integer example: 2 required: false description: Number of invoices to include in response body (per contract). - in: query name: pageSize schema: type: integer example: 2 required: false description: Number of contracts to in the response body (per page). responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Contract" example: { "contracts": [ { "contractId": "5a3876a1-e9a1-4278-8983-4679a8d583c2", "contractNumber": "D123456", "customerProfileId": "bfe6174e-52aa-4fd7-927b-7802256bc054", "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, "xSpit": "1c345237-4d84-47f0-93c2-7b94338e3355", "contractInvoices": [ { "contractInvoiceId": "8699d72a-cf4d-4e6b-9e9c-549d837ca51f", "externalReference": "F2024-0001", "term": 1, "created": "2024-06-02 15:01:00.000", "updated": "2024-06-02 15:01:00.000", "state": "invoice_created", }, { "contractInvoiceId": "1c345237-4d84-47f0-93c2-7b94338e3355", "externalReference": "F2024-0002", "term": 2, "created": "2024-07-02 15:01:00.000", "updated": "2024-07-02 15:01:00.000", "state": "invoice_created", }, ], "contractVersions": [ { "contractVersionId": 1, "termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/", "termAmountExclTax": 1200, "taxCode": "V21", "taxAmount": 108, "termAmountInclTax": 1308, "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/", "termAmountExclTax": 1300, "taxCode": "V21", "taxAmount": 117, "termAmountInclTax": 1417, "start": "2025-01-01 15:01:00.000", }, ], }, { "contractId": "f07253e6-c364-474c-a342-a10a4a7cf305", "contractNumber": "D123456", "customerProfileId": "bfe6174e-52aa-4fd7-927b-7802256bc054", "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, "xSpit": "1c345237-4d84-47f0-93c2-7b94338e3355", "contractInvoices": [ { "contractInvoiceId": "8699d72a-cf4d-4e6b-9e9c-549d837ca51f", "externalReference": "F2024-0003", "term": 1, "created": "2024-06-02 15:01:00.000", "updated": "2024-06-02 15:01:00.000", "state": "invoice_created", }, { "contractInvoiceId": "1c345237-4d84-47f0-93c2-7b94338e3355", "externalReference": "F2024-0004", "term": 2, "created": "2024-07-02 15:01:00.000", "updated": "2024-07-02 15:01:00.000", "state": "invoice_created", }, ], "contractVersions": [ { "contractVersionId": 1, "termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/", "termAmountExclTax": 1200, "taxCode": "V21", "taxAmount": 108, "termAmountInclTax": 1308, "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/", "termAmountExclTax": 1300, "taxCode": "V21", "taxAmount": 117, "termAmountInclTax": 1417, "start": "2025-01-01 15:01:00.000", }, ], }, ], } /contracts/{contractId}: parameters: - in: path name: contractId schema: type: string format: uuid example: d1dd439b-6072-4b97-89c9-724268865b93 required: true description: The contractId of the Contract, formatted as UUID. get: summary: Get contract details of a single contract. description: Get contract details of a single contract. tags: - Contract responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Contract" example: { "contract": { "contractId": "5a3876a1-e9a1-4278-8983-4679a8d583c2", "contractNumber": "D123456", "customerProfileId": "bfe6174e-52aa-4fd7-927b-7802256bc054", "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, "xSpit": "1c345237-4d84-47f0-93c2-7b94338e3355", "contractVersions": [ { "contractVersionId": 1, "termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/", "termAmountExclTax": 1200, "taxCode": "V21", "taxAmount": 108, "termAmountInclTax": 1308, "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/", "termAmountExclTax": 1300, "taxCode": "V21", "taxAmount": 117, "termAmountInclTax": 1417, "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, "created": "2024-07-02 15:01:00.000", "updated": "2024-07-02 15:01:00.000", "state": "invoice_created", "data": "{json}", }, ], }, } patch: summary: Update an existing contract. description: Update an existing contract. tags: - Contract requestBody: content: application/json: schema: $ref: "#/components/schemas/Contract" example: { "contract": { "contractStatusId": 2, "productId": 1, "productName": "HTM 20% korting 2024", "billingDay": 15, "highestInvoiceTerm": 2, "xSpit": "1c345237-4d84-47f0-93c2-7b94338e3355", }, } responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Contract" example: { "contract": { "contractId": "5a3876a1-e9a1-4278-8983-4679a8d583c2", "contractNumber": "123456", }, } /contracts/{contractId}/contractversions: parameters: - in: path name: contractId schema: type: string format: uuid example: d1dd439b-6072-4b97-89c9-724268865b93 required: true description: The contractId of the Contract, formatted as UUID. post: summary: Add a version to an existing contract. description: Add a version to an existing contract. tags: - ContractVersion requestBody: content: application/json: schema: $ref: "#/components/schemas/ContractVersion" example: { "contractVersion": { "termsAndConditions": "https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/", "termAmountExclTax": 1200, "taxCode": "V21", "taxAmount": 108, "termAmountInclTax": 1308, "start": "2024-07-08 15:01:00.000", "end": "", }, } responses: "201": description: CREATED content: application/json: schema: $ref: "#/components/schemas/ContractVersion" example: { "contractVersion": { "contractId": "5a3876a1-e9a1-4278-8983-4679a8d583c2", "contractVersionId": 2, }, } /contracts/{contractId}/contractversions/{contractVersionId}: parameters: - in: path name: contractId schema: type: string format: uuid example: d1dd439b-6072-4b97-89c9-724268865b93 required: true description: The contractId of the Contract, formatted as UUID. - in: path name: contractVersionId schema: type: integer example: 1 required: true description: The id of the ContractVersion, formatted as UUID. patch: summary: Add an existing contract version. description: Add an existing contract version. tags: - ContractVersion requestBody: content: application/json: schema: $ref: "#/components/schemas/ContractVersion" example: { "contractVersion": { "end": "2024-07-03 15:01:00.000" } } responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ContractVersion" example: { "contractVersion": { "contractId": "5a3876a1-e9a1-4278-8983-4679a8d583c2", "contractVersionId": 1, }, } /contracts/{contractId}/contractinvoices: parameters: - in: path name: contractId schema: type: string format: uuid example: d1dd439b-6072-4b97-89c9-724268865b93 required: true description: The contractId of the Contract, formatted as UUID. get: summary: Get invoices of a single contract. description: Get invoices of a single contract. deprecated: true tags: - ContractInvoice responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ContractInvoice" example: { "contractInvoices": [ { "contractInvoiceId": "8699d72a-cf4d-4e6b-9e9c-549d837ca51f", "externalReference": "F2024-0001", "term": 1, "created": "2024-07-02 15:01:00.000", "updated": "2024-07-02 15:01:00.000", "state": "invoice_sent", "data": "{json}", }, { "contractInvoiceId": "dadff658-4ff5-4eb8-b516-492f1f6c6245", "externalReference": "F2024-0002", "term": 2, "created": "2024-08-02 15:01:00.000", "updated": "2024-08-02 15:01:00.000", "state": "invoice_created", "data": "{json}", }, ], } post: summary: Add an invoice to an existing contract. description: Add an invoice to an existing contract. tags: - ContractInvoice requestBody: content: application/json: schema: $ref: "#/components/schemas/ContractInvoice" example: { "contractInvoice": { "externalReference": "F2024-0001", "term": 1, "created": "2024-07-02 15:01:00.000", "updated": "2024-07-02 15:01:00.000", "state": "invoice_created", "data": "{json}", }, } responses: "201": description: CREATED content: application/json: schema: $ref: "#/components/schemas/ContractInvoice" example: { "contractInvoice": { "contractInvoiceId": "8699d72a-cf4d-4e6b-9e9c-549d837ca51f", }, } /contractinvoices: get: summary: Get all contract invoices. description: Get all contract invoices. tags: - ContractInvoice parameters: - in: query name: externalReference schema: type: string example: F2024-0030 required: false description: External reference of the invoice. - in: query name: term schema: type: integer example: 4 required: false description: Term of the invoice. - in: query name: createdFrom schema: type: string format: date-time example: 2024-06-02 15:01:00.000 required: false description: Billing date of the invoice (from). - in: query name: createdUntil schema: type: string format: date-time example: 2024-06-02 15:01:00.000 required: false description: Billing date of the invoice (until). - in: query name: updatedFrom schema: type: string format: date-time example: 2024-06-02 15:01:00.000 required: false description: Updated timestamp of the invoice (from). - in: query name: updatedUntil schema: type: string format: date-time example: 2024-06-02 15:01:00.000 required: false description: Updated timestamp of the invoice (until). - in: query name: state schema: type: string example: created required: false description: Invoice state. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Contract" example: { "contractInvoices": [ { "contractInvoiceId": "8699d72a-cf4d-4e6b-9e9c-549d837ca51f", "externalReference": "F2024-0030", "term": 1, "created": "2024-06-02 15:01:00.000", "updated": "2024-06-02 15:01:00.000", "state": "invoice_created", }, ], } /contractinvoices/{contractInvoiceId}: parameters: - in: path name: contractInvoiceId schema: type: string format: uuid example: d1dd439b-6072-4b97-89c9-724268865b93 required: true description: The id of the ContractInvoice, formatted as UUID. patch: summary: Update an existing invoice. description: Update an existing invoice. tags: - ContractInvoice requestBody: content: application/json: schema: $ref: "#/components/schemas/ContractInvoice" example: { "contractInvoice": { "updated": "2024-07-02 15:01:00.000", "state": "invoice_reopened", "data": "{json}", }, } responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ContractInvoice" example: { "contractInvoice": { "contractInvoiceId": "8699d72a-cf4d-4e6b-9e9c-549d837ca51f", }, } /contracts/{contractId}/contractactions: parameters: - in: path name: contractId schema: type: string format: uuid example: d1dd439b-6072-4b97-89c9-724268865b93 required: true description: The contractId of the Contract, formatted as UUID. get: summary: Get all actions of a single contract. description: Get all actions of a single contract. deprecated: true tags: - ContractAction responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Contract" example: { "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", }, ], } post: summary: Add a new action to an existing contract. description: Add a new action to an existing contract. tags: - ContractAction requestBody: content: application/json: schema: $ref: "#/components/schemas/ContractAction" example: { "contractAction": { "actionType": 2, "user": "subid123456", "timestamp": "2024-07-02 15:01:00.000", "details": "Contract changed xyz", "correlationId": "976e7a4c-bf24-43d2-b444-55817556e7ee", }, } responses: "201": description: CREATED content: application/json: schema: $ref: "#/components/schemas/ContractAction" example: { "contractAction": { "contractActionId": "8699d72a-cf4d-4e6b-9e9c-549d837ca51f", }, } /contractstatuses: get: summary: Return a list of all possible values of the ContractStatus reference table. Used for populating drop down lists for example. description: Return a list of all possible values of the ContractStatus reference table. Used for populating drop down lists for example. tags: - Reference Tables responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ContractStatus" example: { "contractStatuses": [ { "contractStatusId": 1, "name": "new" }, { "contractStatusId": 2, "name": "active" }, { "contractStatusId": 3, "name": "suspended" }, { "contractStatusId": 4, "name": "cancelled" }, { "contractStatusId": 5, "name": "terminated" }, ], } /actiontypes: get: summary: Return a list of all possible values of the ActionType reference table. Used for populating drop down lists for example. description: Return a list of all possible values of the ActionType reference table. Used for populating drop down lists for example. tags: - Reference Tables responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ContractStatus" example: { "actionTypes": [ { "contractActionId": 1, "name": "create" }, { "contractActionId": 2, "name": "change" }, { "contractActionId": 3, "name": "cancel" }, { "contractActionId": 4, "name": "suspend" }, { "contractActionId": 5, "name": "terminate" }, { "contractActionId": 6, "name": "renew" }, { "contractActionId": 7, "name": "invoice" }, ], } components: securitySchemes: bearerToken: type: http scheme: bearer bearerFormat: JWT schemas: Contract: type: object properties: contractId: type: string format: uuid example: 5a3876a1-e9a1-4278-8983-4679a8d583c2 contractNumber: type: string pattern: '^D\d{6}$' example: D123456 customerProfileId: type: string format: uuid example: bfe6174e-52aa-4fd7-927b-7802256bc054 orderId: type: string format: uuid example: eb3d08f7-7feb-4f31-9f5b-daa634e51f48 orderLineId: type: string format: uuid example: 52efbbfc-8c28-4016-9ece-dc3ef9a70bd8 touchpointId: type: integer example: 2 contractStatus: type: object $ref: "#/components/schemas/ContractStatus" productId: type: integer example: 1 productName: type: string example: HTM Maand 20% korting termDuration: type: string format: ISO8601 example: P0Y1M0D billingDay: type: integer example: 15 highestInvoiceTerm: type: integer example: 1 xSpit: type: string format: uuid example: 1c345237-4d84-47f0-93c2-7b94338e3355 contractVersions: type: array items: $ref: "#/components/schemas/ContractVersion" minItems: 0 contractActions: type: array items: $ref: "#/components/schemas/ContractAction" minItems: 0 contractInvoices: type: array items: $ref: "#/components/schemas/ContractInvoice" minItems: 0 Contracts: type: object properties: contracts: type: array items: $ref: "#/components/schemas/Contract" minItems: 0 ContractAction: type: object properties: contractActionId: type: string format: uuid example: 67687851-59dd-4bbc-aa74-0f7abd26c883 actionType: type: object $ref: "#/components/schemas/ActionType" user: type: string example: subid123456 timestamp: type: string format: date-time example: 2024-07-02 15:01:00.000 details: type: string example: Contract created correlationId: type: string format: uuid example: 976e7a4c-bf24-43d2-b444-55817556e7ee ContractVersion: type: object properties: contractVersionId: type: integer example: 1 termsAndConditions: type: string format: url example: https://www.htm.nl/reisproducten/productvoorwaarden/htm-maandkorting/ termAmountExclTax: type: integer example: 1200 taxCode: type: string example: V21 taxAmount: type: integer example: 108 termAmountInclTax: type: integer example: 1308 start: type: string format: date-time example: 2024-07-04 15:01:00.000 end: type: string format: date-time example: 2024-12-31 15:01:00.000 ContractInvoice: type: object properties: contractInvoiceId: type: string format: uuid example: 8699d72a-cf4d-4e6b-9e9c-549d837ca51f externalReference: type: string example: F2024-0001 term: type: integer example: 1 created: type: string format: date-time example: 2024-07-02 15:01:00.000 updated: type: string format: date-time example: 2024-07-02 15:01:00.000 state: type: string example: invoice_created data: type: string format: json example: { json } ContractStatus: type: object properties: contractStatusId: type: integer example: 2 name: type: string enum: [new, active, suspended, cancelled, terminated] example: active ActionType: type: object properties: actionTypeId: type: integer example: 1 name: type: string enum: [create, change, cancel, suspend, terminate, renew, invoice] example: create