OVPAY-810 Contracts CRUD API spec init.

This commit is contained in:
Boterman B (Bas) 2024-07-12 16:07:01 +02:00
commit b72bfddcb9

View File

@ -0,0 +1,743 @@
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/{customerProfileId}/contracts/:
parameters:
- in: path
name: customerProfileId
schema:
type: integer
required: true
description: The id of the CustomerProfile.
get:
description: List all contracts for a certail customer profile.
tags:
- Contract
parameters:
- in: query
name: contractStatusId
schema:
type: integer
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:
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/{contractId}:
parameters:
- in: path
name: contractId
schema:
type: string
format: uuid
required: true
description: The contractId of the Contract, formatted as UUID.
get:
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": "WEFACT-123456",
"term": 1,
"created": "2024-07-02 15:01:00.000",
"updated": "2024-07-02 15:01:00.000",
"state": "invoice_created",
"data": "{json}",
},
],
},
}
patch:
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: CREATED
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
required: true
description: The contractId of the Contract, formatted as UUID.
post:
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
required: true
description: The contractId of the Contract, formatted as UUID.
- in: path
name: contractVersionId
schema:
type: integer
required: true
description: The id of the ContractVersion, formatted as UUID.
patch:
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
required: true
description: The contractId of the Contract, formatted as UUID.
post:
description: Add an invoice to an existing contract.
tags:
- ContractInvoice
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/ContractInvoice"
example:
{
"contractInvoice":
{
"externalReference": "WEFACT-123456",
"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/{contractInvoiceId}:
parameters:
- in: path
name: contractInvoiceId
schema:
type: string
format: uuid
required: true
description: The id of the ContractInvoice, formatted as UUID.
patch:
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
required: true
description: The contractId of the Contract, formatted as UUID.
post:
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:
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:
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: WEFACT-123456
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