CodeSMS

وثائق واجهة برمجة التطبيقات (API)

واجهة برمجة تطبيقات REST v1 ونقاط نهاية متوافقة مع SMS-Activate

اشترك مجانًا

مقدمة

تتيح لك واجهة برمجة التطبيقات (API) شراء أرقام افتراضية باستخدام رصيد حسابك، وقراءة رموز الرسائل القصيرة الواردة، وإلغاء الشراء لاسترداد المبلغ. جميع الطلبات تستخدم بروتوكول HTTPS؛ وتكون الردود بتنسيق JSON.

لا يوجد حد أدنى للرصيد المطلوب. إذا كان رصيدك يغطي سعر الرقم، تتم عملية الشراء؛ وإلا فإن واجهة برمجة التطبيقات (API) تُرجع NO_BALANCE.
اختيار Server (اختياري). لكل خدمة ودولة، تأتي الأرقام من Servers ذات أرقام ثابتة مثل «Server 3» أو «Server 7»؛ ولكل Server سعره ومخزونه ومعدل نجاحه الخاص. اعرضها عبر GET /api/v1/prices?service=..&country=..&servers=1 واختر أحدها بمعامل server عند الشراء. إذا لم تمرر server، يُجرَّب الأرخص أولاً ويُنتقل إلى التالي عند الحاجة.
عنوان URL الأساسي
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).
receivedوصلت رسالة SMS؛ في حقل الرمز.استخدم الرمز، وانتهي؛ اطلب رسالة SMS أخرى إذا كانت قيمة can_retry=true.
completedتم الانتهاء من المشروع (تم استخدام الكود).—
canceledتم إلغاء الطلب واسترداد المبلغ.—
expiredانتهت المدة، ولم تصل رسالة نصية قصيرة؛ تم رد المبلغ.—
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

السعر الحالي والمخزون لكل خدمة/بلد. تعرض الاستعلامات غير المفلترة القائمة بأكملها (حتى 20,000 صف).

المعلمةالنوعالوصف
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 إذا لم يكن هناك رصيد متوفر. إذا لم تصل رسالة SMS أو قمت بالإلغاء، يتم رد الرسوم تلقائيًا. موصى به: أرسل رأس "Idempotency-Key" فريدًا مع كل عملية شراء؛ إذا أعدت المحاولة بنفس المفتاح بعد حدوث خطأ في الشبكة، فلن يتم شراء رقم ثانٍ وسيتم إرجاع التنشيط الأول (صالح لمدة 24 ساعة).

المعلمةالنوعالوصف
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

يعرض حالة التنشيط ورمز الرسالة القصيرة في حال وصوله. يتم إجراء استقصاء كل 3–5 ثوانٍ حتى وصول الرمز (لا حاجة لذلك إذا كنت تستخدم webhooks).

المعلمةالنوعالوصف
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اختياريفي الانتظار، تم الاستلام، اكتمل، تم الإلغاء، انتهت الصلاحية، فشل
limitintegerاختياري1–100 (القيمة الافتراضية 30).
طلب
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_TOO_EARLY عندما تكون قيمة cancel_in أكبر من 0). إذا كانت الشركة المزودة بالخدمة لا تدعم ذلك، فإن 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

يطلب رسالة SMS جديدة إلى الرقم نفسه بعد وصول الرمز (فقط عندما تكون قيمة can_retry=true). تعود حالة التنشيط إلى "في الانتظار".

المعلمةالنوعالوصف
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

يُبلغك بأنك استخدمت الرمز بنجاح ويُغلق عملية التنشيط. يتم إتمام عمليات التنشيط التي لم تكتمل في غضون 15 دقيقة تلقائيًا.

المعلمةالنوعالوصف
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

إذا قمت بتعيين عنوان URL لـ webhook في لوحة التحكم، فإننا نرسل طلب POST موقّعًا إليه عند وصول رمز الرسالة القصيرة؛ دون الحاجة إلى الاستعلام باستمرار. في حالة الاستجابات غير 2xx، تتم إعادة المحاولة بعد 1 دقيقة، و5 دقائق، و15 دقيقة، وساعة واحدة، و6 ساعات.

العناوين
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) في لوحة التحكم. تحقق من الطابع الزمني (±5 دقائق) والتوقيع؛ وقم بإزالة التكرارات في عمليات التسليم المتكررة لنفس عملية التنشيط حسب المعرف.

واجهة برمجة تطبيقات (API) متوافقة مع SMS-Activate

