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