openapi: 3.0.3
info:
  title: LotConnect Umbrella API
  description: Official B2B API gateway connecting 3rd-party parking hardware vendors to super-apps (Kaspi, Yandex, etc.) under the NGParking network.
  version: 1.0.0
  contact:
    name: LotConnect Integration Team
    email: api@lotconnect.kz

servers:
  - url: https://api.lotconnect.kz/api/v1
    description: Production Environment
  - url: https://sandbox.lotconnect.kz/api/v1
    description: Developer Sandbox Environment

components:
  securitySchemes:
    ProviderApiKey:
      type: apiKey
      in: header
      name: X-Provider-API-Key
      description: API Key for Super-Apps (e.g. Kaspi, Yandex) to pull data and process payments.
    VendorApiKey:
      type: apiKey
      in: header
      name: X-Vendor-API-Key
      description: API Key for 3rd-Party Parking Hardware Vendors to push local events to LotConnect.

paths:
  /providers/events/entry:
    post:
      summary: Report Vehicle Entry
      description: (Used by Hardware Vendors) Pushes a vehicle entry event to the LotConnect network.
      security:
        - VendorApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [vendor_lot_id, plate_number, timestamp]
              properties:
                vendor_lot_id:
                  type: string
                  example: "vendor_12345"
                plate_number:
                  type: string
                  example: "123ABC02"
                timestamp:
                  type: string
                  format: date-time
      responses:
        '200':
          description: Event successfully accepted and pushed to Kaspi/Yandex.
        '401':
          description: Unauthorized. Invalid Vendor API Key.

  /providers/events/exit:
    post:
      summary: Request Exit Authorization
      description: (Used by Hardware Vendors) Reports a vehicle attempting to exit. LotConnect instantly verifies payment with Kaspi/Yandex and authorizes the barrier.
      security:
        - VendorApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [vendor_lot_id, plate_number, timestamp, amount_kzt]
              properties:
                vendor_lot_id:
                  type: string
                  example: "vendor_12345"
                plate_number:
                  type: string
                  example: "123ABC02"
                timestamp:
                  type: string
                  format: date-time
                amount_kzt:
                  type: integer
                  example: 500
      responses:
        '200':
          description: Payment cleared via Super-App. Exit authorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  exit_authorized:
                    type: boolean
                    example: true
                  paid_at:
                    type: string
                    format: date-time
        '402':
          description: Payment Failed. Do not open barrier.