openapi: 3.0.3
info:
  title: Maqsafy API
  version: 0.1.0-draft
  description: |
    Draft OpenAPI specification generated from the documented Laravel route inventory.
    This file is intended for technical review and must be validated against runtime
    route:list output before it is treated as the final backend API contract.
servers:
  - url: /
    description: Same origin or configured API gateway base URL
security:
  - bearerAuth: []
tags:
  - name: Authentication
  - name: Users
  - name: Students
  - name: Orders
  - name: Products
  - name: Suppliers
  - name: Wallets
  - name: Payments
  - name: Notifications
  - name: Public Content
paths:
  /api/v2/login:
    post:
      tags: [Authentication]
      summary: Login user
      description: Authenticates a user and returns an API token when credentials are valid.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/v2/logout:
    post:
      tags: [Authentication]
      summary: Logout current device
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v2/logout-from-device:
    post:
      tags: [Authentication]
      summary: Logout from selected device
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v2/logout-from-all-devices:
    post:
      tags: [Authentication]
      summary: Logout from all devices
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v2/register/send_mobile_verify_code:
    post:
      tags: [Authentication]
      summary: Send mobile verification code
      security: []
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/v2/register/verify_mobile:
    post:
      tags: [Authentication]
      summary: Verify mobile number
      security: []
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/v2/register:
    post:
      tags: [Authentication]
      summary: Register user
      security: []
      responses:
        '201':
          description: User registered
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/v2/password/forget:
    post:
      tags: [Authentication]
      summary: Request password reset
      security: []
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/v2/password/reset:
    post:
      tags: [Authentication]
      summary: Reset password
      security: []
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/v2/profile:
    get:
      tags: [Users]
      summary: Get authenticated user profile
      responses:
        '200':
          description: User profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v2/profile/update:
    put:
      tags: [Users]
      summary: Update authenticated user profile
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/v2/profile/update/password:
    put:
      tags: [Users]
      summary: Update authenticated user password
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/v2/students:
    get:
      tags: [Students]
      summary: List students
      responses:
        '200':
          description: Student list
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags: [Students]
      summary: Create student
      responses:
        '201':
          description: Student created
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/v2/students/{studentId}:
    get:
      tags: [Students]
      summary: Get student details
      parameters:
        - $ref: '#/components/parameters/StudentId'
      responses:
        '200':
          description: Student details
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags: [Students]
      summary: Update student
      parameters:
        - $ref: '#/components/parameters/StudentId'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/v2/students/student-daily-limit:
    post:
      tags: [Students]
      summary: Update student daily spending limit
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v2/orders:
    get:
      tags: [Orders]
      summary: List orders
      responses:
        '200':
          description: Order list
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags: [Orders]
      summary: Create order
      responses:
        '201':
          description: Order created
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/v2/orders/{orderId}:
    get:
      tags: [Orders]
      summary: Get order details
      parameters:
        - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: Order details
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v2/orders/cancel:
    post:
      tags: [Orders]
      summary: Cancel order
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v2/orders/accept:
    post:
      tags: [Orders]
      summary: Accept order
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v2/orders/deliver:
    post:
      tags: [Orders]
      summary: Mark order as delivered
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v2/return-orders:
    get:
      tags: [Orders]
      summary: List return orders
      responses:
        '200':
          description: Return order list
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags: [Orders]
      summary: Create return order
      description: Source route includes auth:api and return.rate_limit middleware.
      responses:
        '201':
          description: Return order created
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v2/products:
    get:
      tags: [Products]
      summary: List products
      responses:
        '200':
          description: Product list
    post:
      tags: [Products]
      summary: Create product
      responses:
        '201':
          description: Product created
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/v2/products/{productId}:
    get:
      tags: [Products]
      summary: Get product details
      parameters:
        - $ref: '#/components/parameters/ProductId'
      responses:
        '200':
          description: Product details
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags: [Products]
      summary: Update product
      parameters:
        - $ref: '#/components/parameters/ProductId'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/v2/seller/products/activate:
    post:
      tags: [Products]
      summary: Activate seller product
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v2/seller/products/deactivate:
    post:
      tags: [Products]
      summary: Deactivate seller product
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v2/supplier-stores:
    get:
      tags: [Suppliers]
      summary: List supplier stores
      responses:
        '200':
          description: Supplier store list
  /api/v2/supplier-stores/{supplierStoreId}/products:
    get:
      tags: [Suppliers]
      summary: List products for supplier store
      parameters:
        - $ref: '#/components/parameters/SupplierStoreId'
      responses:
        '200':
          description: Product list
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v2/supplier-orders:
    get:
      tags: [Suppliers]
      summary: List supplier orders
      responses:
        '200':
          description: Supplier order list
    post:
      tags: [Suppliers]
      summary: Create supplier order
      responses:
        '201':
          description: Supplier order created
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/v2/supplier-orders/cancel:
    post:
      tags: [Suppliers]
      summary: Cancel supplier order
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v2/supplier-orders/deliver:
    post:
      tags: [Suppliers]
      summary: Mark supplier order as delivered
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/wallets/search:
    get:
      tags: [Wallets]
      summary: Search wallets
      responses:
        '200':
          description: Wallet search results
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/wallets/search-students:
    get:
      tags: [Wallets]
      summary: Search student wallets
      responses:
        '200':
          description: Student wallet search results
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v2/apple_pay/session:
    post:
      tags: [Payments]
      summary: Create Apple Pay session
      responses:
        '200':
          description: Apple Pay session
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/v2/apple_pay/transaction:
    put:
      tags: [Payments]
      summary: Submit Apple Pay transaction
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/v2/check-apple-pay:
    get:
      tags: [Payments]
      summary: Check Apple Pay service availability
      responses:
        '200':
          description: Apple Pay status
  /api/v2/notifications:
    get:
      tags: [Notifications]
      summary: List notifications
      responses:
        '200':
          description: Notification list
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v2/notifications/read:
    post:
      tags: [Notifications]
      summary: Mark notification as read
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v2/notifications/delete:
    post:
      tags: [Notifications]
      summary: Delete notification
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v2/pages/{slug}:
    get:
      tags: [Public Content]
      summary: Get public page by slug
      security: []
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Page content
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v2/contact-landings:
    post:
      tags: [Public Content]
      summary: Submit contact landing request
      security: []
      responses:
        '201':
          description: Request submitted
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API token
  parameters:
    StudentId:
      name: studentId
      in: path
      required: true
      schema:
        type: integer
    OrderId:
      name: orderId
      in: path
      required: true
      schema:
        type: integer
    ProductId:
      name: productId
      in: path
      required: true
      schema:
        type: integer
    SupplierStoreId:
      name: supplierStoreId
      in: path
      required: true
      schema:
        type: integer
  schemas:
    LoginRequest:
      type: object
      required: [email, password]
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          format: password
    AuthTokenResponse:
      type: object
      properties:
        token:
          type: string
        token_type:
          type: string
          example: Bearer
        user:
          $ref: '#/components/schemas/User'
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
  responses:
    Success:
      description: Successful operation
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    Unauthorized:
      description: Authentication is required or token is invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Authenticated user is not authorized for this action or scope
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: Request validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
