CodeSMS
TürkçeEnglishالعربيةРусскийفارسیBahasa IndonesiaPortuguêsEspañolDeutschFrançaisItaliano中文
ارز
موجودی و پرداخت‌ها به لیر ترکیه است.
ورود ثبت‌نام

مستندات API

REST API v1 و endpointهای سازگار با SMS-Activate

ثبت‌نام رایگان

معرفی

API به شما امکان می‌دهد با موجودی حساب خود شماره مجازی بخرید، کدهای SMS دریافتی را بخوانید و برای بازپرداخت لغو کنید. همه درخواست‌ها از HTTPS استفاده می‌کنند و پاسخ‌ها JSON هستند.

حداقل موجودی لازم نیست. اگر موجودی شما قیمت شماره را پوشش دهد خرید انجام می‌شود؛ در غیر این صورت API پاسخ NO_BALANCE برمی‌گرداند.
انتخاب Server (اختیاری). برای هر سرویس و کشور، شماره‌ها از Serverهایی با شماره ثابت مانند «Server 3» یا «Server 7» تأمین می‌شوند؛ هر Server قیمت، موجودی و نرخ موفقیت مخصوص به خود را دارد. با GET /api/v1/prices?service=..&country=..&servers=1 فهرست را ببینید و هنگام خرید با پارامتر server یکی را انتخاب کنید. اگر server ارسال نکنید، ابتدا ارزان‌ترین امتحان می‌شود و در صورت نیاز Server بعدی استفاده می‌شود.
آدرس پایه
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 iade
import 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 iade
const 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).
receivedSMS رسید؛ در فیلد code.از کد استفاده کنید و پایان دهید؛ اگر can_retry=true بود، SMS دیگری درخواست کنید.
completedتکمیل شد (کد استفاده شد).—
canceledلغو شد، بازپرداخت شد.—
expiredزمان به پایان رسید، SMS نیامد؛ بازپرداخت شد.—
failedدریافت شماره ممکن نشد؛ بازپرداخت شد.—

وجود دکمه‌های لغو، ارسال مجدد پیامک و پایان به شماره و سرویس بستگی دارد: فیلدهای can_cancel، can_retry و can_finish را در پاسخ بررسی کنید. اگر cancel_in > 0 باشد، باید به اندازه آن تعداد ثانیه صبر کنید تا لغو کنید.

دریافت موجودی

GET/api/v1/balance

موجودی فعلی حساب شما را برمی‌گرداند.

درخواست
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
پاسخ 200
{
    "success": true,
    "data": {
        "balance": 125.5,
        "currency": "TRY"
    }
}

فهرست سرویس‌ها

GET/api/v1/services

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
پاسخ 200
{
    "success": true,
    "data": [
        {
            "code": "tg",
            "slug": "telegram",
            "name": "Telegram",
            "min_price": 2.1,
            "stock": 18540
        }
    ]
}

فهرست کشورها

GET/api/v1/countries

کشورهایی که شماره موجود دارند. "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
پاسخ 200
{
    "success": true,
    "data": [
        {
            "iso": "tr",
            "id": 62,
            "name": "Turkey",
            "name_tr": "Türkiye",
            "dial": "90"
        }
    ]
}

قیمت و موجودی

GET/api/v1/prices

قیمت و موجودی فعلی برای هر سرویس/کشور. فراخوانی بدون فیلتر کل فهرست را برمی‌گرداند (تا ۲۰٬۰۰۰ ردیف).

پارامترنوعتوضیحات
servicestringاختیاریکد یا شناسه سرویس (مثلاً tg).
countrystringاختیاریکد ISO کشور (tr) یا شناسه عددی (62).
serversintegerاختیاری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
پاسخ 200
{
    "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
                }
            ]
        }
    ]
}

خرید شماره

POST/api/v1/activations

