openapi: 3.0.3
info:
  title: PubQ Data API
  version: v1
  description: API for accessing data related to companies, sales locations, and orders.
  contact:
    name: PubQ Support
    email: support@pubq.se
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://data.pubq.se/v1/api
    description: Production server
paths:
  /companies/{id}:
    get:
      summary: Get Sales Locations by Company ID
      description: >-
        Retrieves a list of sales locations (units) associated with a specific
        company.
      operationId: getSalesLocationsByCompanyId
      tags:
        - Companies
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: The ID of the company.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SalesLocation'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /orders/{id}:
    get:
      summary: Get Orders by Sales Location ID
      description: >-
        Retrieves a list of orders for a specific sales location (unit) within a
        given date range.
      operationId: getOrdersBySalesLocationId
      tags:
        - Orders
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: The ID of the sales location (routeName).
        - in: query
          name: from
          schema:
            type: integer
            format: int64
          required: true
          description: The start date in Unix timestamp format.
        - in: query
          name: to
          schema:
            type: integer
            format: int64
          required: true
          description: The end date in Unix timestamp format.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorMissingParameters'
                  - $ref: '#/components/schemas/ErrorInvalidDateRange'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /apps/{id}:
    get:
      tags:
        - Metrics
      summary: Get apps by company ID
      description: >-
        Retrieves a list of applications associated with a given company ID. The
        current implementation returns a dummy payload.
      operationId: getAppsByCompanyId
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the company to retrieve apps for.
          schema:
            type: string
      responses:
        '200':
          description: A list of apps.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AppInfo'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /metrics/{appId}:
    get:
      tags:
        - Metrics
      summary: Get metrics for a specific app
      description: >-
        Retrieves metrics for a specified application ID within a given time
        range. The current implementation returns a dummy payload.
      operationId: getAppMetrics
      parameters:
        - name: appId
          in: path
          required: true
          description: The ID of the application to retrieve metrics for.
          schema:
            type: string
        - name: from
          in: query
          required: false
          description: Start timestamp for metrics (Unix timestamp or YYYY-MM-DD string).
          schema:
            type: string
        - name: to
          in: query
          required: false
          description: End timestamp for metrics (Unix timestamp or YYYY-MM-DD string).
          schema:
            type: string
      responses:
        '200':
          description: Metrics data for the application.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppMetrics'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /metrics/vendor/{routeName}:
    get:
      tags:
        - Metrics
      summary: Get metrics for a specific vendor
      description: >-
        Retrieves metrics for a specified vendor route name within a given time
        range. The current implementation returns a dummy payload and has a
        potential issue with `appId` in the response (see implementation notes).
      operationId: getVendorMetrics
      parameters:
        - name: routeName
          in: path
          required: true
          description: The route name of the vendor to retrieve metrics for.
          schema:
            type: string
        - name: from
          in: query
          required: false
          description: Start timestamp for metrics (Unix timestamp or YYYY-MM-DD string).
          schema:
            type: string
        - name: to
          in: query
          required: false
          description: End timestamp for metrics (Unix timestamp or YYYY-MM-DD string).
          schema:
            type: string
      responses:
        '200':
          description: Metrics data for the vendor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorMetrics'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SalesLocation:
      type: object
      properties:
        id:
          type: string
          description: The ID of the sales location (routeName).
        name:
          type: string
          description: The name of the sales location.
        postalCode:
          type: string
          description: The postal code of the sales location.
        city:
          type: string
          description: The city of the sales location.
        countryCode:
          type: string
          description: The country code of the sales location.
      required:
        - id
        - name
        - postalCode
        - city
        - countryCode
    OrderItem:
      type: object
      properties:
        name:
          type: string
          description: The name of the item.
        quantity:
          type: integer
          description: The quantity of the item.
        id:
          type: string
          description: The ID of the item.
        totalPrice:
          type: number
          description: The total price of the item.
        basePrice:
          type: number
          description: The base price of the item.
        category:
          type: string
          description: The category of the item.
        description:
          type: string
          description: The description of the item.
        externalId:
          type: string
          nullable: true
          description: The external ID of the item, if available.
      required:
        - name
        - quantity
        - id
        - totalPrice
        - basePrice
        - category
        - description
    Timeslot:
      type: object
      properties:
        date:
          type: integer
          description: The Unix timestamp of the timeslot date.
        dateISO:
          type: string
          description: The date and time of the timeslot in ISO format.
        label:
          type: string
          description: The label of the timeslot.
      required:
        - date
        - dateISO
        - label
    Order:
      type: object
      properties:
        dateISO:
          type: string
          description: The date and time of the order in ISO format.
        dateTimestamp:
          type: integer
          description: The Unix timestamp of the order date.
        totalAmount:
          type: integer
          description: The total amount of the order (in cents).
        discountAmount:
          type: integer
          description: The discount amount applied to the order (in cents).
        userId:
          type: string
          description: The ID of the user who placed the order.
        totalItems:
          type: integer
          description: The total number of items in the order.
        timeslot:
          $ref: '#/components/schemas/Timeslot'
          nullable: true
          description: The timeslot information, if applicable.
        payment:
          type: object
          description: The payment information.
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
          description: An array of items in the order.
      required:
        - dateISO
        - dateTimestamp
        - totalAmount
        - discountAmount
        - userId
        - totalItems
        - payment
        - items
    ErrorMissingParameters:
      type: object
      properties:
        error:
          type: string
          example: Both from and to must be sent as query parameters (Unix timestamp)
    ErrorInvalidDateRange:
      type: object
      properties:
        error:
          type: string
          example: You can only fetch 1 day at a time.
    Error:
      type: object
      properties:
        code:
          type: integer
          description: The error code.
        message:
          type: string
          description: A description of the error.
        details:
          type: object
          nullable: true
          description: Additional details about the error.
    AppInfo:
      type: object
      properties:
        appId:
          type: string
          description: The unique identifier for the app.
          example: app_xyz123
        name:
          type: string
          description: The name of the app.
          example: My Awesome Application
    AppMetrics:
      type: object
      properties:
        appId:
          type: string
          description: The ID of the application.
          example: app_xyz123
        totalCompletedOrders:
          type: integer
          format: int32
          example: 150
        newUsers:
          type: integer
          format: int32
          example: 25
        activeUsers:
          type: integer
          format: int32
          example: 120
        appOpens:
          type: integer
          format: int32
          example: 500
        iosUsers:
          type: integer
          format: int32
          example: 70
        androidUsers:
          type: integer
          format: int32
          example: 50
        cartsCreated:
          type: integer
          format: int32
          example: 200
        cartsIdling:
          type: integer
          format: int32
          example: 15
        averageSessionLength:
          type: number
          format: float
          description: Average session length in seconds or minutes.
          example: 180.5
    VendorMetrics:
      type: object
      properties:
        routeName:
          type: string
          description: The route name of the vendor.
          example: vendor_route_abc
        totalCompletedOrders:
          type: integer
          format: int32
          example: 150
        newUsers:
          type: integer
          format: int32
          example: 25
        activeUsers:
          type: integer
          format: int32
          example: 120
        appOpens:
          type: integer
          format: int32
          example: 500
        iosUsers:
          type: integer
          format: int32
          example: 70
        androidUsers:
          type: integer
          format: int32
          example: 50
        cartsCreated:
          type: integer
          format: int32
          example: 200
        cartsIdling:
          type: integer
          format: int32
          example: 15
        averageSessionLength:
          type: number
          format: float
          description: Average session length in seconds or minutes.
          example: 180.5
