توثيق API

تنزيل توثيق API (Markdown)

يوفّر kartesim للشركاء أرقام هواتف حقيقية وعناوين IP للهاتف المحمول عبر خدمتين: استئجار الأرقام والبروكسي طويل الأمد، وجلسات OTP بالدفع حسب الاستخدام. والخدمتان متاحتان عبر بروتوكول HANDLER_API وواجهة REST API الأصلية.

جلسات OTPحسب الاستخدام

اطلب رقمًا مؤقتًا، وانتظر رسالة SMS، واستلم رمز OTP — في دورة واحدة من استدعاءات API. تُحتسب الرسوم لكل جلسة، وتُسترد إذا ألغيت قبل وصول الرمز.

استئجار الأرقامشرائح SIM

استأجر رقم هاتف مخصصًا لك لمدة يوم أو أسبوع أو شهر. تُحوَّل جميع رسائل SMS الواردة إلى هذا الرقم إلى حسابك فورًا.

استئجار البروكسيعناوين IP للهاتف المحمول

استأجر بروكسي HTTP/SOCKS5 للهاتف المحمول بعنوان IP حقيقي من المشغّل. يعمل كل بروكسي على جهاز مخصص (Android أو مودم 4G) بشريحة SIM فعّالة.

يتولى مدير حسابك تجهيز الإيجارات. تواصل معنا لإعداد إيجارك — وبمجرد تفعيله، يظهر رقم هاتفك وبيانات اعتماد البروكسي في بوابة الشركاء ويمكن الاستعلام عنها عبر API. أما جلسات OTP فهي ذاتية الخدمة عبر API — دون أي إعداد.

المصادقة

تتطلب جميع طلبات API مفتاح API الخاص بك كشريك. وتعتمد طريقة إرساله على البروتوكول الذي تستخدمه.

Handler API — معامل في الاستعلام

GET /api/stubs/handler_api.php
  ?api_key=YOUR_KEY
  &action=getBalance

REST API الأصلية — ترويسة HTTP

curl https://www.kartesim.com/api/v1/otp/request \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "telegram"}'

احتفظ بمفتاح API سرًّا. يظهر مفتاحك في بوابة الشركاء ضمن API. استخدم زر إعادة إنشاء المفتاح هناك لتغييره فورًا.

مرجع Handler API

عنوان URL الأساسي: /api/stubs/handler_api.php — تستخدم جميع الطلبات GET، وجميع الاستجابات نص عادي.

GET/api/stubs/handler_api.php?action=getBalance

يُرجع رصيدك المدفوع مسبقًا الحالي بالدولار الأمريكي (USD).

المعاملات

الاسم	النوع	إلزامي	الوصف
api_key	string	إلزامي	مفتاح API الخاص بك
action	string	إلزامي	يجب أن تكون القيمة "getBalance"

الاستجابات

45.00رصيدك بالدولار الأمريكي (USD)

999999قيمة ثابتة تُرجع للحسابات ذات الرصيد غير المحدود — ليست رصيدًا حقيقيًا ولا تتغير مع الاستخدام

BAD_KEYمفتاح API غير صالح أو مُلغى

مثال على الطلب

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getBalance'

مثال على الاستجابة

45.00

GET/api/stubs/handler_api.php?action=getCountries

يعرض الدول المدعومة مع رموزها الرقمية.

المعاملات

الاسم	النوع	إلزامي	الوصف
api_key	string	إلزامي	مفتاح API الخاص بك
action	string	إلزامي	يجب أن تكون القيمة "getCountries"

الاستجابات

JSON array[{ "id": 7, "name": "Russia" }, ...]

مثال على الطلب

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getCountries'

مثال على الاستجابة

[
  { "id": 7,   "name": "Russia" },
  { "id": 212, "name": "Morocco" }
]

GET/api/stubs/handler_api.php?action=getPrices

احصل على الأسعار الحالية والمخزون النشط المتاح لكل دولة وخدمة.

المعاملات