یک فعال‌سازی (شماره) جدید باز می‌کند و مبلغ از موجودی شما کسر می‌شود. در صورت کافی نبودن موجودی NO_BALANCE و در صورت نبود موجودی شماره NO_NUMBERS برمی‌گرداند. اگر پیامکی نرسد یا لغو کنید، هزینه به‌طور خودکار بازگردانده می‌شود. توصیه: با هر خرید یک هدر Idempotency-Key یکتا ارسال کنید؛ اگر پس از خطای شبکه با همان کلید دوباره تلاش کنید، شماره دومی خریداری نمی‌شود و همان فعال‌سازی اول برگردانده می‌شود (معتبر به مدت ۲۴ ساعت).

پارامترنوعتوضیحات
servicestringالزامیکد یا شناسه سرویس (مثلاً tg).
countrystringالزامیکد ISO کشور (tr) یا شناسه عددی (62).
max_pricenumberاختیاریبالاترین قیمتی (TRY) که می‌پذیرید. در صورت عدم ارسال، پایین‌ترین قیمت فهرست‌شده اعمال می‌شود؛ اگر قیمت از آن بیشتر شود، PRICE_CHANGED برگردانده می‌شود.
serverintegerاختیاری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
پاسخ 201
{
    "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
    }
}

وضعیت فعال‌سازی / کد پیامک

GET/api/v1/activations/1234

وضعیت فعال‌سازی و در صورت دریافت، کد پیامک را برمی‌گرداند. تا رسیدن کد هر ۳ تا ۵ ثانیه بررسی کنید (در صورت استفاده از وبهوک لازم نیست).

پارامترنوعتوضیحات
idintegerالزامیشناسه فعال‌سازی (پارامتر مسیر).
درخواست
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
پاسخ 200
{
    "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
    }
}

فهرست فعال‌سازی‌ها

GET/api/v1/activations

آخرین فعال‌سازی‌های شما (جدیدترین در ابتدا).

پارامترنوعتوضیحات
statusstringاختیاریwaiting، received، completed، canceled، expired، failed
limitintegerاختیاری۱ تا ۱۰۰ (پیش‌فرض ۳۰).
درخواست
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
پاسخ 200
{
    "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
        }
    ]
}

لغو و بازگشت وجه

POST/api/v1/activations/1234/cancel

اگر کدی نرسیده باشد، فعال‌سازی را لغو و هزینه را به موجودی شما بازمی‌گرداند. برخی ارائه‌دهندگان در چند ثانیه اول اجازه لغو نمی‌دهند (تا زمانی که cancel_in > 0 باشد CANCEL_TOO_EARLY برگردانده می‌شود). اگر ارائه‌دهنده پشتیبانی نکند، can_cancel=false است.

پارامترنوعتوضیحات
idintegerالزامیشناسه فعال‌سازی (پارامتر مسیر).
درخواست
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
پاسخ 200
{
    "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 دیگر

POST/api/v1/activations/1234/retry

پس از دریافت کد، پیامک جدیدی به همان شماره درخواست می‌کند (فقط وقتی can_retry=true باشد). فعال‌سازی به وضعیت "waiting" برمی‌گردد.

پارامترنوعتوضیحات
idintegerالزامیشناسه فعال‌سازی (پارامتر مسیر).
درخواست
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
پاسخ 200
{
    "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
    }
}

پایان

POST/api/v1/activations/1234/finish

اعلام می‌کند که کد را با موفقیت استفاده کرده‌اید و فعال‌سازی را می‌بندد. فعال‌سازی‌هایی که ظرف ۱۵ دقیقه تکمیل نشوند، به‌طور خودکار تکمیل می‌شوند.

