# OTPly API Documentation

> **For AI Assistants:** This is the complete technical reference for integrating the OTPly WhatsApp OTP API. Read this fully before writing any integration code. Everything you need — endpoint, parameters, responses, error codes, and working examples — is here.

---

## Overview

OTPly sends OTPs to Indian mobile numbers via WhatsApp. Integration is a single HTTP GET request — no SDK, no setup needed.

---

## Endpoint

```
GET https://api.adeptcode.in/api.php
```

---

## Parameters

| Parameter | Type   | Required | Description                          |
|-----------|--------|----------|--------------------------------------|
| `api_key` | string | Yes      | Your OTPly API key                   |
| `mobile`  | string | Yes      | 10-digit Indian mobile number        |
| `otp`     | string | Yes      | 4–6 digit numeric OTP to send        |

---

## Example Request

```
GET https://api.adeptcode.in/api.php?api_key=YOUR_API_KEY&mobile=9876543210&otp=4521
```

---

## Response Format

All responses return JSON.

**Success**
```json
{
  "status": "success",
  "code": "OTP_SENT",
  "message": "OTP sent via WhatsApp.",
  "balance": 98,
  "mobile": "+91-9876543210"
}
```

**Error**
```json
{
  "status": "error",
  "code": "INSUFFICIENT_CREDITS",
  "message": "Balance zero hai."
}
```

---

## Error Codes

| Code                   | Description                                  |
|------------------------|----------------------------------------------|
| `INVALID_API_KEY`      | API key not found                            |
| `API_INACTIVE`         | Key is deactivated                           |
| `MISSING_PARAMS`       | `api_key`, `mobile`, or `otp` is missing     |
| `INSUFFICIENT_CREDITS` | Not enough balance                           |
| `INVALID_MOBILE`       | Invalid Indian mobile (must be 6–9 start)    |
| `INVALID_OTP`          | OTP must be 4–6 digits                       |
| `RATE_LIMIT_MINUTE`    | Too many OTPs per minute to same number      |
| `RATE_LIMIT_DAY`       | Daily limit exceeded for that number         |
| `SEND_FAILED`          | WhatsApp delivery failed                     |
| `NETWORK_ERROR`        | Upstream network error                       |

---

## Code Examples

### cURL
```bash
curl "https://api.adeptcode.in/api.php?api_key=YOUR_API_KEY&mobile=9876543210&otp=4521"
```

---

### PHP
```php
<?php
$otp    = rand(1000, 9999);
$apiKey = 'YOUR_API_KEY';
$mobile = '9876543210';

$url = 'https://api.adeptcode.in/api.php?' . http_build_query([
    'api_key' => $apiKey,
    'mobile'  => $mobile,
    'otp'     => $otp,
]);

$response = json_decode(file_get_contents($url), true);

if ($response['status'] === 'success') {
    // OTP sent! Store $otp and verify later.
    echo "OTP sent. Balance: " . $response['balance'];
} else {
    echo "Error: " . $response['message'];
}
```

---

### JavaScript (Node.js / backend only)
```javascript
// ⚠️ Use from backend/server only!
const otp    = Math.floor(1000 + Math.random() * 9000);
const apiKey = 'YOUR_API_KEY';
const mobile = '9876543210';

const url = `https://api.adeptcode.in/api.php?api_key=${apiKey}&mobile=${mobile}&otp=${otp}`;

const res  = await fetch(url);
const data = await res.json();

if (data.status === 'success') {
    console.log('OTP sent! Balance:', data.balance);
} else {
    console.error('Error:', data.message);
}
```

---

### Python
```python
import requests
import random

otp     = random.randint(1000, 9999)
api_key = 'YOUR_API_KEY'
mobile  = '9876543210'

url = 'https://api.adeptcode.in/api.php'
params = {
    'api_key': api_key,
    'mobile':  mobile,
    'otp':     otp,
}

response = requests.get(url, params=params)
data = response.json()

if data['status'] == 'success':
    print(f"OTP sent! Balance: {data['balance']}")
else:
    print(f"Error: {data['message']}")
```

---

## OTP Verification

OTPly only **delivers** the OTP — it does not verify it. You must verify on your side.

```php
// When the user submits the OTP form:
$entered = trim($_POST['otp']);

// Check expiry (5 minutes)
if (time() - $_SESSION['otp_sent_at'] > 300) {
    unset($_SESSION['otp']);
    die("OTP expired. Request a new one.");
}

if ($entered === (string) $_SESSION['otp']) {
    unset($_SESSION['otp']); // invalidate after use
    echo "Verified!";
} else {
    echo "Wrong OTP. Try again.";
}
```

---

## Security Notes

- Never put the API key in frontend JavaScript or browser code.
- Always validate the mobile number before calling the API. Indian numbers match `/^[6-9][0-9]{9}$/`.
- Store the sent OTP in a server-side session, not in a cookie or localStorage.
- Expire OTPs after 5 minutes and invalidate them after one successful use.
- Only store the OTP in session if `status === "success"` — do not store if the send failed.

---

*OTPly — WhatsApp OTP delivery for Indian developers.*