From 7a513612ba9ff0f5e3c0bf235e30989d525272aa Mon Sep 17 00:00:00 2001 From: Max Martens Date: Fri, 11 Oct 2024 15:54:04 +0200 Subject: [PATCH 1/2] FIKOReference v1 CRUD added (just 2 GET endpoints) Also added placeholder for v2 CRUD endpoints --- src/openapi/fiko/fikoreference-crud.yaml | 381 +++++++++++++++++++++++ 1 file changed, 381 insertions(+) create mode 100644 src/openapi/fiko/fikoreference-crud.yaml diff --git a/src/openapi/fiko/fikoreference-crud.yaml b/src/openapi/fiko/fikoreference-crud.yaml new file mode 100644 index 0000000..247747f --- /dev/null +++ b/src/openapi/fiko/fikoreference-crud.yaml @@ -0,0 +1,381 @@ +openapi: 3.0.1 +info: + title: ABTFikoReference + description: |- + CRUD APIs for FIKO reference data (based on the v1 model for FIKO, see [the FIKO v1 datamodel in Lucid](https://lucid.app/lucidchart/50c0ff9d-48ba-4ea9-8182-10bede07d3b1/edit?viewport_loc=145%2C-316%2C2782%2C1418%2C0_0&invitationId=inv_1cd35e35-77f5-4e31-87d6-32fd74400350)). This means that, for now, only GET endpoints on `TaxMetadata` and `ProductGroupMetadata` (already named `ProductMetadata` to avoid rework for v2) are available. \ + + When the v2 model for FIKO is implemented (see [the FIKO v2 datamodel in Lucid](https://lucid.app/lucidchart/50c0ff9d-48ba-4ea9-8182-10bede07d3b1/edit?viewport_loc=-72%2C-954%2C2406%2C1226%2CUnjZp4g0O~CK&invitationId=inv_1cd35e35-77f5-4e31-87d6-32fd74400350)), POST/PUT/DELETE for these tables (as well as CRUD for additional tables) will become available, to support populating the reference tables with Unit4Financials data.\ + + These are NOT functional API's to be published by the Service Engine, but are direct CRUD API's on top of the database. + version: '1.0' +servers: + - url: https://api.integratielaag.nl/abt/fikoreference/1.0 +tags: + - name: ABTFikoReference CRUD v1 + description: >- + CRUD APIs for FIKO reference data (based on the v1 model for FIKO, see [the FIKO v1 datamodel in Lucid](https://lucid.app/lucidchart/50c0ff9d-48ba-4ea9-8182-10bede07d3b1/edit?viewport_loc=145%2C-316%2C2782%2C1418%2C0_0&invitationId=inv_1cd35e35-77f5-4e31-87d6-32fd74400350)). + - name: ABTFikoReference CRUD v2 + description: >- + CRUD APIs for FIKO reference data (based on the v2 model for FIKO, see [the FIKO v2 datamodel in Lucid](https://lucid.app/lucidchart/50c0ff9d-48ba-4ea9-8182-10bede07d3b1/edit?viewport_loc=-72%2C-954%2C2406%2C1226%2CUnjZp4g0O~CK&invitationId=inv_1cd35e35-77f5-4e31-87d6-32fd74400350)). + +paths: + /taxmetadata: + get: + tags: + - ABTFikoReference CRUD v1 + summary: Get a list of all possible values of the "TaxMetadata" reference table. Mainly used for populating dropdown lists (in PMT for example). + description: |- + Get a list of all possible values of the `TaxMetadata` reference table. Mainly used for populating dropdown lists (in PMT for example).\ + The attributes `validFrom` and `validTo` are not yet present in the FIKO v1 datamodel, but are already included in this resourcemodel; to prevent rework in the near future.\ + For now, for `validFrom`, the value will always be returned as `2024-01-01T00:00:00.000+00:00` and for `validTo` it will always be `null`. + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/TaxMetadataListResponse' + examples: + getListTaxMetadataSales: + summary: List containing three TaxMetadata entries, used for sales tax + value: + { + "Entries": [ + { + "taxMetadataId": "61A148AF-6DCB-4BB6-9D3F-17A8B627F745", + "taxCode": "V21", + "taxPercentageAmount": 21, + "description": "BTW VERKOOP HOOG 21%", + "validFrom": "2024-01-01T00:00:00.000+00:00", + "validTo": null + }, + { + "taxMetadataId": "47C8972E-A730-4032-9BDA-AF0A5BCB2C85", + "taxCode": "V09", + "taxPercentageAmount": 9, + "description": "BTW VERKOOP LAAG 9%", + "validFrom": "2024-01-01T00:00:00.000+00:00", + "validTo": null + }, + { + "taxMetadataId": "AC20A838-C81B-4652-96EA-F6E79E696E9C", + "taxCode": "V0", + "taxPercentageAmount": 0, + "description": "BTW VERKOOP NUL", + "validFrom": "2024-01-01T00:00:00.000+00:00", + "validTo": null + } + ] + } + getListTaxMetadataSalesAndPurchase: + summary: List containing x TaxMetadata entries, used for sales and purchase tax + value: + { + "Entries": [ + { + "taxMetadataId": "61A148AF-6DCB-4BB6-9D3F-17A8B627F745", + "taxCode": "V21", + "taxPercentageAmount": 21, + "description": "BTW VERKOOP HOOG 21%", + "validFrom": "2024-01-01T00:00:00.000+00:00", + "validTo": null + }, + { + "taxMetadataId": "47C8972E-A730-4032-9BDA-AF0A5BCB2C85", + "taxCode": "V09", + "taxPercentageAmount": 9, + "description": "BTW VERKOOP LAAG 9%", + "validFrom": "2024-01-01T00:00:00.000+00:00", + "validTo": null + }, + { + "taxMetadataId": "AC20A838-C81B-4652-96EA-F6E79E696E9C", + "taxCode": "V0", + "taxPercentageAmount": 0, + "description": "BTW VERKOOP NUL", + "validFrom": "2024-01-01T00:00:00.000+00:00", + "validTo": null + }, + { + "TBD": "TBD" + }, + { + "TBD": "TBD" + }, + { + "TBD": "TBD" + } + ] + } + '400': + description: '400' + content: + application/json: + schema: + $ref: '#/components/schemas/400Response' + '401': + description: '401' + content: + application/json: + schema: + $ref: '#/components/schemas/401Response' + '404': + description: '404' + content: + application/json: + schema: + $ref: '#/components/schemas/404Response' + '500': + description: '500' + content: + application/json: + schema: + $ref: '#/components/schemas/500Response' + /productmetadata: + get: + tags: + - ABTFikoReference CRUD v1 + summary: Get a list of all possible values of the "ProductMetadata" reference table. Mainly used for populating dropdown lists (in PMT for example). + description: |- + Get a list of all possible values of the `ProductGroupMetadata` (soon to be renamed to `ProductMetadata`) reference table. Mainly used for populating dropdown lists (in PMT for example).\ + The name of the entity is `ProductGroupMetadata` in the FIKO v1 datamodel, but the resourcemodel already uses the name `ProductMetadata`, as will be the name from FIKO v2 onwards.\ + This also applies to the attributes `productMetadataId` (still called `ProductGroupMetadataId` in FIKO v1), `productCode` (still called `productGroupCode` in FIKO v1) and `user` (present in FIKO v1, but removed in FIKO v2, so also in this resourcemodel). + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ProductMetadataListResponse' + examples: + getListProductMetadata: + summary: List containing one ProductMetadata entry, used for testing purposes + value: + { + "Entries": [ + { + "productMetadataId": "501B17EF-36C4-4039-B92C-6517969B464E", + "productCode": "PG001", + "department": "Electronics", + "costCenter": "CC101", + "costType": "TypeA", + "description": "Group for electronic products", + "documentCode": "DOC001", + "timestampUpdated": "2024-09-03T15:07:53.470+00:00", + "validFrom": "2024-08-01T00:00:00.000+00:00", + "validUntil": "2025-08-01T00:00:00.000+00:00" + } + ], + } + '400': + description: '400' + content: + application/json: + schema: + $ref: '#/components/schemas/400Response' + '401': + description: '401' + content: + application/json: + schema: + $ref: '#/components/schemas/401Response' + '404': + description: '404' + content: + application/json: + schema: + $ref: '#/components/schemas/404Response' + '500': + description: '500' + content: + application/json: + schema: + $ref: '#/components/schemas/500Response' + +components: + schemas: + TaxMetadataListResponse: + type: object + required: + - Entries + properties: + Entries: + type: array + items: + $ref: '#/components/schemas/TaxMetadataResponse' + ProductMetadataListResponse: + type: object + required: + - Entries + properties: + Entries: + type: array + items: + $ref: '#/components/schemas/ProductMetadataResponse' + TaxMetadataResponse: + type: object + required: + - taxMetadataId + - taxCode + - taxPercentageAmount + - validFrom + properties: + taxMetadataId: + type: string + format: uuid + example: 501B17EF-36C4-4039-B92C-6517969B464E + taxCode: + type: string + example: V09 + taxPercentageAmount: + type: integer + example: 21 + description: + type: string + example: BTW VERKOOP LAAG 9% + validFrom: + type: string + format: date-time-offset + example: '2024-09-03T10:01:34.000+00:00' + validUntil: + type: string + format: date-time-offset + example: '2024-09-03T10:01:34.000+00:00' + ProductMetadataResponse: + type: object + required: + - productMetadataId + - productCode + - department + - costCenter + - costType + - description + - documentCode + - timestampUpdated + - validFrom + properties: + productMetadataId: + type: string + format: uuid + example: 501B17EF-36C4-4039-B92C-6517969B464E + productCode: + type: string + description: Called "artikelnr" in U4F + example: TBD + department: + type: string + description: Called "element 1" in U4F + example: TBD + costCenter: + type: string + description: Called "element 3" in U4F + example: TBD + costType: + type: string + description: Called "element 2" in U4F + example: TBD + description: + type: string + example: TBD + documentCode: + type: string + example: TBD + timestampUpdated: + type: string + format: date-time-offset + example: '2024-09-03T10:01:34.000+00:00' + validFrom: + type: string + format: date-time-offset + example: '2024-09-03T10:01:34.000+00:00' + validUntil: + type: string + format: date-time-offset + example: '2024-09-03T10:01:34.000+00:00' + 400Response: + type: object + properties: + code: + type: string + example: '400' + type: + type: string + message: + type: string + example: Bad Request + description: + type: string + example: '''2023-02-01 00:00:00'' is not a valid Datetime' + apiErrorCode: + type: string + example: htm.api.err.40xxx + 401Response: + type: object + properties: + code: + type: string + example: '900901' + type: + type: string + message: + type: string + example: Invalid Credentials + description: + type: string + example: >- + Invalid Credentials. Make sure you have provided the correct + security credentials + apiErrorCode: + type: string + example: htm.api.err.40xxx + 403Response: + type: object + properties: + code: + type: string + example: '900901' + type: + type: string + message: + type: string + example: Retailer not authorized + description: + type: string + example: The retailer is not allowed to access resource for requested + apiErrorCode: + type: string + example: htm.api.err.40xxx touchpoint + 404Response: + type: object + properties: + code: + type: string + example: '404' + type: + type: string + example: Status report + message: + type: string + example: Not Found + description: + type: string + example: The requested resource is not available. + apiErrorCode: + type: string + example: htm.api.err.40xxx + 500Response: + type: object + properties: + code: + type: string + example: '500' + type: + type: string + message: + type: string + example: Internal Server Error + description: + type: string + apiErrorCode: + type: string + example: htm.api.err.40xxx From 3e5958eb889088d3065d51afda16a1bac0de2b7b Mon Sep 17 00:00:00 2001 From: Max Martens Date: Fri, 11 Oct 2024 15:55:41 +0200 Subject: [PATCH 2/2] Remove erroneous newline characters --- src/openapi/fiko/fikoreference-crud.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/openapi/fiko/fikoreference-crud.yaml b/src/openapi/fiko/fikoreference-crud.yaml index 247747f..516519a 100644 --- a/src/openapi/fiko/fikoreference-crud.yaml +++ b/src/openapi/fiko/fikoreference-crud.yaml @@ -2,9 +2,9 @@ openapi: 3.0.1 info: title: ABTFikoReference description: |- - CRUD APIs for FIKO reference data (based on the v1 model for FIKO, see [the FIKO v1 datamodel in Lucid](https://lucid.app/lucidchart/50c0ff9d-48ba-4ea9-8182-10bede07d3b1/edit?viewport_loc=145%2C-316%2C2782%2C1418%2C0_0&invitationId=inv_1cd35e35-77f5-4e31-87d6-32fd74400350)). This means that, for now, only GET endpoints on `TaxMetadata` and `ProductGroupMetadata` (already named `ProductMetadata` to avoid rework for v2) are available. \ + CRUD APIs for FIKO reference data (based on the v1 model for FIKO, see [the FIKO v1 datamodel in Lucid](https://lucid.app/lucidchart/50c0ff9d-48ba-4ea9-8182-10bede07d3b1/edit?viewport_loc=145%2C-316%2C2782%2C1418%2C0_0&invitationId=inv_1cd35e35-77f5-4e31-87d6-32fd74400350)). This means that, for now, only GET endpoints on `TaxMetadata` and `ProductGroupMetadata` (already named `ProductMetadata` to avoid rework for v2) are available. - When the v2 model for FIKO is implemented (see [the FIKO v2 datamodel in Lucid](https://lucid.app/lucidchart/50c0ff9d-48ba-4ea9-8182-10bede07d3b1/edit?viewport_loc=-72%2C-954%2C2406%2C1226%2CUnjZp4g0O~CK&invitationId=inv_1cd35e35-77f5-4e31-87d6-32fd74400350)), POST/PUT/DELETE for these tables (as well as CRUD for additional tables) will become available, to support populating the reference tables with Unit4Financials data.\ + When the v2 model for FIKO is implemented (see [the FIKO v2 datamodel in Lucid](https://lucid.app/lucidchart/50c0ff9d-48ba-4ea9-8182-10bede07d3b1/edit?viewport_loc=-72%2C-954%2C2406%2C1226%2CUnjZp4g0O~CK&invitationId=inv_1cd35e35-77f5-4e31-87d6-32fd74400350)), POST/PUT/DELETE for these tables (as well as CRUD for additional tables) will become available, to support populating the reference tables with Unit4Financials data. These are NOT functional API's to be published by the Service Engine, but are direct CRUD API's on top of the database. version: '1.0'