openapi: 3.0.3
info:
  title: Generic KPI API
  version: "1.0.2"

paths:
  /kpi-data:
    get:
      summary: Get KPI data
      responses:
        "200":
          description: Payload
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericKpiResponse"
              example:
                sections:
                  - title: "Orders"
                    message: "Unable to fetch orders"
                    documents:
                      - documentNumber: "165945457"
                        documentDate: "2025-08-15T13:37:42Z"
                        externalUrl: "https://e-commerce.site/order-number"
                        trackingUrl: "https://posten.no/tracking-number"
                        status:
                          name: "Open"
                          colorCode: "GREEN"
                          updatedDate: "2025-08-15T13:37:42Z"
                        amount: 2799.0
                        currency: "NOK"
                        lines:
                          - name: "Barbeque grill"
                            quantity: 1
                            delivered: 0
                            url: "https://e-commerce.site/products/barbeque-grill"
                            fields:
                              - name: "Product code"
                                value: "G-24595"
                              - name: "Price"
                                value: "2399.0"
                            expandableFields:
                              - columns: ["Mansion 3.0","Gassgrill","G-24595-30"]
                                fields:
                                  - name: "Category"
                                    value: "Cooking ware"
                                  - name: "GTIN"
                                    value: "7072806007647"
                          - name: "Delivery service"
                            quantity: 1
                            delivered: 0
                            url: "https://e-commerce.site/services/delivery"
                            fields:
                              - name: "Price"
                                value: "400.0"
                        fields:
                          - value: "Order comment: Expected delivery 01.09"
                          - name: "Transporter"
                            value: "DHL"

components:
  schemas:
    GenericKpiResponse:
      type: object
      properties:
        sections:
          type: array
          description: List of KPI panel sections.
          items:
            $ref: "#/components/schemas/KpiSectionDTO"
          
    KpiSectionDTO:
      type: object
      required:
        - title
        - documents
      properties:
        title:
          type: string
          description: Section title, like 'Orders' or 'Invoices'.
        message:
          type: string
          description: Error or any other message for the section, like 'No data available'.
        documents:
          type: array
          description: Documents to be shown in the panel. Documents are supposed to be of the kind represented by the section title.
          items:
            $ref: "#/components/schemas/KpiDocumentDTO"

    KpiDocumentDTO:
      type: object
      required:
        - documentNumber
        - documentDate
      properties:
        documentNumber:
          type: string
          description: Unique document identifier (number), mandatory.
          maxLength: 10
        documentDate:
          type: string
          format: date-time
          description: Document timestamp in ISO 8601 format, UTC timezone. Use yyyy-MM-dd'T'HH:mm:ss'Z' format.
        externalUrl:
          type: string
          format: uri
          description: The document's URL in an external system, e.g. in e-commerce.
        trackingUrl:
          type: string
          format: uri
          description: The corresponding URL in a logistics provider's system.
        status:
          $ref: "#/components/schemas/KpiStatusDTO"
        amount:
          type: number
          description: Order sum with .00 precision.
        currency:
          type: string
          description: Order currency.
          maxLength: 3
        lines:
          type: array
          description: Document lines.
          items:
            $ref: "#/components/schemas/KpiDocumentLineDTO"
        fields:
          type: array
          description: Custom fields.
          items:
            $ref: "#/components/schemas/KpiCustomFieldDTO"

    KpiStatusDTO:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Status text.
          maxLength: 15
        colorCode:
          type: string
          description: One of the supported color codes. If absent, NORMAL is supposed.
          enum: [NORMAL,GREEN,ORANGE,RED]
        updatedDate:
          type: string
          format: date-time
          description: Status modification timestamp in ISO 8601 format, UTC timezone. Use yyyy-MM-dd'T'HH:mm:ss'Z' format.

    KpiDocumentLineDTO:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Item (supposedly, a product or service) name.
        quantity:
          type: number
          description: Total quantity bought or sold.
        delivered:
          type: number
          description: Delivered quantity.
        url:
          type: string
          format: uri
          description: Product or service URL in an external system, e.g. in e-commerce.
        fields:
          type: array
          description: Custom fields
          items:
            $ref: "#/components/schemas/KpiCustomFieldDTO"
        expandableFields:
          type: array
          description: Additional expandable info section.
          items:
            $ref: "#/components/schemas/KpiExpandableDTO"

    KpiCustomFieldDTO:
      type: object
      required:
        - value
      properties:
        name:
          type: string
          description: Custom field name. Nameless fields are allowed only in KpiDocumentDTO.
          maxLength: 25
        value:
          type: string
          description: Custom field value.

    KpiExpandableDTO:
      type: object
      required:
        - columns
      properties:
        columns:
          type: array
          description: Property names.
          minItems: 1
          items:
            type: string
        fields:
          type: array
          description: Custom fields.
          items:
            $ref: "#/components/schemas/KpiCustomFieldDTO"