الاسم	النوع	إلزامي	الوصف
api_key	string	إلزامي	مفتاح API الخاص بك
action	string	إلزامي	يجب أن تكون القيمة "getPrices"
country	number	اختياري	التصفية حسب المعرّف الرقمي للدولة
hide_empty	integer	اختياري	اضبطه على 1 لاستبعاد الدول التي ليس لديها مخزون من الاستجابة

الاستجابات

JSON object{ "countryId": { "serviceId": { "cost": 0.1, "count": 10 } } }

مثال على الطلب

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getPrices&hide_empty=1'

مثال على الاستجابة

{
  "212": {
    "wa": { "cost": 0.15, "count": 12 },
    "tg": { "cost": 0.15, "count": 12 }
  }
}

GET/api/stubs/handler_api.php?action=getNumber

اطلب رقم هاتف مؤقتًا للتحقق عبر OTP. يُرجع معرّف جلسة والرقم المخصص. تنتهي الجلسة بعد 10 دقائق إذا لم تصل أي رسالة SMS.

المعاملات

الاسم	النوع	إلزامي	الوصف
api_key	string	إلزامي	مفتاح API الخاص بك
action	string	إلزامي	يجب أن تكون القيمة "getNumber"
service	string	اختياري	اسم الخدمة (مثل "telegram" و"whatsapp") — للعلم فقط
country	integer	اختياري	رمز الاتصال الدولي للدولة (مثل 212 للمغرب). احذفه أو استخدم 0 لأي دولة.

الاستجابات

ACCESS_NUMBER:id:numberأُنشئت الجلسة — يُستخدم id مع getStatus/setStatus، وnumber هو رقم الهاتف المخصص

NO_NUMBERSلا توجد منافذ متصلة متاحة تطابق طلبك

NO_BALANCEالرصيد غير كافٍ لتغطية رسوم OTP

مثال على الطلب

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getNumber&service=telegram&country=212'

مثال على الاستجابة

ACCESS_NUMBER:cma4x9k3b0000abc123:212661234567

GET/api/stubs/handler_api.php?action=getStatus

استعلم دوريًا عن رمز OTP في جلسة نشطة. كرّر الاستعلام كل 5–10 ثوانٍ حتى تتلقى STATUS_OK أو STATUS_CANCEL.

المعاملات

الاسم	النوع	إلزامي	الوصف
api_key	string	إلزامي	مفتاح API الخاص بك
action	string	إلزامي	يجب أن تكون القيمة "getStatus"
id	string	إلزامي	معرّف الجلسة من استجابة ACCESS_NUMBER

الاستجابات

STATUS_WAIT_CODEالجلسة نشطة — لم تصل رسالة SMS بعد. واصل الاستعلام.

STATUS_OK:84729وصل رمز OTP — يأتي الرمز بعد النقطتين

STATUS_CANCELانتهت صلاحية الجلسة أو أُلغيت

مثال على الطلب

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getStatus&id=cma4x9k3b0000abc123'

مثال على الاستجابة

STATUS_OK:84729

GET/api/stubs/handler_api.php?action=setStatus

أكّد استلام OTP (status=1) أو ألغِ الجلسة لاسترداد كامل المبلغ (status=8). لا يمكن إلغاء إلا الجلسات في حالة PENDING.

المعاملات

الاسم	النوع	إلزامي	الوصف
api_key	string	إلزامي	مفتاح API الخاص بك
action	string	إلزامي	يجب أن تكون القيمة "setStatus"
id	string	إلزامي	معرّف الجلسة المراد تنفيذ الإجراء عليها
status	integer	إلزامي	1 = تأكيد الاستلام، 8 = الإلغاء والاسترداد

الاستجابات

ACCESS_READYتم التأكيد — استُلمت الجلسة

ACCESS_CANCELتم الإلغاء — أُعيد المبلغ إلى الرصيد

BAD_ACTIONالجلسة غير موجودة أو مكتملة بالفعل

مثال على الطلب