پارامترنوعتوضیحات
idintegerالزامیشناسه فعال‌سازی (پارامتر مسیر).
درخواست
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
پاسخ 200
{
    "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)) < 300
const 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 می‌توانید به ما متصل شوید.

GEThttps://codesms.org/stubs/handler_api.php?api_key=YOUR_API_KEY&action=...
  • 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
getNumberservice, country (ID), [maxPrice], [operator = Server no]ACCESS_NUMBER:1234:905551234567
getNumberV2service, country (ID), [maxPrice], [operator = Server no]{"activationId":"1234","phoneNumber":"905551234567","activationCost":8.5,"countryCode":"62","canGetAnotherSms":true,...}
getStatusidSTATUS_WAIT_CODE | STATUS_OK:482913 | STATUS_WAIT_RETRY:482913 | STATUS_CANCEL
getStatusV2id{"verificationType":0,"sms":{"dateTime":"...","code":"482913","text":"..."},"call":null}
setStatusid, 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}}}
getNumbersStatuscountry{"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

کدهای خطا

codeHTTPتوضیحات
BAD_KEY401کلید API وارد نشده یا نامعتبر است.
API_DISABLED403دسترسی API برای حساب شما غیرفعال است.
EMAIL_NOT_VERIFIED403آدرس ایمیل شما تأیید نشده است.
IP_NOT_ALLOWED403آدرس IP درخواست در فهرست مجاز نیست.
ACCOUNT_BANNED403حساب کاربری تعلیق شده است.
RATE_LIMIT429از سقف تعداد درخواست در دقیقه فراتر رفته‌اید.
BAD_SERVICE400کد سرویس نامعتبر است یا وارد نشده است.
BAD_COUNTRY400کد کشور نامعتبر است یا وارد نشده است.
NO_BALANCE402موجودی کافی نیست. (حداقل موجودی الزامی نیست؛ این خطا زمانی برمی‌گردد که موجودی شما کمتر از قیمت باشد.)
NO_NUMBERS409در حال حاضر شماره‌ای برای این سرویس/کشور موجود نیست (هزینه‌ای کسر نشد / مبلغ بازگردانده شد).
BAD_MAX_PRICE400max_price باید یک عدد مثبت باشد.
BAD_SERVER400server must be a positive integer (the Server number).
PRICE_CHANGED409با قیمتی که پذیرفتید شماره‌ای باقی نمانده است؛ هزینه‌ای از شما کسر نشد. error.price در پاسخ، قیمت فعلی است؛ اگر آن را می‌پذیرید، همان درخواست را با max_price تکرار کنید.
TOO_MANY_ACTIVE429از تعداد مجاز فعال‌سازی‌های هم‌زمان فراتر رفته‌اید.
NOT_FOUND404فعال‌سازی یافت نشد.
BAD_STATUS409این عملیات در وضعیت فعلی فعال‌سازی امکان‌پذیر نیست.
CANCEL_TOO_EARLY409ارائه‌دهنده در این مرحله اجازه لغو نمی‌دهد؛ پس از cancel_in ثانیه دوباره تلاش کنید.
ALREADY_RECEIVED409به دلیل دریافت کد، امکان لغو وجود ندارد.
UNSUPPORTED409ارائه‌دهنده از این عملیات پشتیبانی نمی‌کند (مثلاً SMS دیگر).
PROVIDER_ERROR502ارائه‌دهنده با خطای موقت مواجه شد؛ دوباره تلاش کنید.
PLAN_REQUIRED403API erişimi için etkin bir API paketi gerekiyor (Panel → API).
BAD_SIGNATURE401İmzalı istek zorunlu ve imza eksik/geçersiz ya da zaman damgası 5 dakikadan eski.
BAD_IDEMPOTENCY_KEY400هدر Idempotency-Key باید ۸ تا ۶۴ کاراکتر باشد (حروف، ارقام، _ - : .).
IDEMPOTENCY_IN_PROGRESS409درخواست قبلی با همین Idempotency-Key هنوز در حال پردازش است؛ چند ثانیه دیگر دوباره تلاش کنید.
REPLAYED_REQUEST401Aynı X-Nonce ikinci kez kullanıldı (tekrar oynatma koruması).
SERVER_ERROR500خطای غیرمنتظره سرور.

محدودیت‌ها و توصیه‌ها

  • محدودیت درخواست: 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 است.