From 7a513612ba9ff0f5e3c0bf235e30989d525272aa Mon Sep 17 00:00:00 2001 From: Max Martens Date: Fri, 11 Oct 2024 15:54:04 +0200 Subject: [PATCH] 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