openapi: 3.0.1
info:
  title: Dealer API
  version: 1.0.0
components:
  securitySchemes:
    BearerAuth:               # name can be anything
      type: http
      scheme: bearer
      bearerFormat: JWT       # or API Key
security:
  - BearerAuth: []            # apply globally (all endpoints)
paths:
  /dealer_api/test_connection:
    get:
      summary: Test API token connection validity
      description: >
        Validates the provided Dealer API Token.
        Requires an `Authorization: Bearer <token>` header.
      tags:
        - Connection
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Connection is valid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "Connection is valid."
        '400':
          description: Missing or invalid Authorization token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: "Missing or invalid Authorization token."
        '401':
          description: Invalid or unauthorized token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: "Token is invalid or user not found."
        '403':
          description: API access forbidden for this user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  code:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: "API access not allowed for this user."
  /dealer_api/sale_orders/{dealer_order_ref}:
    get:
      summary: Get status of a sales order by dealer_order_ref
      description: >
        Returns the latest status and related delivery info of the sales order submitted by the dealer.
        Requires an `Authorization: Bearer <token>` header.
      tags:
        - Sale Order
      security:
        - BearerAuth: []
      parameters:
        - name: dealer_order_ref
          in: path
          required: true
          schema:
            type: string
          description: The dealer order reference identifier
      responses:
        '200':
          description: Sale order status retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "Sale order found."
                  result:
                    type: object
                    properties:
                      so_status:
                        type: string
                        description: "done, processing, or failed"
                        example: "done"
                      dealer_order_ref:
                        type: string
                        example: "ORDER12345"
                      order_name:
                        type: string
                        example: "SO0001"
                      status:
                        type: string
                        example: "sale"
                      delivery_status:
                        type: string
                        example: "delivered"
                      customer_name:
                        type: string
                        example: "John Doe"
                      amount_total:
                        type: number
                        format: float
                        example: 1500.75
                      currency:
                        type: string
                        example: "USD"
        '400':
          description: Invalid order reference or linked queue job not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    examples:
                      invalid_ref:
                        value: "Invalid Dealer API Order Ref."
                      missing_queue:
                        value: "Linked Sale Order queue job is not found"
        '401':
          description: Unauthorized — invalid or missing token / user not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    examples:
                      no_token:
                        value: "Missing or invalid Authorization token."
                      user_not_found:
                        value: "User not found."
                      token_invalid:
                        value: "Token is invalid."
        '403':
          description: API access forbidden for this user
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  code:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: "API access not allowed for this user."

  /dealer_api/products:
    get:
      summary: Get all active product variants with API access
      description: >
        Returns a list of product variants that are active and API-accessible for the dealer.
        Requires a valid `Authorization: Bearer <token>` header.
      tags:
        - Product
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Product variants retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "Product variants retrieved successfully."
                  count:
                    type: integer
                    example: 2
                  result:
                    type: array
                    items:
                      type: object
                      properties:
                        product_id:
                          type: integer
                          example: 101
                        display_name:
                          type: string
                          example: "T-Shirt"
                        attribute:
                          type: object
                          additionalProperties:
                            type: string
                          example:
                            Color: "Red"
                            Size: "M"
                        product_code:
                          type: string
                          example: "TSHIRT-RED-M"
                        active:
                          type: boolean
                          example: true

  /dealer_api/all_product_quantity:
    get:
      summary: Get available quantity for all API-accessible products
      description: >
        Returns the sync quantity for all product variants that are API-accessible.
        Requires a valid `Authorization: Bearer <token>` header.
      tags:
        - Product
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Quantities retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "Products’ quantities are retrieved successfully."
                  count:
                    type: integer
                    example: 2
                  result:
                    type: array
                    items:
                      type: object
                      properties:
                        product_id:
                          type: integer
                          example: 101
                        product_desc:
                          type: string
                          example: "T-Shirt (Red, M)"
                        quantity:
                          type: integer
                          example: 50


  /dealer_api/product_quantity:
    post:
      summary: Get available quantity for specific product variants
      description: >
        Accepts a JSON body with a list of `variant_ids` and returns their available sync quantities. 
        Requires a valid `Authorization: Bearer <token>` header.
      tags:
        - Product
      security:
        - BearerAuth: []
      requestBody:
        description: List of product variant IDs
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - variant_ids
              properties:
                variant_ids:
                  type: array
                  items:
                    type: integer
                  example: [101, 102, 103]
      responses:
        '200':
          description: Quantities retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "Products’ quantities are retrieved successfully."
                  result:
                    type: array
                    items:
                      type: object
                      properties:
                        product_id:
                          type: integer
                          example: 101
                        product_desc:
                          type: string
                          example: "[ABC123] T-Shirt (Red, M)"
                        quantity:
                          type: integer
                          example: 40
        '400':
          description: Validation error (invalid structure, too many IDs, or non-existing IDs)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    examples:
                      invalid_structure:
                        value: "Only variant_ids field names are allowed in this endpoint."
                      not_list:
                        value: "You must at least provide an ID to get the available quantity for this product."
                      empty_list:
                        value: "You must at least provide an ID to get the available quantity for this product."
                      too_many:
                        value: "Requested products exceed the limit count (20 max)"
                      invalid_ids:
                        value: "The variant_ids is invalid."
        '406':
          description: Too many products requested (limit exceeded)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  code:
                    type: integer
                    example: 406
                  message:
                    type: string
                    example: "Requested products exceed the limit count (20 max)"
 
  /dealer_api/sale_orders:
    post:
      summary: Create sale order from dealer
      description: >
        Submits a new sales order from the dealer.
        The order is validated, logged, and queued for confirmation.
        Requires an `Authorization: Bearer <token>` header.
      tags:
        - Sale Order
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - dealer_order_ref
                - api_call_datetime
                - order_line
              properties:
                dealer_order_ref:
                  type: string
                  example: "ORDER12345"
                api_call_datetime:
                  type: string
                  format: date-time
                  example: "2025-08-25T14:30:00"
                order_line:
                  type: array
                  items:
                    type: object
                    required:
                      - dealer_line_id
                      - product_id
                      - product_uom_qty
                    properties:
                      dealer_line_id:
                        type: string
                        example: "LINE001"
                      product_id:
                        type: integer
                        example: 101
                      product_uom_qty:
                        type: integer
                        example: 2
      responses:
        '202':
          description: Sale order creation queued successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  code:
                    type: integer
                    example: 202
                  message:
                    type: string
                    example: "Sale order creation queued successfully."
                  result:
                    type: object
                    properties:
                      dealer_order_ref:
                        type: string
                        example: "ORDER12345"
                      so_status:
                        type: string
                        example: "queued"
        '400':
          description: Validation error — missing fields, duplicates, or invalid data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    examples:
                      missing_field:
                        value: "Missing required field: dealer_order_ref."
                      invalid_datetime:
                        value: "Invalid format for api_call_datetime."
                      duplicate_ref:
                        value: "Duplicate order request detected."
                      product_not_found:
                        value: "An error has occurred during the creation of order. Error: Product ID 101 is not found."
                      qty_invalid:
                        value: "An error has occurred during the creation of order. Error : Quantity for LINE001 is not a valid number."
                      qty_negative:
                        value: "An error has occurred during the creation of order. Error : LINE001 contains a negative number in quantity."
                      quotation_error:
                        value: "Failed to create quotation. Error: <error details>"
        '401':
          description: Unauthorized — invalid or missing token / user not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    examples:
                      no_token:
                        value: "Missing or invalid Authorization token."
                      user_not_found:
                        value: "User not found."
                      token_invalid:
                        value: "Token is invalid."
        '403':
          description: API access forbidden for this user
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  code:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: "API access not allowed for this user."
