Документация API

Язык

Документация API

Простой API для автоматизации заказов OTP: проверка баланса, пополнение, получение списка услуг и стран, покупка номера, приём OTP, отмена или завершение заказа.

Базовый URL

https://noksstsar.site/api/v1

Аутентификация Лимит запросов Формат ответа Эндпоинты Пополнение баланса Порядок заказа

Аутентификация

Каждый запрос должен содержать ваш API-ключ. Передайте его одним из способов:

Authorization: Bearer YOUR_API_KEY
X-Api-Key: YOUR_API_KEY
?apikey=YOUR_API_KEY

🔑 Войти затем откройте «Настройки API», чтобы получить свой ключ.

Ключ действует только на этом домене. Держите его в секрете — ключ даёт полный доступ к вашему балансу и заказам.

Лимит запросов

Чтение (GET)	120 запросов / мин.
Изменения (POST)	30 запросов / мин.

Квота считается по каждому API-ключу. При превышении ответ — 429 Too Many Requests. Заголовок Retry-After показывает, сколько секунд подождать.

Формат ответа

Всегда JSON. Все денежные суммы — в рупиях (IDR), целые числа.

Успех

{ "success": true, "data": ... }

Ошибка

{ "success": false, "message": "penjelasan error" }

HTTP-коды: 200 успешно · 401 неверный ключ · 422 неверные данные / ошибка · 429 слишком много запросов · 504 медленное соединение (см. примечание к заказу).

Эндпоинты

GET/balance

Баланс клиента. `held` — средства, удерживаемые в активных заказах, `active_count` — количество текущих заказов.

Пример

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://noksstsar.site/api/v1/balance

Ответ

{ "success": true, "data": { "balance": 50000, "held": 3148, "active_count": 1 } }

GET/services

Список услуг (WhatsApp, Telegram и т. д.).

Параметры (необязательно)

q	поиск по названию услуги
page	страница (по умолчанию 1)
limit	на странице (по умолчанию 10, макс. 50)

Пример

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://noksstsar.site/api/v1/services?q=whatsapp&limit=20"

Ответ

{ "success": true, "data": [
  { "id": 1, "name": "WhatsApp", "service_image": "https://..." }
] }

GET/services/{service_id}/countries

Страны, доступные для услуги, и цена продажи (IDR). Используйте `country_id` при заказе.

Пример

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://noksstsar.site/api/v1/services/1/countries

Ответ

{ "success": true, "data": [
  { "country_id": 6, "country_name": "Indonesia", "country_code": "id", "price": 1200 }
] }

POST/order

Купить номер для OTP. С баланса списывается цена выбранной страны.

Тело запроса

service_id *	id услуги
country_id *	id страны
operator	конкретный оператор (по умолчанию "any")
max_price_usd	предел цены; выбирается самый дешёвый тариф ≤ этого значения
request_id	ключ идемпотентности (см. примечание про 504)

Пример

curl -X POST https://noksstsar.site/api/v1/order \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service_id":1,"country_id":6,"request_id":"my-uniq-123"}'

Ответ

{ "success": true, "data": {
  "id": 9001, "phone_number": "628123456789",
  "service_name": "WhatsApp", "country_name": "Indonesia",
  "price": 1200, "status": "active",
  "sms_code": null, "sms_data": [], "expired_at": "2026-07-13T21:20:00+07:00"
} }

⚠️ Если пришёл 504 (retry_safe), НЕ создавайте новый заказ — номер мог уже быть выдан. Повторите с тем же `request_id` или проверьте `/orders/active`.

GET/orders/active

Все текущие заказы (ожидают OTP или уже получили его).

Пример

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://noksstsar.site/api/v1/orders/active

GET/order/{id}

Статус одного заказа и последний OTP. Опрашивайте периодически (например, каждые 3–5 секунд), пока ждёте OTP. Поле `sms_code` заполняется, когда OTP приходит.

Ответ (OTP получен)

{ "success": true, "data": {
  "id": 9001, "status": "active", "phone_number": "628123456789",
  "sms_code": "123456",
  "sms_data": [ { "text": "Your code is 123456", "code": "123456" } ]
} }

POST/order/cancel

Отменить заказ. Баланс возвращается, если SMS ещё не пришло. Отмена невозможна, если OTP уже получен (или это арендованный номер).

curl -X POST https://noksstsar.site/api/v1/order/cancel \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_id":9001}'

POST/order/request-sms

Запросить новое SMS/OTP на тот же номер (только для заказов, которые это поддерживают, после первого SMS).

curl -X POST https://noksstsar.site/api/v1/order/request-sms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_id":9001}'

POST/order/finish

Отметить заказ завершённым (SMS должно быть получено). После завершения заказ уходит в историю.

curl -X POST https://noksstsar.site/api/v1/order/finish \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_id":9001}'

POST/deposit

Пополнить баланс. QRIS (оплата в рупиях) или Crypto (оплата в USD через шлюз). Баланс пополняется автоматически после подтверждения платежа.

Тело запроса

method *	"qris" или "crypto"
amount	QRIS: сумма в IDR (2 000 – 2 000 000)
amount_usd	Crypto: сумма в USD (1 – 1000)

Пример (QRIS)

curl -X POST https://noksstsar.site/api/v1/deposit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method":"qris","amount":10000}'

Ответ (QRIS)

{ "success": true, "data": {
  "id": 5501, "code": "RCD-XXXX", "amount": 10000,
  "qr_string": "00020101...6304ABCD",
  "qr_image_base64": "data:image/png;base64,iVBOR...",
  "expired_at": "2026-07-13T21:40:00+07:00"
} }

Отобразите `qr_image_base64` как изображение или сформируйте QR сами из `qr_string`. Для Crypto в ответе есть `payment_url` — направьте клиента туда.

Пример (Crypto)

curl -X POST https://noksstsar.site/api/v1/deposit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method":"crypto","amount_usd":5}'

GET/deposit/{id}

Статус одного пополнения. `status` = "pending" (не оплачено) / "paid" (оплачено → баланс зачислен) / "expired". Опрашивайте после создания пополнения или просто следите за /balance.

Ответ

{ "success": true, "data": {
  "id": 5501, "code": "RCD-XXXX", "amount": 10000,
  "status": "paid", "method": "iskapay",
  "paid_at": "2026-07-13T21:31:00+07:00", "expired_at": "2026-07-13T21:40:00+07:00"
} }

Типичный порядок заказа

GET /services → выберите `id` услуги.
GET /services/{id}/countries → выберите `country_id`.
POST /order → получите `id` заказа и номер.
GET /order/{id} повторно, пока не заполнится `sms_code` (OTP пришёл).
POST /order/finish (завершить) или /order/cancel (если OTP не пришёл → возврат).