openapi: 3.0.3

info:
  title: ALEFBA Marketplace API
  version: 1.0.0
  description: |
    API specification for ALEFBA's AI-powered, multi-category marketplace platform.

    Verify all paths, authentication rules, parameters and response schemas
    against the live production implementation before public release.
  contact:
    name: ALEFBA Developer Support
    email: info@alefba.eu
    url: https://docs.alefba.eu/support.php

servers:
  - url: https://alefba.eu
    description: ALEFBA Production

tags:
  - name: Public Catalog
  - name: Seller Health
  - name: Seller Products
  - name: Seller Orders

paths:
  /api/catalog:
    get:
      tags: [Public Catalog]
      summary: Retrieve public marketplace catalog data
      operationId: getPublicCatalog
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
            default: 1
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
      responses:
        '200':
          description: Catalog response returned successfully
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /api/v1/ping.php:
    get:
      tags: [Seller Health]
      summary: Check Seller API availability
      operationId: pingSellerApi
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Seller API is available
        '401':
          description: Authentication is missing or invalid

  /api/v1/products.php:
    get:
      tags: [Seller Products]
      summary: Retrieve seller products or one product by id
      operationId: getSellerProducts
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: id
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Product data returned successfully
        '401':
          description: Authentication is missing or invalid

    post:
      tags: [Seller Products]
      summary: Create a seller product
      operationId: createSellerProduct
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '201':
          description: Product created successfully
        '401':
          description: Authentication is missing or invalid
        '422':
          description: Validation failed

    put:
      tags: [Seller Products]
      summary: Update a seller product
      operationId: updateSellerProduct
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: id
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Product updated successfully
        '401':
          description: Authentication is missing or invalid
        '404':
          description: Product not found
        '422':
          description: Validation failed

  /api/v1/orders.php:
    get:
      tags: [Seller Orders]
      summary: Retrieve seller orders or one order by id
      operationId: getSellerOrders
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: id
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Order data returned successfully
        '401':
          description: Authentication is missing or invalid
        '404':
          description: Order not found

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Access Token