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 `validUntil` 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 `validUntil` 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",
                          "validUntil": 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",
                          "validUntil": null
                        },
                        {
                          "taxMetadataId": "AC20A838-C81B-4652-96EA-F6E79E696E9C",
                          "taxCode": "V0",
                          "taxPercentageAmount": 0,
                          "description": "BTW VERKOOP NUL",
                          "validFrom": "2024-01-01T00:00:00.000+00:00",
                          "validUntil": 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",
                          "validUntil": 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",
                          "validUntil": null
                        },
                        {
                          "taxMetadataId": "AC20A838-C81B-4652-96EA-F6E79E696E9C",
                          "taxCode": "V0",
                          "taxPercentageAmount": 0,
                          "description": "BTW VERKOOP NUL",
                          "validFrom": "2024-01-01T00:00:00.000+00:00",
                          "validUntil": 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