# Cancel and refund
curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=setStatus&id=cma4x9k3b0000abc123&status=8'

مثال على الاستجابة

ACCESS_CANCEL

REST API الأصلية

للتكاملات الحديثة، استخدم REST API الأصلية بدلًا من Handler API القديمة. أرسل مفتاح API في ترويسة HTTP x-api-key.

جلسات OTP

حسب الاستخدام

تتيح لك جلسات OTP طلب رقم هاتف مؤقت، واستلام رمز لمرة واحدة، ثم تحرير الرقم — وكل ذلك عبر API. تُحتسب رسوم كل جلسة مرة واحدة عند إنشائها. وإذا ألغيت قبل وصول الرمز، تُسترد الرسوم كاملة.

POST/api/v1/otp/request

اطلب رقم هاتف مؤقتًا للتحقق عبر OTP. يُرجع sessionId والرقم المخصص. تُخصم رسوم OTP_PER_USE فورًا.

المعاملات

الاسم	النوع	إلزامي	الوصف
country	integer	اختياري	رمز الاتصال الدولي للدولة للتصفية (مثل 212). احذفه لأي دولة.
service	string	اختياري	اسم الخدمة مثل "telegram" — يُحفظ في الجلسة للرجوع إليه
webhookUrl	string	اختياري	عنوان HTTPS نرسل إليه طلب POST عند وصول OTP (بدلًا من الاستعلام الدوري)
expiresIn	integer	اختياري	مدة صلاحية الجلسة بالثواني (60–1800، والافتراضي 600)

الاستجابات

200 OKأُنشئت الجلسة — يحتوي جسم الاستجابة على sessionId وnumber وexpiresAt

402 Payment Requiredالرصيد غير كافٍ

503 Service Unavailableلا توجد أرقام متصلة متاحة

مثال على الطلب

curl -X POST https://www.kartesim.com/api/v1/otp/request \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "telegram", "country": 212}'

مثال على الاستجابة

{ "sessionId": "cma4x9k3b0000abc123", "number": "212661234567", "status": "PENDING", "expiresAt": "2026-06-01T00:20:00.000Z" }

GET/api/v1/otp/:sessionId

استعلم دوريًا عن حالة جلسة OTP ورمزها. يُرجع رمز OTP المستخرج بمجرد وصول رسالة SMS. كرّر الاستعلام كل 5–10 ثوانٍ.

الاستجابات

200 OK — PENDINGstatus: "PENDING", otp: null — ما زال في الانتظار

200 OK — RECEIVEDstatus: "RECEIVED", otp: "84729" — الرمز جاهز

200 OK — EXPIREDstatus: "EXPIRED" — لم تصل أي رسالة SMS خلال المهلة

200 OK — CANCELLEDstatus: "CANCELLED" — ألغيت الجلسة

مثال على الطلب

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/otp/cma4x9k3b0000abc123

مثال على الاستجابة

{ "sessionId": "cma4x9k3b0000abc123", "status": "RECEIVED", "number": "212661234567", "otp": "84729", "smsBody": "Your code is 84729" }

POST/api/v1/otp/:sessionId/cancel

ألغِ جلسة في حالة PENDING. تُسترد رسوم OTP كاملة. لا يمكن إلغاء الجلسات التي استلمت OTP بالفعل.

الاستجابات

200 OKstatus: "CANCELLED", refunded: 0.10 — أُضيف المبلغ إلى الرصيد

409 Conflictالجلسة ليست في حالة PENDING — لا يمكن إلغاؤها

404 Not Foundالجلسة غير موجودة أو تابعة لحساب آخر

مثال على الطلب

curl -X POST -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/otp/cma4x9k3b0000abc123/cancel

مثال على الاستجابة

{ "sessionId": "cma4x9k3b0000abc123", "status": "CANCELLED", "refunded": "0.1000" }

POSTعنوان webhook الخاص بك (إرسال من الخادم)

