openapi: 3.0.0
info:
  title: LogistiX Merchant API (Draft)
  version: 1.0.0
  description: API for merchants to manage deliveries via LogistiX.

servers:
  - url: https://api.logistix.example.com/v1 # Placeholder URL

paths:
  /orders:
    post:
      summary: Create a new delivery order
      tags:
        - Orders
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderInput'
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          description: Bad Request (e.g., validation error)
        '401':
          description: Unauthorized (Invalid API Key)
        '500':
          description: Internal Server Error

  /orders/{orderId}:
    get:
      summary: Get order status and details
      tags:
        - Orders
      security:
        - ApiKeyAuth: []
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
          description: The ID of the order to retrieve.
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '401':
          description: Unauthorized
        '404':
          description: Order not found
        '500':
          description: Internal Server Error

  /quotes:
    post:
      summary: Get a delivery quote
      tags:
        - Quotes
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteInput'
      responses:
        '200':
          description: Delivery quote
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error

components:
  schemas:
    Address:
      type: object
      properties:
        street: 
          type: string
        city: 
          type: string
        postalCode: 
          type: string
        country: 
          type: string
          default: "Kenya"
        latitude: 
          type: number
          format: float
        longitude: 
          type: number
          format: float
      required:
        - street
        - city

    Package:
      type: object
      properties:
        description:
          type: string
        weight_kg:
          type: number
          format: float
        length_cm:
          type: integer
        width_cm:
          type: integer
        height_cm:
          type: integer
      required:
        - description
        - weight_kg

    OrderInput:
      type: object
      properties:
        pickup_address:
          $ref: '#/components/schemas/Address'
        delivery_address:
          $ref: '#/components/schemas/Address'
        recipient_name:
          type: string
        recipient_phone:
          type: string
        package_details:
          $ref: '#/components/schemas/Package'
        delivery_instructions:
          type: string
      required:
        - pickup_address
        - delivery_address
        - recipient_name
        - recipient_phone
        - package_details

    OrderResponse:
      type: object
      properties:
        order_id:
          type: string
          format: uuid
        status:
          type: string
          enum: [Pending, Assigned, PickedUp, InTransit, Delivered, Failed, Cancelled]
        delivery_fee:
          type: number
          format: float
        currency:
          type: string
          default: "KES"
        estimated_delivery_time:
          type: string
          format: date-time
        pickup_address:
          $ref: '#/components/schemas/Address'
        delivery_address:
          $ref: '#/components/schemas/Address'
        recipient_name:
          type: string
        recipient_phone:
          type: string
        package_details:
          $ref: '#/components/schemas/Package'
        tracking_history:
          type: array
          items:
            $ref: '#/components/schemas/TrackingUpdate'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    QuoteInput:
      type: object
      properties:
        pickup_address:
          $ref: '#/components/schemas/Address'
        delivery_address:
          $ref: '#/components/schemas/Address'
        package_details:
          $ref: '#/components/schemas/Package'
      required:
        - pickup_address
        - delivery_address
        - package_details

    QuoteResponse:
      type: object
      properties:
        estimated_fee:
          type: number
          format: float
        currency:
          type: string
          default: "KES"
        estimated_delivery_duration_minutes:
          type: integer

    TrackingUpdate:
      type: object
      properties:
        status:
          type: string
        location:
          type: object
          properties:
            latitude:
              type: number
              format: float
            longitude:
              type: number
              format: float
        timestamp:
          type: string
          format: date-time

  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY