openapi: 3.0.3
info:
  title: SIMcloud API
  version: 1.0.0
  description: |
    Token-authenticated SIMcloud API for SMS, airtime, data, electricity,
    wallet balance, and network lookup.
servers:
  - url: https://simcloud.co.za
security:
  - bearerAuth: []
tags:
  - name: SMS
  - name: Airtime
  - name: Data
  - name: Electricity
  - name: Balance
  - name: Network Lookup
paths:
  /api/sms.php:
    post:
      tags: [SMS]
      summary: Queue an SMS
      operationId: sendSms
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [recipient, message]
              properties:
                recipient:
                  type: string
                  example: "+27821234567"
                message:
                  type: string
                  example: "Hello World!"
      responses:
        '200':
          description: SMS queued
        '400':
          description: Validation error
        '401':
          description: Unauthorized
    get:
      tags: [SMS]
      summary: Query SMS status
      operationId: getSmsStatus
      parameters:
        - in: query
          name: sms_id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: SMS status
        '404':
          description: SMS not found
  /api/airtime.php:
    post:
      tags: [Airtime]
      summary: Queue an airtime order
      description: The same MSISDN and amount cannot be ordered again within 5 minutes. Duplicate requests inside that window return HTTP 409.
      operationId: createAirtimeOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [msisdn, network, amount, reference]
              properties:
                msisdn:
                  type: string
                  example: "0821234567"
                network:
                  type: string
                  description: Accepts friendly names or internal codes.
                  example: "mtn"
                amount:
                  type: number
                  format: float
                  example: 10.00
                reference:
                  type: string
                  example: "Airtime for John"
      responses:
        '201':
          description: Airtime order queued
        '400':
          description: Validation or balance error
        '401':
          description: Unauthorized
        '409':
          description: Duplicate order within the 5-minute rule window
    get:
      tags: [Airtime]
      summary: Query an airtime order
      operationId: getAirtimeOrder
      parameters:
        - in: query
          name: request_id
          required: false
          schema:
            type: integer
        - in: query
          name: orderno
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Airtime order status
        '404':
          description: Order not found
  /api/data.php:
    post:
      tags: [Data]
      summary: Queue a data order
      description: The same MSISDN and amount cannot be ordered again within 5 minutes. Duplicate requests inside that window return HTTP 409.
      operationId: createDataOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [msisdn, network, amount, reference]
              properties:
                msisdn:
                  type: string
                  example: "0821234567"
                network:
                  type: string
                  description: Accepts friendly names or internal codes.
                  example: "vodacom"
                amount:
                  type: number
                  format: float
                  example: 25.00
                sellvalue:
                  type: number
                  format: float
                  description: Alias for amount.
                reference:
                  type: string
                  example: "Data for John"
      responses:
        '201':
          description: Data order queued
        '400':
          description: Validation or balance error
        '401':
          description: Unauthorized
        '409':
          description: Duplicate order within the 5-minute rule window
    get:
      tags: [Data]
      summary: Query a data order
      operationId: getDataOrder
      parameters:
        - in: query
          name: request_id
          required: false
          schema:
            type: integer
        - in: query
          name: orderno
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Data order status
        '404':
          description: Order not found
  /api/electricity.php:
    post:
      tags: [Electricity]
      summary: Submit an electricity order
      operationId: createElectricityOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [meter_number, amount, client_reference, recipient]
              properties:
                meter_number:
                  type: string
                  example: "01234567890"
                amount:
                  type: number
                  format: float
                  example: 150.00
                client_reference:
                  type: string
                  example: "INV-10045"
                recipient:
                  type: string
                  example: "0821234567"
      responses:
        '201':
          description: Electricity order accepted
        '400':
          description: Validation or balance error
        '401':
          description: Unauthorized
        '503':
          description: Electricity unavailable
    get:
      tags: [Electricity]
      summary: Query an electricity order
      operationId: getElectricityOrder
      parameters:
        - in: query
          name: order_id
          required: false
          schema:
            type: integer
        - in: query
          name: client_reference
          required: false
          schema:
            type: string
        - in: query
          name: order_reference_id
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Electricity voucher view details only
        '404':
          description: Order not found
  /api/balance.php:
    get:
      tags: [Balance]
      summary: Get wallet balance
      operationId: getWalletBalance
      responses:
        '200':
          description: Last known wallet balance
        '401':
          description: Unauthorized
  /api/network.php:
    get:
      tags: [Network Lookup]
      summary: Look up a mobile network
      operationId: lookupNetwork
      parameters:
        - in: query
          name: msisdn
          required: true
          schema:
            type: string
          example: "0821234567"
      responses:
        '200':
          description: Network found
        '400':
          description: Invalid msisdn
        '401':
          description: Unauthorized
        '404':
          description: Number does not match any network
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Token