عند وصول OTP، نرسل طلب POST إلى webhookUrl الذي قدّمته عند إنشاء الجلسة. وهذا بديل عن الاستعلام الدوري — إذ يستلم خادمك رمز OTP تلقائيًا دون الحاجة إلى استدعاء getStatus.

محتوى الطلب

طلب POST إلى webhookUrl الخاص بك

{
  "event":      "otp.received",
  "sessionId":  "cma4x9k3b0000abc123",
  "status":     "RECEIVED",
  "number":     "212661234567",
  "otp":        "84729",
  "smsBody":    "Your Telegram code is 84729",
  "receivedAt": "2026-06-21T12:00:00.000Z"
}

الأمان

يجب أن يستخدم عنوان webhook بروتوكول HTTPS في بيئة الإنتاج — تُرفض عناوين HTTP.
نرسل ترويسة X-Webhook-Signature: sha256=... (HMAC-SHA256). تحقّق منها للتأكد من أن الطلب أصلي.
نعيد المحاولة مرة واحدة بعد ثانيتين عند تلقي 5xx. يجب أن تُرجع نقطة النهاية لديك 200 بسرعة.
يجب أن تكون نقطة النهاية لديك متساوية القوة (idempotent) — فقد يتكرر التسليم عند إعادة المحاولة.

GET/api/partner/rentals

اجلب جميع إيجارات الأرقام النشطة في حسابك.

الاستجابات

200 OKمصفوفة JSON بإيجارات الأرقام النشطة

401 Unauthorizedمفتاح API غير صالح أو مفقود

مثال على الطلب

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/rentals

مثال على الاستجابة

[
  {
    "id": "cuid...",
    "phoneNumber": "1234567890",
    "countryCode": 1,
    "expiresAt": "2026-06-25T10:00:00.000Z",
    "daysRemaining": 26
  }
]

GET/api/partner/proxies

اجلب جميع إيجارات البروكسي النشطة في حسابك، بما في ذلك عنوان IP الحالي وبيانات الاعتماد.

الاستجابات

200 OKمصفوفة JSON بإيجارات البروكسي النشطة

401 Unauthorizedمفتاح API غير صالح أو مفقود

مثال على الطلب

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/proxies

مثال على الاستجابة

[
  {
    "id": "cuid...",
    "port": "Port A",
    "host": "192.168.1.10",
    "socks5Port": 1080,
    "username": "user",
    "password": "pwd",
    "expiresAt": "2026-06-25T10:00:00.000Z"
  }
]

GET/api/partner/sms?simNumber=1234567890

اجلب أحدث رسائل SMS التي وصلت إلى أرقامك المستأجرة. ويمكنك التصفية حسب simNumber محدد.

المعاملات

الاسم	النوع	إلزامي	الوصف
simNumber	string	اختياري	تصفية رسائل SMS لرقم مستأجر محدد

الاستجابات

200 OKمصفوفة JSON بأحدث رسائل SMS

401 Unauthorizedمفتاح API غير صالح أو مفقود

مثال على الطلب

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/sms

مثال على الاستجابة

[
  {
    "id": "cuid...",
    "simNumber": "1234567890",
    "fromNumber": "Twilio",
    "body": "Your verification code is 49201",
    "receivedAt": "2026-05-29T15:30:00.000Z"
  }
]

استئجار الأرقام

يمنحك استئجار الرقم استخدامًا حصريًا لشريحة SIM حقيقية طوال مدة إيجار محددة. وتصل كل رسالة SMS يستقبلها هذا الرقم إلى حسابك فورًا. يمكنك استئجار الأرقام مباشرةً عبر API أو من بوابة الشركاء.

الدورة	المدة	الوصف
يومي	24 ساعة	الأنسب لحملات التحقق قصيرة الأمد
أسبوعي	7 أيام	الأنسب للوصول المستمر إلى رقم ثابت
شهري	30 يومًا	الأنسب لرقم مخصص على المدى الطويل

كيف يعمل

