Public API v1 — OctoSMM

Autentifikatsiya

Har bir so‘rovda X-API-Key header yuboring. Kalitni profil sahifasidan oling yoki yangilang.

Header

X-API-Key: octo_YOUR_API_KEY

API kalitni ko‘rish uchun tizimga kiring.

Base URL

Base

https://octobuilder.uz/api/v1

Barcha endpointlar shu manzil ostida. HTTPS majburiy.

Endpointlar

Method	Path	Tavsif
GET	`/countries`	Davlatlar va narxlar
GET	`/balance`	Joriy balans
POST	`/buy`	Raqam sotib olish
GET	`/status/{id}`	Buyurtma holati / SMS
GET	`/history`	Buyurtmalar tarixi

GET /countries

Davlatlar va narxlar

Mavjud davlatlar ro‘yxati. Narxlar sizning tarifingizdagi API ustama bilan hisoblanadi.

curl

curl -s -H "X-API-Key: octo_YOUR_API_KEY" "https://octobuilder.uz/api/v1/countries"

Javob

{
  "success": true,
  "data": [
    {"code": "UZ", "name": "O'zbekiston", "price": 1.35, "qty": 42}
  ],
  "meta": {"timestamp": "2026-10-10T12:00:00+05:00"}
}

GET /balance

Balans

Hisobingizdagi joriy balans (USD).

curl

curl -s -H "X-API-Key: octo_YOUR_API_KEY" "https://octobuilder.uz/api/v1/balance"

Javob

{
  "success": true,
  "data": {
    "balance": 120.50,
    "currency": "USD"
  },
  "meta": {"timestamp": "..."}
}

POST /buy

Raqam sotib olish

Tanlangan davlat uchun virtual raqam sotib oladi. Balans, kunlik/oylik limit va provayder mavjudligi tekshiriladi.

Parametr	Tip	Majburiy	Izoh
`country`	string	Ha	ISO kod, masalan UZ, US, RU
`idempotency_key`	string	Yo‘q	Takroriy so‘rovlarni oldini olish (UUID)

curl

curl -s -X POST \
  -H "X-API-Key: octo_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"UZ"}' \
  "https://octobuilder.uz/api/v1/buy"

Javob

{
  "success": true,
  "data": {
    "id": 42,
    "number": "+998901234567",
    "country": "UZ",
    "price": 1.35,
    "balance": 119.15,
    "status": "active",
    "expires_at": "2026-10-10T12:20:00+05:00"
  }
}

GET /status/{id}

Buyurtma holati / SMS kod

Faqat o‘zingizning buyurtmangiz. SMS kelganda code maydoni to‘ldiriladi. Polling tavsiya etiladi (3–5 soniya).

Parametr	Tip	Majburiy	Izoh
`id`	integer	Ha	Buyurtma ID (path parametr)

curl

curl -s -H "X-API-Key: octo_YOUR_API_KEY" "https://octobuilder.uz/api/v1/status/42"

Javob

{
  "success": true,
  "data": {
    "id": 42,
    "status": "waiting",
    "number": "+998901234567",
    "code": null,
    "pass": null,
    "expires_at": "..."
  }
}

GET /history

Buyurtmalar tarixi

Sahifalangan ro‘yxat. Query: page, limit (max 100).

Parametr	Tip	Majburiy	Izoh
`page`	integer	Yo‘q	Default: 1
`limit`	integer	Yo‘q	Default: 20, max: 100

curl

curl -s -H "X-API-Key: octo_YOUR_API_KEY" "https://octobuilder.uz/api/v1/history?page=1&limit=20"

Javob

{
  "success": true,
  "data": {
    "items": [ ... ],
    "page": 1,
    "limit": 20,
    "total": 5,
    "pages": 1
  }
}

Xatolik kodlari

Kod	HTTP	Ma’no
`invalid_api_key`	401	Kalit yo‘q yoki noto‘g‘ri
`api_access_denied`	403	Tarif API ga ruxsat bermaydi
`insufficient_balance`	402	Balans yetarli emas
`daily_limit_exceeded`	429	Kunlik limit tugagan
`monthly_limit_exceeded`	429	Oylik limit tugagan
`rate_limit_exceeded`	429	Daqiqasiga 30 so‘rov
`country_required`	400	`country` majburiy
`country_not_found`	404	Davlat topilmadi
`not_found`	404	Buyurtma topilmadi
`provider_error`	502	Provayder xatosi

Xato javob formati:

{
  "success": false,
  "error": {
    "code": "insufficient_balance",
    "message": "Balans yetarli emas"
  }
}

Limitlar

Rate limit: daqiqasiga 30 so‘rov (API kalit bo‘yicha).
Kunlik / oylik: tarifingizdagi limitlar. Profil va status stripda ko‘rinadi.
Narx: har doim serverda hisoblanadi; client yuborgan narxga ishonilmaydi.
Idempotency: buy da idempotency_key ishlatish tavsiya etiladi.

Namunalar

PHP

$ch = curl_init('https://octobuilder.uz/api/v1/countries');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['X-API-Key: octo_YOUR_API_KEY'],
]);
$json = json_decode(curl_exec($ch), true);

Python

import requests
r = requests.get(
  "https://octobuilder.uz/api/v1/countries",
  headers={"X-API-Key": "octo_YOUR_API_KEY"}
)
print(r.json())

Node.js

const res = await fetch("https://octobuilder.uz/api/v1/countries", {
  headers: { "X-API-Key": "octo_YOUR_API_KEY" }
});
const data = await res.json();