openapi: 3.0.3
info:
  title: ESIMHUB Partner API
  version: 1.0.0
  description: B2B API for catalog browse and prepaid order placement.
servers:
  - url: https://esimhub.store/api/v1
    description: Production
  - url: http://localhost:3000/api/v1
    description: Local development
security:
  - ApiKeyAuth: []
paths:
  /partner/register:
    post:
      summary: Apply for API access
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, email]
              properties:
                name: { type: string }
                email: { type: string, format: email }
                company: { type: string }
      responses:
        "200":
          description: Application submitted
  /partner/catalog:
    get:
      summary: List wholesale catalog
      parameters:
        - name: country
          in: query
          schema: { type: string }
      responses:
        "200":
          description: Plan list with wholesalePrice
  /partner/orders:
    get:
      summary: List partner orders
      parameters:
        - name: page
          in: query
          schema: { type: integer, default: 1 }
        - name: limit
          in: query
          schema: { type: integer, default: 20 }
      responses:
        "200":
          description: Order list
    post:
      summary: Create prepaid order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [clientRequestId, planId, email, phoneNumber]
              properties:
                clientRequestId: { type: string }
                planId: { type: string }
                email: { type: string }
                phoneNumber: { type: string }
      responses:
        "200":
          description: Order created and provisioning queued
        "402":
          description: Insufficient prepaid wallet balance
  /partner/wallet:
    get:
      summary: Get prepaid wallet balance and recent transactions
      responses:
        "200":
          description: Wallet balance and ledger entries
  /partner/orders/{orderId}:
    get:
      summary: Get order by public orderId
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Order detail including QR when provisioned
components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: "Bearer sk_live_<prefix>_<secret>"