استدعِ GET /api/v1/numbers/available لتصفّح الأرقام المتاحة (مُخفاة جزئيًا).
اختر رقمًا ودورة فوترة، ثم استدعِ POST /api/v1/numbers/rent لاستئجاره فورًا.
يُخصم المبلغ من رصيدك فورًا، ويُرجع رقم الهاتف الكامل غير المُخفى في الاستجابة.
تظهر جميع رسائل SMS الواردة إلى رقمك المستأجر في سجلات SMS فورًا.
عند انتهاء المدة يُحرَّر الرقم تلقائيًا، ولا يُسترد أي مبلغ عن الوقت غير المستخدم.

GET/api/v1/numbers/available

تصفّح الأرقام المتاحة للإيجار. تظهر الأرقام مُخفاة جزئيًا (مثل +212 6** *** **7) حتى ترى الدولة والمشغّل قبل الالتزام. ويمكنك التصفية حسب رمز الدولة.

المعاملات

الاسم	النوع	إلزامي	الوصف
country	number	اختياري	رمز الدولة وفق الاتحاد الدولي للاتصالات (مثل 212). احذفه أو استخدم 0 لأي دولة.

الاستجابات

200 OKJSON يتضمن قائمة الأرقام المتاحة والعدد الإجمالي

401 Unauthorizedمفتاح API غير صالح أو مفقود

429 Too Many Requestsتجاوزت حد معدّل الطلبات (30 طلبًا في الدقيقة)

مثال على الطلب

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/numbers/available?country=212

مثال على الاستجابة

{
  "available": [
    {
      "phoneId":      "clx...",
      "maskedNumber": "+212 6** *** **7",
      "countryCode":  212,
      "country":      "Morocco",
      "carrier":      "Orange",
      "pricing": { "daily": null, "weekly": 2.50, "monthly": 8.00 }
    }
  ],
  "total": 1
}

POST/api/v1/numbers/rent

استأجر رقمًا بنفسك. يخصم المبلغ من رصيدك وينشئ إيجارًا حصريًا في عملية واحدة غير قابلة للتجزئة. ويُرجع رقم الهاتف الكامل (غير المُخفى) عند النجاح.

المعاملات

الاسم	النوع	إلزامي	الوصف
phoneId	string	إلزامي	معرّف المنفذ من /api/v1/numbers/available
billingCycle	string	إلزامي	DAILY \| WEEKLY \| MONTHLY
cycles	number	اختياري	عدد دورات الفوترة المدفوعة مقدمًا (1–12، والافتراضي 1)
autoRenew	boolean	اختياري	التجديد التلقائي عند انتهاء المدة (الافتراضي false)

الاستجابات

200 OKأُنشئ الإيجار — رقم الهاتف الكامل في الاستجابة

402 Payment Requiredالرصيد غير كافٍ أو لم يُضبط سعر لهذه الدورة

409 Conflictاستأجر شريك آخر الرقم للتو — أعد المحاولة برقم مختلف

401 Unauthorizedمفتاح API غير صالح أو مفقود

مثال على الطلب

curl -X POST -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"phoneId":"clx...","billingCycle":"MONTHLY","cycles":1}' \
  https://www.kartesim.com/api/v1/numbers/rent

مثال على الاستجابة

{
  "rentalId":     "cly...",
  "phoneNumber":  "+212661234567",
  "countryCode":  212,
  "carrier":      "Orange",
  "billingCycle": "MONTHLY",
  "pricePerCycle": 8.00,
  "cycles":        1,
  "totalCharged":  8.00,
  "autoRenew":     false,
  "startedAt":    "2026-06-21T20:00:00.000Z",
  "expiresAt":    "2026-07-21T20:00:00.000Z"
}

GET/api/partner/rentals

اجلب جميع إيجارات الأرقام النشطة في حسابك.

الاستجابات

200 OKمصفوفة JSON بإيجارات الأرقام النشطة

401 Unauthorizedمفتاح API غير صالح أو مفقود

مثال على الطلب

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/rentals

مثال على الاستجابة

