مستندات API
REST API v1 و endpointهای سازگار با SMS-Activate
معرفی
API به شما امکان میدهد با موجودی حساب خود شماره مجازی بخرید، کدهای SMS دریافتی را بخوانید و برای بازپرداخت لغو کنید. همه درخواستها از HTTPS استفاده میکنند و پاسخها JSON هستند.
- آدرس پایه
https://codesms.org- قالب
- JSON (
application/json) — form-encoded هم پذیرفته میشود - ارز
- TRY (₺)
- پاسخ موفق
{"success": true, "data": ...}- پاسخ خطا
{"success": false, "error": {"code": "NO_BALANCE", "message": "..."}}
احراز هویت
کلید API خود را همراه هر درخواست ارسال کنید. کلید را میتوانید از صفحه API در پنل خود دریافت کنید.
curl "https://codesms.org/api/v1/balance" \
-H "X-API-Key: YOUR_API_KEY"$ch = curl_init('https://codesms.org/api/v1/balance');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY']]);requests.get("https://codesms.org/api/v1/balance", headers={"X-API-Key": "YOUR_API_KEY"})fetch("https://codesms.org/api/v1/balance", { headers: { "X-API-Key": "YOUR_API_KEY" } })روشهای جایگزین: هدر Authorization: Bearer YOUR_API_KEY یا پارامتر ?api_key=YOUR_API_KEY (فقط برای تست؛ ممکن است کلید در لاگها ثبت شود).
- API روی حسابهایی با ایمیل تأییدنشده کار نمیکند (EMAIL_NOT_VERIFIED).
- میتوانید در پنل فهرست IPهای مجاز تعریف کنید؛ در صورت تنظیم، درخواستها فقط از همان آدرسها پذیرفته میشوند.
- اگر کلید شما فاش شد، فوراً آن را در پنل بازسازی کنید؛ کلید قبلی بلافاصله نامعتبر میشود.
شروع سریع
خرید شماره ← انتظار برای کد ← پایان. اگر کدی نرسید، برای بازپرداخت لغو کنید.
<?php
$base = 'https://codesms.org';
$key = 'YOUR_API_KEY';
function api($method, $path, $body = null) {
global $base, $key;
$ch = curl_init($base . $path);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => ['X-API-Key: ' . $key, 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => $body ? json_encode($body) : null]);
return json_decode(curl_exec($ch), true);
}
$r = api('POST', '/api/v1/activations', ['service' => 'tg', 'country' => 'tr']);
if (!$r['success']) { exit('Hata: ' . $r['error']['code']); }
$id = $r['data']['id'];
echo "Numara: {$r['data']['phone']}\n";
for ($i = 0; $i < 120; $i++) { // en fazla ~6 dk
sleep(3);
$s = api('GET', "/api/v1/activations/$id")['data'];
if ($s['status'] === 'received') { echo "Kod: {$s['code']}\n"; api('POST', "/api/v1/activations/$id/finish"); exit; }
if (in_array($s['status'], ['canceled', 'expired', 'failed'])) exit("Bitti: {$s['status']}\n");
}
api('POST', "/api/v1/activations/$id/cancel"); // kod gelmedi: iptal et, ücret iadeimport time, requests
BASE = "https://codesms.org"
HEAD = {"X-API-Key": "YOUR_API_KEY"}
r = requests.post(f"{BASE}/api/v1/activations", headers=HEAD, json={"service": "tg", "country": "tr"}).json()
if not r["success"]:
raise SystemExit(f"Hata: {r['error']['code']}")
act = r["data"]
print("Numara:", act["phone"])
for _ in range(120): # en fazla ~6 dk
time.sleep(3)
s = requests.get(f"{BASE}/api/v1/activations/{act['id']}", headers=HEAD).json()["data"]
if s["status"] == "received":
print("Kod:", s["code"])
requests.post(f"{BASE}/api/v1/activations/{act['id']}/finish", headers=HEAD)
break
if s["status"] in ("canceled", "expired", "failed"):
break
else:
requests.post(f"{BASE}/api/v1/activations/{act['id']}/cancel", headers=HEAD) # ücret iadeconst BASE = "https://codesms.org";
const HEAD = { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" };
const api = (method, path, body) => fetch(BASE + path, { method, headers: HEAD, body: body && JSON.stringify(body) }).then(r => r.json());
const r = await api("POST", "/api/v1/activations", { service: "tg", country: "tr" });
if (!r.success) throw new Error(r.error.code);
const { id, phone } = r.data;
console.log("Numara:", phone);
for (let i = 0; i < 120; i++) { // en fazla ~6 dk
await new Promise(res => setTimeout(res, 3000));
const s = (await api("GET", `/api/v1/activations/${id}`)).data;
if (s.status === "received") { console.log("Kod:", s.code); await api("POST", `/api/v1/activations/${id}/finish`); process.exit(0); }
if (["canceled", "expired", "failed"].includes(s.status)) process.exit(1);
}
await api("POST", `/api/v1/activations/${id}/cancel`); // ücret iadeچرخه عمر فعالسازی
| status | معنی | اقدامات ممکن |
|---|---|---|
waiting | شماره صادر شد، در انتظار SMS. | استعلام، لغو (اگر can_cancel=true). |
received | SMS رسید؛ در فیلد code. | از کد استفاده کنید و پایان دهید؛ اگر can_retry=true بود، SMS دیگری درخواست کنید. |
completed | تکمیل شد (کد استفاده شد). | — |
canceled | لغو شد، بازپرداخت شد. | — |
expired | زمان به پایان رسید، SMS نیامد؛ بازپرداخت شد. | — |
failed | دریافت شماره ممکن نشد؛ بازپرداخت شد. | — |
وجود دکمههای لغو، ارسال مجدد پیامک و پایان به شماره و سرویس بستگی دارد: فیلدهای can_cancel، can_retry و can_finish را در پاسخ بررسی کنید. اگر cancel_in > 0 باشد، باید به اندازه آن تعداد ثانیه صبر کنید تا لغو کنید.
دریافت موجودی
موجودی فعلی حساب شما را برمیگرداند.
curl "https://codesms.org/api/v1/balance" \
-H "X-API-Key: YOUR_API_KEY"$ch = curl_init('https://codesms.org/api/v1/balance');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY'],
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);import requests
response = requests.get(
"https://codesms.org/api/v1/balance",
headers={"X-API-Key": "YOUR_API_KEY"}
)
print(response.json())const response = await fetch("https://codesms.org/api/v1/balance", {
method: "GET",
headers: {
"X-API-Key": "YOUR_API_KEY"
}
});
console.log(await response.json());package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://codesms.org/api/v1/balance", nil)
req.Header.Set("X-API-Key", "YOUR_API_KEY")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var response = await client.GetAsync("https://codesms.org/api/v1/balance");
Console.WriteLine(await response.Content.ReadAsStringAsync());HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://codesms.org/api/v1/balance"))
.header("X-API-Key", "YOUR_API_KEY")
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());require 'net/http'
require 'json'
uri = URI("https://codesms.org/api/v1/balance")
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = 'YOUR_API_KEY'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body{
"success": true,
"data": {
"balance": 125.5,
"currency": "TRY"
}
}فهرست سرویسها
Stokta numarası bulunan servisler, en düşük fiyat ve toplam stokla.
curl "https://codesms.org/api/v1/services" \
-H "X-API-Key: YOUR_API_KEY"$ch = curl_init('https://codesms.org/api/v1/services');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY'],
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);import requests
response = requests.get(
"https://codesms.org/api/v1/services",
headers={"X-API-Key": "YOUR_API_KEY"}
)
print(response.json())const response = await fetch("https://codesms.org/api/v1/services", {
method: "GET",
headers: {
"X-API-Key": "YOUR_API_KEY"
}
});
console.log(await response.json());package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://codesms.org/api/v1/services", nil)
req.Header.Set("X-API-Key", "YOUR_API_KEY")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var response = await client.GetAsync("https://codesms.org/api/v1/services");
Console.WriteLine(await response.Content.ReadAsStringAsync());HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://codesms.org/api/v1/services"))
.header("X-API-Key", "YOUR_API_KEY")
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());require 'net/http'
require 'json'
uri = URI("https://codesms.org/api/v1/services")
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = 'YOUR_API_KEY'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body{
"success": true,
"data": [
{
"code": "tg",
"slug": "telegram",
"name": "Telegram",
"min_price": 2.1,
"stock": 18540
}
]
}فهرست کشورها
کشورهایی که شماره موجود دارند. "id" کد عددی کشور سازگار با SMS-Activate است.
curl "https://codesms.org/api/v1/countries" \
-H "X-API-Key: YOUR_API_KEY"$ch = curl_init('https://codesms.org/api/v1/countries');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY'],
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);import requests
response = requests.get(
"https://codesms.org/api/v1/countries",
headers={"X-API-Key": "YOUR_API_KEY"}
)
print(response.json())const response = await fetch("https://codesms.org/api/v1/countries", {
method: "GET",
headers: {
"X-API-Key": "YOUR_API_KEY"
}
});
console.log(await response.json());package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://codesms.org/api/v1/countries", nil)
req.Header.Set("X-API-Key", "YOUR_API_KEY")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var response = await client.GetAsync("https://codesms.org/api/v1/countries");
Console.WriteLine(await response.Content.ReadAsStringAsync());HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://codesms.org/api/v1/countries"))
.header("X-API-Key", "YOUR_API_KEY")
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());require 'net/http'
require 'json'
uri = URI("https://codesms.org/api/v1/countries")
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = 'YOUR_API_KEY'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body{
"success": true,
"data": [
{
"iso": "tr",
"id": 62,
"name": "Turkey",
"name_tr": "Türkiye",
"dial": "90"
}
]
}قیمت و موجودی
قیمت و موجودی فعلی برای هر سرویس/کشور. فراخوانی بدون فیلتر کل فهرست را برمیگرداند (تا ۲۰٬۰۰۰ ردیف).
| پارامتر | نوع | توضیحات | |
|---|---|---|---|
| service | string | اختیاری | کد یا شناسه سرویس (مثلاً tg). |
| country | string | اختیاری | کد ISO کشور (tr) یا شناسه عددی (62). |
| servers | integer | اختیاری | If set to 1 (service and country must both be given), the price, stock and success rate of each "Server N" are also returned in the "servers" array. Pass that number as the server parameter when buying. |
curl "https://codesms.org/api/v1/prices?service=tg&country=tr&servers=1" \
-H "X-API-Key: YOUR_API_KEY"$ch = curl_init('https://codesms.org/api/v1/prices?service=tg&country=tr&servers=1');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY'],
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);import requests
response = requests.get(
"https://codesms.org/api/v1/prices?service=tg&country=tr&servers=1",
headers={"X-API-Key": "YOUR_API_KEY"}
)
print(response.json())const response = await fetch("https://codesms.org/api/v1/prices?service=tg&country=tr&servers=1", {
method: "GET",
headers: {
"X-API-Key": "YOUR_API_KEY"
}
});
console.log(await response.json());package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://codesms.org/api/v1/prices?service=tg&country=tr&servers=1", nil)
req.Header.Set("X-API-Key", "YOUR_API_KEY")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var response = await client.GetAsync("https://codesms.org/api/v1/prices?service=tg&country=tr&servers=1");
Console.WriteLine(await response.Content.ReadAsStringAsync());HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://codesms.org/api/v1/prices?service=tg&country=tr&servers=1"))
.header("X-API-Key", "YOUR_API_KEY")
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());require 'net/http'
require 'json'
uri = URI("https://codesms.org/api/v1/prices?service=tg&country=tr&servers=1")
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = 'YOUR_API_KEY'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body{
"success": true,
"data": [
{
"service": "tg",
"country": "tr",
"price": 8.5,
"currency": "TRY",
"stock": 420,
"success_rate": 87,
"servers": [
{
"server": 3,
"price": 8.5,
"stock": 300,
"success_rate": 91
},
{
"server": 7,
"price": 9.2,
"stock": 120,
"success_rate": null
}
]
}
]
}خرید شماره
یک فعالسازی (شماره) جدید باز میکند و مبلغ از موجودی شما کسر میشود. در صورت کافی نبودن موجودی NO_BALANCE و در صورت نبود موجودی شماره NO_NUMBERS برمیگرداند. اگر پیامکی نرسد یا لغو کنید، هزینه بهطور خودکار بازگردانده میشود. توصیه: با هر خرید یک هدر Idempotency-Key یکتا ارسال کنید؛ اگر پس از خطای شبکه با همان کلید دوباره تلاش کنید، شماره دومی خریداری نمیشود و همان فعالسازی اول برگردانده میشود (معتبر به مدت ۲۴ ساعت).
| پارامتر | نوع | توضیحات | |
|---|---|---|---|
| service | string | الزامی | کد یا شناسه سرویس (مثلاً tg). |
| country | string | الزامی | کد ISO کشور (tr) یا شناسه عددی (62). |
| max_price | number | اختیاری | بالاترین قیمتی (TRY) که میپذیرید. در صورت عدم ارسال، پایینترین قیمت فهرستشده اعمال میشود؛ اگر قیمت از آن بیشتر شود، PRICE_CHANGED برگردانده میشود. |
| server | integer | اختیاری | Buy only from this "Server N" (GET /api/v1/prices?servers=1). When given, no other server is tried; NO_NUMBERS is returned if it has none, PRICE_CHANGED if its price exceeds max_price. If omitted, all servers are tried in price order. |
curl -X POST "https://codesms.org/api/v1/activations" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"service":"tg","country":"tr"}'$ch = curl_init('https://codesms.org/api/v1/activations');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY', 'Content-Type: application/json'],
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode(['service' => 'tg', 'country' => 'tr']),
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);import requests
response = requests.post(
"https://codesms.org/api/v1/activations",
headers={"X-API-Key": "YOUR_API_KEY"},
json={"service": "tg", "country": "tr"}
)
print(response.json())const response = await fetch("https://codesms.org/api/v1/activations", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({"service":"tg","country":"tr"})
});
console.log(await response.json());package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("POST", "https://codesms.org/api/v1/activations", bytes.NewBufferString(`{"service":"tg","country":"tr"}`))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-Key", "YOUR_API_KEY")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var response = await client.PostAsync("https://codesms.org/api/v1/activations", new StringContent("{\"service\":\"tg\",\"country\":\"tr\"}", System.Text.Encoding.UTF8, "application/json"));
Console.WriteLine(await response.Content.ReadAsStringAsync());HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://codesms.org/api/v1/activations"))
.header("X-API-Key", "YOUR_API_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString("{\"service\":\"tg\",\"country\":\"tr\"}"))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());require 'net/http'
require 'json'
uri = URI("https://codesms.org/api/v1/activations")
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = 'YOUR_API_KEY'
req['Content-Type'] = 'application/json'
req.body = '{"service":"tg","country":"tr"}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body{
"success": true,
"data": {
"id": 1234,
"status": "waiting",
"phone": "+905551234567",
"code": null,
"text": null,
"service": {
"code": "tg",
"name": "Telegram"
},
"country": {
"iso": "tr",
"name": "Turkey",
"dial": "90"
},
"server": 3,
"price": 8.5,
"currency": "TRY",
"created_at": "2026-01-15T10:00:00+03:00",
"expires_at": "2026-01-15T10:20:00+03:00",
"retry_count": 0,
"can_cancel": true,
"can_retry": false,
"can_finish": false,
"cancel_in": 0
}
}وضعیت فعالسازی / کد پیامک
وضعیت فعالسازی و در صورت دریافت، کد پیامک را برمیگرداند. تا رسیدن کد هر ۳ تا ۵ ثانیه بررسی کنید (در صورت استفاده از وبهوک لازم نیست).
| پارامتر | نوع | توضیحات | |
|---|---|---|---|
| id | integer | الزامی | شناسه فعالسازی (پارامتر مسیر). |
curl "https://codesms.org/api/v1/activations/1234" \
-H "X-API-Key: YOUR_API_KEY"$ch = curl_init('https://codesms.org/api/v1/activations/1234');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY'],
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);import requests
response = requests.get(
"https://codesms.org/api/v1/activations/1234",
headers={"X-API-Key": "YOUR_API_KEY"}
)
print(response.json())const response = await fetch("https://codesms.org/api/v1/activations/1234", {
method: "GET",
headers: {
"X-API-Key": "YOUR_API_KEY"
}
});
console.log(await response.json());package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://codesms.org/api/v1/activations/1234", nil)
req.Header.Set("X-API-Key", "YOUR_API_KEY")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var response = await client.GetAsync("https://codesms.org/api/v1/activations/1234");
Console.WriteLine(await response.Content.ReadAsStringAsync());HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://codesms.org/api/v1/activations/1234"))
.header("X-API-Key", "YOUR_API_KEY")
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());require 'net/http'
require 'json'
uri = URI("https://codesms.org/api/v1/activations/1234")
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = 'YOUR_API_KEY'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body{
"success": true,
"data": {
"status": "received",
"code": "482913",
"text": "Your Telegram code: 482913",
"can_cancel": false,
"can_retry": true,
"can_finish": true,
"id": 1234,
"phone": "+905551234567",
"service": {
"code": "tg",
"name": "Telegram"
},
"country": {
"iso": "tr",
"name": "Turkey",
"dial": "90"
},
"server": 3,
"price": 8.5,
"currency": "TRY",
"created_at": "2026-01-15T10:00:00+03:00",
"expires_at": "2026-01-15T10:20:00+03:00",
"retry_count": 0,
"cancel_in": 0
}
}فهرست فعالسازیها
آخرین فعالسازیهای شما (جدیدترین در ابتدا).
| پارامتر | نوع | توضیحات | |
|---|---|---|---|
| status | string | اختیاری | waiting، received، completed، canceled، expired، failed |
| limit | integer | اختیاری | ۱ تا ۱۰۰ (پیشفرض ۳۰). |
curl "https://codesms.org/api/v1/activations?status=waiting&limit=20" \
-H "X-API-Key: YOUR_API_KEY"$ch = curl_init('https://codesms.org/api/v1/activations?status=waiting&limit=20');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY'],
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);import requests
response = requests.get(
"https://codesms.org/api/v1/activations?status=waiting&limit=20",
headers={"X-API-Key": "YOUR_API_KEY"}
)
print(response.json())const response = await fetch("https://codesms.org/api/v1/activations?status=waiting&limit=20", {
method: "GET",
headers: {
"X-API-Key": "YOUR_API_KEY"
}
});
console.log(await response.json());package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://codesms.org/api/v1/activations?status=waiting&limit=20", nil)
req.Header.Set("X-API-Key", "YOUR_API_KEY")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var response = await client.GetAsync("https://codesms.org/api/v1/activations?status=waiting&limit=20");
Console.WriteLine(await response.Content.ReadAsStringAsync());HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://codesms.org/api/v1/activations?status=waiting&limit=20"))
.header("X-API-Key", "YOUR_API_KEY")
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());require 'net/http'
require 'json'
uri = URI("https://codesms.org/api/v1/activations?status=waiting&limit=20")
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = 'YOUR_API_KEY'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body{
"success": true,
"data": [
{
"id": 1234,
"status": "waiting",
"phone": "+905551234567",
"code": null,
"text": null,
"service": {
"code": "tg",
"name": "Telegram"
},
"country": {
"iso": "tr",
"name": "Turkey",
"dial": "90"
},
"server": 3,
"price": 8.5,
"currency": "TRY",
"created_at": "2026-01-15T10:00:00+03:00",
"expires_at": "2026-01-15T10:20:00+03:00",
"retry_count": 0,
"can_cancel": true,
"can_retry": false,
"can_finish": false,
"cancel_in": 0
}
]
}لغو و بازگشت وجه
اگر کدی نرسیده باشد، فعالسازی را لغو و هزینه را به موجودی شما بازمیگرداند. برخی ارائهدهندگان در چند ثانیه اول اجازه لغو نمیدهند (تا زمانی که cancel_in > 0 باشد CANCEL_TOO_EARLY برگردانده میشود). اگر ارائهدهنده پشتیبانی نکند، can_cancel=false است.
| پارامتر | نوع | توضیحات | |
|---|---|---|---|
| id | integer | الزامی | شناسه فعالسازی (پارامتر مسیر). |
curl -X POST "https://codesms.org/api/v1/activations/1234/cancel" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'$ch = curl_init('https://codesms.org/api/v1/activations/1234/cancel');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY', 'Content-Type: application/json'],
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode([]),
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);import requests
response = requests.post(
"https://codesms.org/api/v1/activations/1234/cancel",
headers={"X-API-Key": "YOUR_API_KEY"},
json={}
)
print(response.json())const response = await fetch("https://codesms.org/api/v1/activations/1234/cancel", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({})
});
console.log(await response.json());package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("POST", "https://codesms.org/api/v1/activations/1234/cancel", bytes.NewBufferString(`{}`))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-Key", "YOUR_API_KEY")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var response = await client.PostAsync("https://codesms.org/api/v1/activations/1234/cancel", new StringContent("{}", System.Text.Encoding.UTF8, "application/json"));
Console.WriteLine(await response.Content.ReadAsStringAsync());HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://codesms.org/api/v1/activations/1234/cancel"))
.header("X-API-Key", "YOUR_API_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString("{}"))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());require 'net/http'
require 'json'
uri = URI("https://codesms.org/api/v1/activations/1234/cancel")
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = 'YOUR_API_KEY'
req['Content-Type'] = 'application/json'
req.body = '{}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body{
"success": true,
"data": {
"status": "canceled",
"can_cancel": false,
"id": 1234,
"phone": "+905551234567",
"code": null,
"text": null,
"service": {
"code": "tg",
"name": "Telegram"
},
"country": {
"iso": "tr",
"name": "Turkey",
"dial": "90"
},
"server": 3,
"price": 8.5,
"currency": "TRY",
"created_at": "2026-01-15T10:00:00+03:00",
"expires_at": "2026-01-15T10:20:00+03:00",
"retry_count": 0,
"can_retry": false,
"can_finish": false,
"cancel_in": 0
}
}درخواست SMS دیگر
پس از دریافت کد، پیامک جدیدی به همان شماره درخواست میکند (فقط وقتی can_retry=true باشد). فعالسازی به وضعیت "waiting" برمیگردد.
| پارامتر | نوع | توضیحات | |
|---|---|---|---|
| id | integer | الزامی | شناسه فعالسازی (پارامتر مسیر). |
curl -X POST "https://codesms.org/api/v1/activations/1234/retry" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'$ch = curl_init('https://codesms.org/api/v1/activations/1234/retry');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY', 'Content-Type: application/json'],
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode([]),
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);import requests
response = requests.post(
"https://codesms.org/api/v1/activations/1234/retry",
headers={"X-API-Key": "YOUR_API_KEY"},
json={}
)
print(response.json())const response = await fetch("https://codesms.org/api/v1/activations/1234/retry", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({})
});
console.log(await response.json());package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("POST", "https://codesms.org/api/v1/activations/1234/retry", bytes.NewBufferString(`{}`))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-Key", "YOUR_API_KEY")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var response = await client.PostAsync("https://codesms.org/api/v1/activations/1234/retry", new StringContent("{}", System.Text.Encoding.UTF8, "application/json"));
Console.WriteLine(await response.Content.ReadAsStringAsync());HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://codesms.org/api/v1/activations/1234/retry"))
.header("X-API-Key", "YOUR_API_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString("{}"))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());require 'net/http'
require 'json'
uri = URI("https://codesms.org/api/v1/activations/1234/retry")
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = 'YOUR_API_KEY'
req['Content-Type'] = 'application/json'
req.body = '{}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body{
"success": true,
"data": {
"retry_count": 1,
"id": 1234,
"status": "waiting",
"phone": "+905551234567",
"code": null,
"text": null,
"service": {
"code": "tg",
"name": "Telegram"
},
"country": {
"iso": "tr",
"name": "Turkey",
"dial": "90"
},
"server": 3,
"price": 8.5,
"currency": "TRY",
"created_at": "2026-01-15T10:00:00+03:00",
"expires_at": "2026-01-15T10:20:00+03:00",
"can_cancel": true,
"can_retry": false,
"can_finish": false,
"cancel_in": 0
}
}پایان
اعلام میکند که کد را با موفقیت استفاده کردهاید و فعالسازی را میبندد. فعالسازیهایی که ظرف ۱۵ دقیقه تکمیل نشوند، بهطور خودکار تکمیل میشوند.
| پارامتر | نوع | توضیحات | |
|---|---|---|---|
| id | integer | الزامی | شناسه فعالسازی (پارامتر مسیر). |
curl -X POST "https://codesms.org/api/v1/activations/1234/finish" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'$ch = curl_init('https://codesms.org/api/v1/activations/1234/finish');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY', 'Content-Type: application/json'],
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode([]),
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);import requests
response = requests.post(
"https://codesms.org/api/v1/activations/1234/finish",
headers={"X-API-Key": "YOUR_API_KEY"},
json={}
)
print(response.json())const response = await fetch("https://codesms.org/api/v1/activations/1234/finish", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({})
});
console.log(await response.json());package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("POST", "https://codesms.org/api/v1/activations/1234/finish", bytes.NewBufferString(`{}`))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-Key", "YOUR_API_KEY")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var response = await client.PostAsync("https://codesms.org/api/v1/activations/1234/finish", new StringContent("{}", System.Text.Encoding.UTF8, "application/json"));
Console.WriteLine(await response.Content.ReadAsStringAsync());HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://codesms.org/api/v1/activations/1234/finish"))
.header("X-API-Key", "YOUR_API_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString("{}"))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());require 'net/http'
require 'json'
uri = URI("https://codesms.org/api/v1/activations/1234/finish")
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = 'YOUR_API_KEY'
req['Content-Type'] = 'application/json'
req.body = '{}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body{
"success": true,
"data": {
"status": "completed",
"code": "482913",
"text": "Your Telegram code: 482913",
"can_cancel": false,
"can_retry": true,
"can_finish": true,
"id": 1234,
"phone": "+905551234567",
"service": {
"code": "tg",
"name": "Telegram"
},
"country": {
"iso": "tr",
"name": "Turkey",
"dial": "90"
},
"server": 3,
"price": 8.5,
"currency": "TRY",
"created_at": "2026-01-15T10:00:00+03:00",
"expires_at": "2026-01-15T10:20:00+03:00",
"retry_count": 0,
"cancel_in": 0
}
}Webhook
اگر در پنل آدرس webhook تنظیم کنید، هنگام رسیدن کد SMS یک درخواست POST امضاشده به آن ارسال میکنیم؛ نیازی به استعلام مداوم نیست. در صورت پاسخ غیر 2xx، پس از ۱ دقیقه، ۵ دقیقه، ۱۵ دقیقه، ۱ ساعت و ۶ ساعت دوباره تلاش میشود.
- X-SMSOnay-Event
activation.code- X-SMSOnay-Timestamp
- ثانیههای یونیکس
- X-SMSOnay-Signature
sha256=HMAC_SHA256(secret, timestamp + "." + body)
{
"event": "activation.code",
"activation": {
"id": 1234,
"status": "received",
"phone": "+905551234567",
"code": "482913",
"service": {
"code": "tg"
},
"...": "..."
},
"timestamp": 1768460000
}# HMAC-SHA256(secret, timestamp + "." + rawBody) -> "sha256=" + hex
# Header'lar: X-SMSOnay-Timestamp, X-SMSOnay-Signature$ts = $_SERVER['HTTP_X_SMSONAY_TIMESTAMP'];
$sig = $_SERVER['HTTP_X_SMSONAY_SIGNATURE'];
$body = file_get_contents('php://input');
$calc = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, 'whsec_YOUR_SECRET');
if (!hash_equals($calc, $sig) || abs(time() - (int)$ts) > 300) { http_response_code(401); exit; }
$event = json_decode($body, true);import hmac, hashlib, time
def verify(ts, signature, body: bytes, secret: str) -> bool:
calc = 'sha256=' + hmac.new(secret.encode(), ts.encode() + b'.' + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(calc, signature) and abs(time.time() - int(ts)) < 300const crypto = require('crypto');
function verify(ts, signature, rawBody, secret) {
const calc = 'sha256=' + crypto.createHmac('sha256', secret).update(ts + '.' + rawBody).digest('hex');
return crypto.timingSafeEqual(Buffer.from(calc), Buffer.from(signature)) && Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}func verify(ts, signature string, body []byte, secret string) bool {
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(ts + "."))
mac.Write(body)
calc := "sha256=" + hex.EncodeToString(mac.Sum(nil))
return hmac.Equal([]byte(calc), []byte(signature))
}static bool Verify(string ts, string signature, string body, string secret)
{
using var h = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
var calc = "sha256=" + Convert.ToHexString(h.ComputeHash(Encoding.UTF8.GetBytes(ts + "." + body))).ToLower();
return CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(calc), Encoding.UTF8.GetBytes(signature));
}static boolean verify(String ts, String signature, String body, String secret) throws Exception {
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
String calc = "sha256=" + HexFormat.of().formatHex(mac.doFinal((ts + "." + body).getBytes(StandardCharsets.UTF_8)));
return MessageDigest.isEqual(calc.getBytes(), signature.getBytes());
}require 'openssl'
def verify(ts, signature, body, secret)
calc = 'sha256=' + OpenSSL::HMAC.hexdigest('SHA256', secret, "#{ts}.#{body}")
Rack::Utils.secure_compare(calc, signature)
endکلید امضای خود را میتوانید از صفحه API در پنل دریافت کنید. مهر زمانی (±۵ دقیقه) و امضا را بررسی کنید؛ ارسالهای تکراری برای یک فعالسازی را بر اساس id حذف کنید.
API سازگار با SMS-Activate
اگر نرمافزار ثبتنام/اتوماسیون فعلی شما از پروتکل SMS-Activate (handler_api) پشتیبانی میکند، فقط با تغییر آدرس سرور و کلید API میتوانید به ما متصل شوید.
- service: کد سرویس (tg، wa، ig، go، fb …) — کد دریافتی از GET /api/v1/services.
- country: شناسه کشور در SMS-Activate (مثلاً 62 = ترکیه، 0 = روسیه، 187 = آمریکا) — شناسه دریافتی از GET /api/v1/countries.
- قیمتها به لیر ترکیه است؛ maxPrice نیز به TRY در نظر گرفته میشود.
- operator: فقط مقدار عددی بهعنوان شماره «Server N» تفسیر میشود (GET /api/v1/prices?servers=1)؛ اگر حذف شود، همه Serverها به ترتیب قیمت امتحان میشوند.
| action | پارامترها | نمونه پاسخ |
|---|---|---|
| getBalance | — | ACCESS_BALANCE:125.50 |
| getNumber | service, country (ID), [maxPrice], [operator = Server no] | ACCESS_NUMBER:1234:905551234567 |
| getNumberV2 | service, country (ID), [maxPrice], [operator = Server no] | {"activationId":"1234","phoneNumber":"905551234567","activationCost":8.5,"countryCode":"62","canGetAnotherSms":true,...} |
| getStatus | id | STATUS_WAIT_CODE | STATUS_OK:482913 | STATUS_WAIT_RETRY:482913 | STATUS_CANCEL |
| getStatusV2 | id | {"verificationType":0,"sms":{"dateTime":"...","code":"482913","text":"..."},"call":null} |
| setStatus | id, status (3=tekrar SMS, 6=tamamla, 8=iptal) | ACCESS_RETRY_GET | ACCESS_ACTIVATION | ACCESS_CANCEL | EARLY_CANCEL_DENIED |
| getPrices | [service], [country] | {"62":{"tg":{"cost":8.5,"count":420}}} |
| getNumbersStatus | country | {"tg_0":420,"wa_0":310} |
| getCountries | — | {"62":{"id":62,"eng":"Turkey",...}} |
| getServicesList | — | {"status":"success","services":[{"code":"tg","name":"Telegram"}]} |
| getActiveActivations | — | {"status":"success","activeActivations":[...]} |
curl "https://codesms.org/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getNumber&service=tg&country=62" \
-H "X-API-Key: unused"$ch = curl_init('https://codesms.org/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getNumber&service=tg&country=62');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: unused'],
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);import requests
response = requests.get(
"https://codesms.org/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getNumber&service=tg&country=62",
headers={"X-API-Key": "unused"}
)
print(response.json())const response = await fetch("https://codesms.org/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getNumber&service=tg&country=62", {
method: "GET",
headers: {
"X-API-Key": "unused"
}
});
console.log(await response.json());پاسخهای خطا به صورت متن ساده هستند: BAD_KEY، BAD_ACTION، BAD_SERVICE، NO_NUMBERS، NO_BALANCE، NO_ACTIVATION، EARLY_CANCEL_DENIED، WRONG_MAX_PRICE:price، ACCOUNT_INACTIVE…
درخواستهای امضاشده (اختیاری)
اگر گزینه پنل → API → «درخواست امضاشده الزامی است» فعال باشد، هدرهای زیر باید به هر درخواست REST اضافه شوند؛ حتی اگر کلید شما به سرقت برود، بدون رمز امضا نمیتوان درخواستی ارسال کرد و همان درخواست را نمیتوان دوباره تکرار کرد. نقطه پایانی سازگار با SMS-Activate از امضا پشتیبانی نمیکند، بنابراین تا زمانی که این گزینه فعال است قابل استفاده نیست.
X-Timestamp: زمان Unix (ثانیه)؛ حداکثر ۵ دقیقه میتواند با زمان سرور اختلاف داشته باشد.X-Nonce: یک مقدار تصادفی جدید برای هر درخواست، ۱۶ تا ۶۴ کاراکتر (A-Z a-z 0-9 _ -).X-Signature:hex(HMAC-SHA256(imza_sırrı, X-Timestamp + "\n" + X-Nonce + "\n" + METHOD + "\n" + yol?sorgu + "\n" + hex(SHA256(gövde))))
$ts = (string)time(); $nonce = bin2hex(random_bytes(16)); $body = json_encode(['service' => 'tg', 'country' => 'tr']);
$sig = hash_hmac('sha256', "$ts\n$nonce\nPOST\n/api/v1/activations\n" . hash('sha256', $body), $signSecret);
// Başlıklar: X-API-Key, X-Timestamp: $ts, X-Nonce: $nonce, X-Signature: $sig, Content-Type: application/jsonکدهای خطا
| code | HTTP | توضیحات |
|---|---|---|
| BAD_KEY | 401 | کلید API وارد نشده یا نامعتبر است. |
| API_DISABLED | 403 | دسترسی API برای حساب شما غیرفعال است. |
| EMAIL_NOT_VERIFIED | 403 | آدرس ایمیل شما تأیید نشده است. |
| IP_NOT_ALLOWED | 403 | آدرس IP درخواست در فهرست مجاز نیست. |
| ACCOUNT_BANNED | 403 | حساب کاربری تعلیق شده است. |
| RATE_LIMIT | 429 | از سقف تعداد درخواست در دقیقه فراتر رفتهاید. |
| BAD_SERVICE | 400 | کد سرویس نامعتبر است یا وارد نشده است. |
| BAD_COUNTRY | 400 | کد کشور نامعتبر است یا وارد نشده است. |
| NO_BALANCE | 402 | موجودی کافی نیست. (حداقل موجودی الزامی نیست؛ این خطا زمانی برمیگردد که موجودی شما کمتر از قیمت باشد.) |
| NO_NUMBERS | 409 | در حال حاضر شمارهای برای این سرویس/کشور موجود نیست (هزینهای کسر نشد / مبلغ بازگردانده شد). |
| BAD_MAX_PRICE | 400 | max_price باید یک عدد مثبت باشد. |
| BAD_SERVER | 400 | server must be a positive integer (the Server number). |
| PRICE_CHANGED | 409 | با قیمتی که پذیرفتید شمارهای باقی نمانده است؛ هزینهای از شما کسر نشد. error.price در پاسخ، قیمت فعلی است؛ اگر آن را میپذیرید، همان درخواست را با max_price تکرار کنید. |
| TOO_MANY_ACTIVE | 429 | از تعداد مجاز فعالسازیهای همزمان فراتر رفتهاید. |
| NOT_FOUND | 404 | فعالسازی یافت نشد. |
| BAD_STATUS | 409 | این عملیات در وضعیت فعلی فعالسازی امکانپذیر نیست. |
| CANCEL_TOO_EARLY | 409 | ارائهدهنده در این مرحله اجازه لغو نمیدهد؛ پس از cancel_in ثانیه دوباره تلاش کنید. |
| ALREADY_RECEIVED | 409 | به دلیل دریافت کد، امکان لغو وجود ندارد. |
| UNSUPPORTED | 409 | ارائهدهنده از این عملیات پشتیبانی نمیکند (مثلاً SMS دیگر). |
| PROVIDER_ERROR | 502 | ارائهدهنده با خطای موقت مواجه شد؛ دوباره تلاش کنید. |
| PLAN_REQUIRED | 403 | API erişimi için etkin bir API paketi gerekiyor (Panel → API). |
| BAD_SIGNATURE | 401 | İmzalı istek zorunlu ve imza eksik/geçersiz ya da zaman damgası 5 dakikadan eski. |
| BAD_IDEMPOTENCY_KEY | 400 | هدر Idempotency-Key باید ۸ تا ۶۴ کاراکتر باشد (حروف، ارقام، _ - : .). |
| IDEMPOTENCY_IN_PROGRESS | 409 | درخواست قبلی با همین Idempotency-Key هنوز در حال پردازش است؛ چند ثانیه دیگر دوباره تلاش کنید. |
| REPLAYED_REQUEST | 401 | Aynı X-Nonce ikinci kez kullanıldı (tekrar oynatma koruması). |
| SERVER_ERROR | 500 | خطای غیرمنتظره سرور. |
محدودیتها و توصیهها
- محدودیت درخواست: 120 درخواست در دقیقه (برای هر حساب).
- وضعیت را هر ۳ تا ۵ ثانیه بررسی کنید؛ استفاده از وبهوکها کارآمدتر است.
- فعالسازیهایی که پیامکی دریافت نکنند، با پایان زمان بهطور خودکار لغو و هزینهشان بازگردانده میشود؛ میتوانید زودتر هم لغو کنید.
- تعداد فعالسازیهای باز همزمان محدود است (TOO_MANY_ACTIVE).
- در صورت اتمام زمان شبکه، درخواست خرید را با همان هدر Idempotency-Key دوباره ارسال کنید؛ شماره دومی خریداری نمیشود. اگر از این هدر استفاده نمیکنید، ابتدا فعالسازیهای اخیر خود را با GET /api/v1/activations بررسی کنید.
- قیمت ممکن است با تغییر موجودی تغییر کند: اگر با قیمت فهرستشده شمارهای باقی نمانده باشد، هزینهای کسر نمیشود و قیمت فعلی با PRICE_CHANGED اعلام میشود (WRONG_MAX_PRICE:price در endpoint سازگار با SMS-Activate). اگر آن را میپذیرید، درخواست را با max_price (maxPrice) تکرار کنید.
- فیلد success_rate در فهرست قیمتها، درصد فروشهای ۳۰ روز گذشته برای آن سرویس و کشور است که کد SMS دریافت شده است؛ اگر نمونه بسیار کوچک باشد، مقدار آن null است.