إذا كان برنامج التسجيل/الأتمتة الذي تستخدمه حاليًا يدعم بروتوكول SMS-Activate (handler_api)، فيمكنك الاتصال بنا بمجرد تغيير عنوان الخادم ومفتاح واجهة برمجة التطبيقات (API).

GEThttps://codesms.org/stubs/handler_api.php?api_key=YOUR_API_KEY&action=...
  • الخدمة: رمز الخدمة (tg، wa، ig، go، fb …) — الرمز المستمد من GET /api/v1/services.
  • البلد: معرّف البلد في SMS-Activate (على سبيل المثال: 62 = تركيا، 0 = روسيا، 187 = الولايات المتحدة الأمريكية) — المعرّف المستمد من GET /api/v1/countries.
  • الأسعار بالليرة التركية؛ ويتم تفسير maxPrice بالليرة التركية أيضًا.
  • operator: تُفسَّر القيمة الرقمية فقط على أنها رقم «Server N» (GET /api/v1/prices?servers=1)؛ وإذا أُغفلت، تُجرَّب جميع Servers حسب ترتيب السعر.
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…

الطلبات الموقعة (اختياري)

إذا تم تشغيل الخيار "Panel → API → "Signed request required" (لوحة التحكم → واجهة برمجة التطبيقات → "يلزم طلب موقّع")، فيجب إضافة الرؤوس التالية إلى كل طلب REST؛ حتى في حالة سرقة مفتاحك، لا يمكن إرسال الطلبات بدون سر التوقيع، ولا يمكن إعادة إرسال الطلب نفسه. لا تدعم نقطة النهاية المتوافقة مع SMS-Activate التوقيع، لذا لا يمكن استخدامها أثناء تشغيل هذا الخيار.

  • X-Timestamp: الوقت وفقًا لنظام يونكس (بالثواني)؛ قد يختلف عن وقت الخادم بحد أقصى 5 دقائق.
  • X-Nonce: قيمة عشوائية جديدة لكل طلب، تتراوح بين 16 و64 حرفًا (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_PRICE400يجب أن تكون قيمة max_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لا يدعم المزود هذا الإجراء (مثل إرسال رسالة نصية قصيرة أخرى).
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 من 8 إلى 64 حرفًا (أحرف أبجدية، أرقام، _ - : .).
IDEMPOTENCY_IN_PROGRESS409لا يزال الطلب السابق الذي يحمل نفس مفتاح التكرار (Idempotency-Key) قيد المعالجة؛ يرجى إعادة المحاولة بعد بضع ثوانٍ.
REPLAYED_REQUEST401Aynı X-Nonce ikinci kez kullanıldı (tekrar oynatma koruması).
SERVER_ERROR500حدث خطأ غير متوقع في الخادم.

القيود والتوصيات

  • حد معدل الاستخدام 120 طلبًا في الدقيقة (لكل حساب).
  • التحقق من حالة الاستطلاع كل 3–5 ثوانٍ؛ ويُعد استخدام webhooks أكثر كفاءة.
  • يتم إلغاء عمليات التنشيط التي لا تتلقى أي رسالة نصية قصيرة واسترداد قيمتها تلقائيًا عند انتهاء المدة المحددة؛ كما يمكنك الإلغاء مبكرًا.
  • عدد عمليات التنشيط المفتوحة في وقت واحد محدود (TOO_MANY_ACTIVE).
  • في حالة انقضاء مهلة الشبكة، أعد إرسال طلب الشراء باستخدام نفس رأس "Idempotency-Key"؛ ولن يتم شراء رقم ثانٍ. إذا لم تستخدم هذا الرأس، فتحقق أولاً من عمليات التنشيط الأخيرة باستخدام GET /api/v1/activations.
  • قد يتغيّر السعر حسب المخزون: إذا لم تتبقَّ أرقام بالسعر المعروض فلن يتم خصم أي مبلغ منك، وسيُبلَّغ عن السعر الحالي عبر PRICE_CHANGED (أو WRONG_MAX_PRICE:price في نقطة النهاية المتوافقة مع SMS-Activate). وإذا قبلته، كرّر الطلب مع max_price (maxPrice).
  • يمثّل الحقل success_rate في قائمة الأسعار نسبة المبيعات خلال آخر 30 يومًا لتلك الخدمة والدولة التي وصل فيها رمز SMS؛ وتكون قيمته null عندما تكون العيّنة صغيرة جدًا.