openapi: 3.0.3
info:
  title: Girteka Orders API
  version: '1.0'
  description: >
    This is order-api documentation which covers all actions availble on order
    object via api invocations.
servers:
  - url: https://test-api.girteka.eu/orders/v1
    description: Testing environment
  - url: https://api.girteka.eu/orders/v1
    description: Production environment
tags:
  - name: Orders
    description: Endpoints for retrieving the all data related to the order.
paths:
  /orders/{id}:
    get:
      summary: Get all data for specific data order
      operationId: get-order-by-id
      description: >-
        Returns the the all data for the specific order ID. The order dara is
        returned only in case authorisation allows the api consumer to access
        the data
      tags:
        - Orders
      security:
        - CognitoOAuth2Test:
            - girteka-api-resource-server/orders.read
        - CognitoOAuth2Prod:
            - girteka-api-resource-server/orders.read
      parameters:
        - name: id
          in: path
          required: true
          description: Girteka order ID
          schema:
            type: string
          examples:
            valid:
              summary: Valid order ID
              value: ORD123456789
            forbidden:
              summary: Forbidden access
              value: forbidden-order
            not_found:
              summary: Not found
              value: not-found-order
      responses:
        '200':
          description: Latest metadata entry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order_data'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Order not found
        '500':
          $ref: '#/components/responses/InternalServerError'
  /orders/{id}/temperatures:
    get:
      summary: Get all temperature readings associated with specific order
      operationId: get-order-temperatures
      description: >-
        Returns all temperature readings assiciated with specific order. The
        temperature dara is returned only in case authorisation allows the api
        consumer to access the data
      tags:
        - Orders
      security:
        - CognitoOAuth2Test:
            - girteka-api-resource-server/orders.read
        - CognitoOAuth2Prod:
            - girteka-api-resource-server/orders.read
      parameters:
        - name: id
          in: path
          required: true
          description: Girteka order ID
          schema:
            type: string
          examples:
            valid:
              summary: Valid order ID
              value: ORD123456789
            forbidden:
              summary: Forbidden access
              value: forbidden-order
            not_found:
              summary: Not found
              value: not-found-order
      responses:
        '200':
          description: Temperature readings sorted by tampstamp
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/temperature_data'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Order not found
        '500':
          $ref: '#/components/responses/InternalServerError'
  /orders/{id}/temperatures/latest:
    get:
      summary: Get latest temperature readings associated with specific order
      operationId: get-order-temperatures-latest
      description: >-
        Returns latest temperature readings assiciated with specific order. The
        temperature dara is returned only in case authorisation allows the api
        consumer to access the data
      tags:
        - Orders
      security:
        - CognitoOAuth2Test:
            - girteka-api-resource-server/orders.read
        - CognitoOAuth2Prod:
            - girteka-api-resource-server/orders.read
      parameters:
        - name: id
          in: path
          required: true
          description: Girteka order ID
          schema:
            type: string
          examples:
            valid:
              summary: Valid order ID
              value: ORD123456789
            forbidden:
              summary: Forbidden access
              value: forbidden-order
            not_found:
              summary: Not found
              value: not-found-order
      responses:
        '200':
          description: Temperature readings sorted by tampstamp
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/temperature_data'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Order not found
        '500':
          $ref: '#/components/responses/InternalServerError'
  /orders:
    post:
      summary: >-
        This is an implementation of orders data update when order data object
        is provided in the body.
      operationId: post-order-update
      description: >-
        This is an implementation of orders data update when order data object
        is provided in the body. The same can be implemented either with POST
        method to specific order /orders/{id}. For Higfh volumes updates it is
        highly recomend to implement updates via messaging. Please contact
        order-api@girteka.eu to get access to messaging queue. Please note, that
        security validation is applied to check if you have rights to update
        specific order data
      tags:
        - Orders
      security:
        - CognitoOAuth2Test:
            - girteka-api-resource-server/orders.read
        - CognitoOAuth2Prod:
            - girteka-api-resource-server/orders.read
      responses:
        '200':
          description: Latest metadata entry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order_data'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Order not found
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      summary: >-
        Returns all orders as per search criteria provided in query. Search
        method returns only latest values.
      operationId: get-order-search
      description: >-
        Returns all data or requested objects associated with the order. the
        search is performed only on the scope of the orders allowed for the
        api-consumer
      tags:
        - Orders
      security:
        - CognitoOAuth2Test:
            - girteka-api-resource-server/orders.read
        - CognitoOAuth2Prod:
            - girteka-api-resource-server/orders.read
      parameters:
        - name: trailer_plate_id
          in: query
          required: false
          description: >-
            Search for the active orders with current assigned specific trailer
            plate id. This comes only in combination of open_orders is true.
          schema:
            type: string
          examples:
            valid:
              summary: Valid triler id
              value: ''
            forbidden:
              summary: Forbidden access
              value: forbidden-order
            not_found:
              summary: Not found
              value: not-found-order
      responses:
        '200':
          description: Temperature readings sorted by tampstamp
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/order_data_latest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Order not found
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    customer_data:
      type: object
      required:
        - customer_id
      properties:
        customer_id:
          type: string
          description: Unique identifier of the customer data entry
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        name:
          type: string
          description: The name of the customer
          example: My Best Company, UAB
        customer_vat:
          type: string
          description: VAT number of the customer
          example: LT123456789
        address:
          $ref: '#/components/schemas/address_data'
    coordinates_data:
      type: object
      properties:
        latitude:
          type: number
          description: Latitude of the address
          example: 54.687157
        longitude:
          type: number
          description: Longitude of the address
          example: 25.279652
    driver_document_data:
      type: object
      properties:
        document_type:
          type: string
          description: Type of the document
          enum:
            - driving_licence
            - passport
        document_number:
          type: string
          description: Document number
          example: ABC123456
        document_country:
          type: string
          description: Country of issue of the document
          example: LT
        document_issue_date:
          type: string
          description: Date of issue of the document
          example: '2020-01-01'
        document_expiry_date:
          type: string
          description: Date of expiry of the document
          example: '2025-01-01'
        document_image:
          type: string
          description: Image of the document
          example: https://girteka.eu/image.jpg
    driver_data:
      type: object
      properties:
        first_name:
          type: string
          description: The name of the driver
          example: John
        last_name:
          type: string
          description: The name of the driver
          example: John
        documents:
          type: array
          description: List of driver documents
          items:
            $ref: '#/components/schemas/driver_document_data'
    customer_care_data:
      type: object
      properties:
        phone:
          type: string
          description: Phone number of the customer
          example: '000000000000'
        email:
          type: string
          description: Email of the customer
          example: info@girteka.eu
        customer_care_id:
          type: string
          description: Uniq Identification of customer care agent
          example: '15'
    address_data:
      type: object
      properties:
        location_name:
          type: string
          description: Name of the location represented by address
          example: Cargo Centrale
        street:
          type: string
          description: Jasinskio
        city:
          type: string
          description: City
          example: Vilnius
        zip:
          type: string
          description: Zip Code
          example: LT-2586
        country_code:
          type: integer
          description: Country Code
          example: '440'
        country:
          type: string
          description: Country
          example: Lithuania
        coordinates:
          $ref: '#/components/schemas/coordinates_data'
    order_stage_data:
      type: object
      properties:
        sequence:
          type: integer
          description: >-
            Sequence number of the order execution. This represent logical
            sequence number in order transportation.
          example: '1'
        transportation_type:
          type: string
          description: Represents the order execution transportation type.
          example: road
          enum:
            - road
            - rail
            - sea
            - air
        sequence_start_datetime:
          type: string
          description: Timestamp of the start of the stage
          example: '2025-05-06T14:30:00Z'
        sequence_end_datetime:
          type: string
          description: Timestamp of the end of the stage
          example: '2025-05-06T14:30:00Z'
        stage_status:
          type: string
          description: Status of the stage
          example: completed
          enum:
            - completed
            - in_progress
            - cancelled
        vehicle:
          $ref: '#/components/schemas/vechicle_data'
        drivers:
          type: array
          description: List of drivers assigned to the fracht execution
          items:
            $ref: '#/components/schemas/driver_data'
        loading:
          properties:
            loading_refernceId:
              type: string
              description: Reference ID of the loading
              example: RTUPOU
            loading_start:
              type: string
              description: Timestamp of the start of the loading
              example: '2025-05-06T14:30:00Z'
            loading_end:
              type: string
              description: Timestamp of the end of the loading
              example: '2025-05-06T14:30:00Z'
            loading_address:
              $ref: '#/components/schemas/address_data'
        unloading:
          properties:
            unloading_refernceId:
              type: string
              description: Reference ID of the loading
              example: RTUPOU
            unloading_start:
              type: string
              description: Timestamp of the start of the loading
              example: '2025-05-06T14:30:00Z'
            unloading_end:
              type: string
              description: Timestamp of the end of the loading
              example: '2025-05-06T14:30:00Z'
            unloading_address:
              $ref: '#/components/schemas/address_data'
    cargo_data:
      properties:
        description:
          type: string
          description: Cargo description
          example: Motocyrcles
        weightKg:
          type: integer
          description: Cargo weight in Kg
          example: '600'
        volumeM3:
          type: integer
          description: Cargo volume in m3
          example: '60'
    location_data:
      properties:
        location_type:
          type: string
          description: Defines location type
          example: loading
          enum:
            - loading
            - unloading
            - parking
        refernceId:
          type: string
          description: string
          example: RTUPOU
        sequence:
          type: string
          description: string
          example: '60'
        address:
          $ref: '#/components/schemas/address_data'
    vechicle_data:
      properties:
        truck_license_plate:
          type: string
          description: License plate number of the truck
          example: ABC123
        trailer_license_plate:
          type: string
          description: License plate number of the trailer
          example: TR4567
        assign_timestmap:
          type: string
          description: Timestamp of the assignment
          example: '2025-05-06T14:30:00Z'
        deasign_timestmap:
          type: string
          description: >-
            Timstamp of deasigning of vechicle. For current vechcle in use,
            deasign_timestmap is empty
          example: '2025-05-06T14:30:00Z'
    temperature_data:
      description: >-
        Defines temperature data for the during order execution. Data available
        only if the order is temperature controled
      properties:
        temperature_trailer:
          type: number
          description: Temperature of the sensor in trailer
          example: '25.5'
        timestamp:
          type: string
          description: Timestamp of the temperature reading
          example: '2025-05-06T14:30:00Z'
    visibility_data:
      description: Defines GPS Locations data for order for specifi timestamp
      properties:
        timestamp:
          type: string
          description: Timestamp of the location reading
          example: '2025-05-06T14:30:00Z'
        source:
          type: string
          description: GPS locations reading source
          example: P44
        coordinates:
          $ref: '#/components/schemas/coordinates_data'
    gps_data:
      description: This is data set for the gps location on the order
      properties:
        timestamp:
          type: string
          description: Timestamp of the location reading
          example: '2025-05-06T14:30:00Z'
        source:
          type: string
          description: GPS locations reading source
          example: P44
          enum:
            - p44
            - trailer
            - truck
        coordinates:
          $ref: '#/components/schemas/coordinates_data'
    event_data:
      description: Represent the event associated with the Order
      properties:
        event_type:
          type: string
          description: Type of the event
          example: loading
          enum:
            - loading
            - unloading
            - parking
            - loading_end
            - unloading_end
            - parking_end
            - loading_start
            - unloading_start
            - parking_start
        timestamp:
          type: string
          description: Timestamp of the event
          example: '2025-05-06T14:30:00Z'
        location:
          $ref: '#/components/schemas/location_data'
    order_data_latest:
      description: >-
        Represent Order data without historical records showing only latest
        order related data.
      required:
        - id
        - order_id
      properties:
        id:
          type: string
          description: >-
            System Unique identifier of the Order entry. ID is created during
            order creation and represents Girteka systems uniq ID
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        order_id:
          type: string
          description: >-
            Girteka Internal unique identifier of the order. This is Girteka SAP
            ID
          example: ORD123456789
        customer_order_id:
          type: string
          description: >-
            Order ID provided by the Customer. In an situtation when customer
            does not provide customer id in order reques, this field is the same
            as Girteka order_id.
          example: CUST987654321
        customer_system_id:
          type: string
          description: System Unique identifier of the Order entry within customer systems.
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        status:
          type: string
          description: Represents order status
          example: In Transit
        customer:
          $ref: '#/components/schemas/customer_data'
        support_organisation:
          $ref: '#/components/schemas/customer_care_data'
        cargo:
          $ref: '#/components/schemas/cargo_data'
        order_stages:
          $ref: '#/components/schemas/order_stage_data'
        tracking:
          $ref: '#/components/schemas/gps_data'
        temperatures:
          properties:
            temperature_setting:
              type: number
              description: Defines agreeed temperature for order execution.
              example: '25.5'
            temperature_data:
              $ref: '#/components/schemas/temperature_data'
    order_data:
      type: object
      required:
        - id
        - order_id
      properties:
        id:
          type: string
          description: >-
            System Unique identifier of the Order entry. ID is created during
            order creation and represents Girteka systems uniq ID
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        order_id:
          type: string
          description: >-
            Girteka Internal unique identifier of the order. This is Girteka SAP
            ID
          example: ORD123456789
        customer_order_id:
          type: string
          description: >-
            Order ID provided by the Customer. In an situtation when customer
            does not provide customer id in order reques, this field is the same
            as Girteka order_id.
          example: CUST987654321
        customer_system_id:
          type: string
          description: System Unique identifier of the Order entry within customer systems.
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        status:
          type: string
          description: Represents order status
          example: In Transit
        customer:
          $ref: '#/components/schemas/customer_data'
        support_organisation:
          $ref: '#/components/schemas/customer_care_data'
        cargo:
          $ref: '#/components/schemas/cargo_data'
        order_stages:
          type: array
          description: Represents Order execution flows
          items:
            $ref: '#/components/schemas/order_stage_data'
        tracking:
          type: array
          description: Tracking data for the order
          items:
            $ref: '#/components/schemas/gps_data'
        temperatures:
          properties:
            temperature_setting:
              type: number
              description: Defines agreeed temperature for order execution.
              example: '25.5'
            temperature_data:
              type: array
              description: Temperature data during order execution
              items:
                $ref: '#/components/schemas/temperature_data'
    pagination_metadata:
      type: object
      description: Pagination metadata
      properties:
        page:
          type: integer
          description: Current page
          example: 1
        page_count:
          type: integer
          description: Total page count
          example: 1
        total_count:
          type: integer
          description: Total records count
          example: 1
  responses:
    Unauthorized:
      description: Access denied
    Forbidden:
      description: Forbidden
    InternalServerError:
      description: Unexpected internal server error
  securitySchemes:
    CognitoOAuth2Test:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: >-
            https://cgi-iam-test.auth.eu-central-1.amazoncognito.com/oauth2/token
          scopes:
            girteka-api-resource-server/orders.read: Read access to orders
            girteka-api-resource-server/orders.write: Write access to orders
    CognitoOAuth2Prod:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: >-
            https://cgi-iam-prod.auth.eu-central-1.amazoncognito.com/oauth2/token
          scopes:
            girteka-api-resource-server/orders.read: Read access to orders
            girteka-api-resource-server/orders.write: Write access to orders