[
  {
    "id": "cuid...",
    "phoneNumber": "+212661234567",
    "maskedNumber": "+212 6** *** **7",
    "countryCode": 212,
    "expiresAt": "2026-06-25T10:00:00.000Z",
    "daysRemaining": 26
  }
]

الأرقام مخصصة لحسابك. لا يُشارك الرقم أبدًا ولا يُعاد تخصيصه خلال مدة إيجارك. ويُخصم الرصيد المطلوب للمدة كاملة عند الاستئجار. وإذا حُجز رقم طلبته بين التصفّح والاستئجار، فستتلقى الاستجابة 409 — أعد المحاولة برقم آخر.

استئجار البروكسي

يوفّر كل منفذ في الأسطول بروكسي HTTP وSOCKS5 عبر اتصال بيانات الهاتف المحمول الخاص به. ويمكن للشركاء تمرير حركة المرور عبر هذه البروكسيات للحصول على عنوان IP حقيقي للهاتف المحمول من دولة محددة.

البروتوكول	المنفذ الافتراضي	ملاحظات
HTTP	يختلف حسب الجهاز	بروكسي HTTP CONNECT — يظهر المنفذ في بوابة الشركاء وفي `/api/partner/proxies`
SOCKS5	1080	بروكسي SOCKS5 — يدعم أنفاق TCP وUDP

بروكسي HTTP — curl

curl --proxy http://USER:PASS@PHONE_IP:8888 https://api.ipify.org

بروكسي SOCKS5 — curl

curl --proxy socks5://USER:PASS@PHONE_IP:1080 https://api.ipify.org

بيانات اعتماد البروكسي وعنوان IP يقدّمها مدير حسابك. يُحدَّث عنوان IP للمنفذ تلقائيًا مع كل نبضة (heartbeat) — وتعرض بوابة الشركاء دائمًا أحدث عنوان. ويتطلب الوصول إلى البروكسي المصادقة — وتُرفض الاتصالات غير المصادق عليها.

عرض البروكسيات النشطة

تظهر اشتراكات البروكسي النشطة لديك — بما في ذلك عنوان IP الحالي والمنفذ وتاريخ الانتهاء — في بوابة الشركاء ضمن البروكسيات. ويُحدَّث حقل IP مباشرةً كلما أبلغ المنفذ عن عنوانه.

الدول المدعومة

استخدم getCountries للحصول على القائمة الحالية. رموز الدول الشائعة:

الرمز	الدولة	الرمز	الدولة
0	أي دولة (تعيين تلقائي)	7	Russia
212	المغرب	33	فرنسا
1	الولايات المتحدة	44	المملكة المتحدة
49	ألمانيا	34	إسبانيا
966	المملكة العربية السعودية	971	الإمارات العربية المتحدة
20	مصر	216	تونس

مرجع الأخطاء

الاستجابة	المعنى
BAD_KEY	مفتاح API غير صالح أو مُلغى أو مفقود
BAD_ACTION	إجراء غير معروف أو معاملات إلزامية مفقودة
TOO_MANY_REQUESTS	تجاوزت حد معدّل الطلبات — 120 طلبًا في الدقيقة
NO_NUMBERS	لا توجد منافذ متصلة متاحة تطابق طلب OTP الخاص بك
NO_BALANCE	الرصيد غير كافٍ لإنشاء جلسة OTP
STATUS_WAIT_CODE	لم يصل OTP بعد — واصل الاستعلام
STATUS_OK:code	وصل OTP — يأتي الرمز الرقمي بعد النقطتين
STATUS_CANCEL	انتهت صلاحية الجلسة أو أُلغيت
ACCESS_NUMBER:id:num	أُنشئت جلسة OTP — يليها معرّف الجلسة ورقم الهاتف
ACCESS_CANCEL	أُلغيت الجلسة وأُعيد المبلغ إلى الرصيد
ACCESS_READY	استُلمت الجلسة / تم تأكيدها

توثيق kartesim للشركاء — لطلب مفتاح API أو للاستفسار عن الإيجارات، تواصل مع مدير حسابك.