# Omega Airtime API Documentation

## Overview
This documentation covers the external API endpoints for airtime selling flows in the Cronos system. These APIs are designed for external clients to integrate airtime recharge functionality.

## Base URL
```
http://api.omega.sendai.co.zw
```

## Authentication
The API uses PIN-based authentication with JWT tokens. All airtime operations require authentication.

### Authentication Flow
1. Create an account (if not already registered)
2. Authenticate using PIN to get JWT token
3. Include JWT token in Authorization header for subsequent requests
4. Token format: `Bearer <jwt_token>`

## Endpoints

### 1. Create Account
Create a new account in the system. This is typically the first step before authentication.

**Endpoint:** `POST /api/v1/onboarding/accounts`

**Request Body:**
```json
{
  "name": "Sean Inc",
  "type": "company",
  "level": "superagent",
  "contact_name": "Sean",
  "contact_email": "wanye@omega-solutions.net",
  "contact_phone": "0775265552",
  "address": "63 Glenelg Road Vainona",
  "city": "Harare",
  "user_firstname": "Sean",
  "user_lastname": "Omega",
  "user_email": "wanye@omega-solutions.net",
  "user_phone": "0775265552"
}
```

**Request Validation:**
- `name`: Required, account/company name
- `type`: Required, account type (e.g., "company")
- `level`: Required, account level (e.g., "superagent")
- `contact_name`: Required, primary contact person name
- `contact_email`: Required, valid email format
- `contact_phone`: Required, contact phone number
- `address`: Required, physical address
- `city`: Required, city name
- `user_firstname`: Required, user's first name
- `user_lastname`: Required, user's last name
- `user_email`: Required, user's email (valid email format)
- `user_phone`: Required, user's phone number

**Response (Success - 200):**
```json
{
  "status": "success",
  "message": "account created successfully",
  "data": {
    "id": "019886e5-01c3-70ff-87db-bbfbc642a29a",
    "name": "Sean Inc",
    "number": "9444-5339-1364",
    "address": "63 Glenelg Road Vainona",
    "city": "",
    "contact_name": "Sean",
    "contact_email": "wanye@omega-solutions.net",
    "contact_phone": "263775265552",
    "account_type": "company",
    "account_level": "superagent"
  }
}
```

**Notes:**
- Phone numbers are automatically formatted to international format (e.g., "0775265552" becomes "263775265552")
- A unique account number is automatically generated
- This endpoint does not require authentication

### 2. PIN Authentication
Authenticate user with phone number and PIN to obtain JWT token.

**Endpoint:** `POST /auth/pin-authentication`

**Request Body:**
```json
{
  "phone": "+263771234567",
  "pin": "1234"
}
```

**Request Validation:**
- `phone`: Required, must be valid phone number format
- `pin`: Required

**Response (Success - 200):**
```json
{
  "status": "success",
  "message": "authenticated",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2024-01-01T12:00:00Z"
  }
}
```

**Response (Error - 401):**
```json
{
  "message": "Invalid credentials"
}
```

### 3. PIN Reset
Reset user's PIN (sends new PIN via configured method).

**Endpoint:** `POST /auth/pin-reset`

**Request Body:**
```json
{
  "phone": "+263771234567"
}
```

**Request Validation:**
- `phone`: Required, must be valid phone number format

**Response (Success - 200):**
```json
{
  "status": "success",
  "message": "pin was rest successfully",
  "data": null
}
```

**Response (Error - 422):**
```json
{
  "message": "User not found"
}
```

### 4. Get Current User
Get authenticated user information.

**Endpoint:** `GET /auth/user`

**Headers:**
```
Authorization: Bearer <jwt_token>
```

**Response (Success - 200):**
```json
{
  "status": "success",
  "message": "user retrieved",
  "data": {
    "id": "user-id",
    "email": "user@example.com",
    "phone": "+263771234567",
    "account_id": "account-id"
  }
}
```

### 5. Single Airtime Recharge
Credit airtime to a phone number.

**Endpoint:** `POST /api/v1/recharges/airtime`

**Headers:**
```
Authorization: Bearer <jwt_token>
```

**Request Body:**
```json
{
  "phone": "+263771234567",
  "amount": 100,
  "currency": "USD",
  "reference": "unique-reference-123"
}
```

**Request Validation:**
- `phone`: Required, must be valid phone number format
- `amount`: Required, integer amount in cents/smallest currency unit
- `currency`: Required, currency code (e.g., "USD", "ZWL")
- `reference`: Required, unique transaction reference

**Response (Success - 200):**
```json
{
  "status": "success",
  "message": "successful airtime recharge",
  "data": {
    "transaction_id": "txn-12345",
    "reference": "unique-reference-123",
    "phone": "+263771234567"
  }
}
```

**Response (Insufficient Funds - 422):**
```json
{
  "status": "error",
  "message": "Insufficient funds",
  "data": null
}
```

**Response (Wallet Not Found - 422):**
```json
{
  "status": "error",
  "message": "Wallet not found",
  "data": null
}
```

**Rate Limiting:** This endpoint is rate-limited based on server configuration.

### 6. Batch Airtime Recharge
Process multiple airtime recharges in batch.

**Endpoint:** `POST /api/v1/recharges/airtime/batch`

**Request Body:**
```json
{
  "account": "account-id",
  "recharges": [
    {
      "phone": "+263771234567",
      "amount": 100,
      "currency": "USD",
      "reference": "ref-001"
    },
    {
      "phone": "+263779876543",
      "amount": 200,
      "currency": "USD",
      "reference": "ref-002"
    }
  ]
}
```

**Response (Success - 200):**
```json
{
  "status": "success",
  "message": "batch recharge created",
  "data": {
    "batch_id": "batch-12345",
    "total_count": 2,
    "status": "processing"
  }
}
```

## Error Handling

### Standard Error Response Format
```json
{
  "status": "error",
  "message": "Error description",
  "data": null
}
```

### Common HTTP Status Codes
- `200` - Success
- `400` - Bad Request (validation errors)
- `401` - Unauthorized (authentication required/invalid)
- `422` - Unprocessable Entity (business logic errors)
- `429` - Too Many Requests (rate limited)
- `500` - Internal Server Error

### Common Error Scenarios
1. **Invalid Phone Number:** Phone number format validation fails
2. **Insufficient Funds:** User's wallet balance is insufficient for the recharge
3. **Wallet Not Found:** User doesn't have a wallet in the specified currency
4. **Rate Limiting:** Too many requests in the rate limit window
5. **Invalid PIN:** Authentication fails due to incorrect PIN
6. **User Not Found:** Phone number is not registered in the system

## Integration Notes

### Phone Number Format
- Must be in international format (e.g., +263771234567)
- System validates phone number format before processing
- During account creation, local format numbers are automatically converted to international format

### Currency Handling
- Amounts are specified in the smallest currency unit (cents for USD, etc.)
- Supported currencies depend on server configuration

### Transaction References
- Must be unique per transaction
- Used for idempotency and tracking
- Recommended format: timestamp-based or UUID

### Authentication Best Practices
- Store JWT tokens securely
- Handle token expiration gracefully
- Implement proper logout functionality

### Rate Limiting
- Single airtime endpoint has rate limiting enabled
- Monitor response headers for rate limit information
- Implement proper backoff strategies

## Security Considerations
- All communication must be over HTTPS
- JWT tokens have expiration times
- PIN-based authentication provides additional security layer
- Rate limiting prevents abuse