توثيق API

واجهة REST API للوصول الجماعي / الآلي إلى jiema.my. استخدمها لدمج التحقق عبر الرسائل القصيرة في خدماتك الخاصة. جميع نقاط النهاية تُرجع JSON.

يرجى تسجيل الدخول لإنشاء أول مفتاح API لك.

المحتويات

المصادقة
الأخطاء وحدود المعدل
GET /v1/account
GET /v1/services
GET /v1/countries
GET /v1/prices
POST /v1/orders
GET /v1/orders/:id
POST /v1/orders/:id/cancel
POST /v1/orders/:id/next-sms
GET /v1/orders
سير العمل النموذجي

المصادقة

يجب أن يتضمن كل طلب مفتاح API الخاص بك:

Authorization: Bearer jm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

صيغة رأس بديلة: X-API-Key: jm_xxx…

يمكنك إنشاء المفاتيح وإلغاؤها عبر /account/api-keys. يمكن لكل مستخدم الاحتفاظ بحد أقصى 10 مفاتيح نشطة. يُعرض الـ token الكامل مرة واحدة فقط عند الإنشاء — احفظه في مكان آمن.

الأخطاء وحدود المعدل

تُرجع جميع الأخطاء JSON:

{ "ok": false, "code": "RATE_LIMITED", "message": "..." }

HTTP	code	المعنى
401	AUTH_MISSING / AUTH_INVALID	لا يوجد مفتاح أو تم إلغاؤه
403	FORBIDDEN	محظور أو لا يوجد وصول
400	BAD_REQUEST / INSUFFICIENT / NO_NUMBERS / …	خطأ في التحقق أو في منطق العمل
404	NOT_FOUND	الطلب غير موجود (أو ليس لك)
429	RATE_LIMITED	تحديد المعدل لكل مفتاح
500	INTERNAL	خطأ في الخادم (تم الإبلاغ تلقائيًا)

حدود المعدل: لكل مفتاح، نافذة منزلقة 60s. نقاط نهاية الكتابة (orders, cancel, next-sms) 10 req/min؛ نقاط نهاية القراءة (account, services, prices, list) 60 req/min.

GET /v1/account

احصل على رصيدك الحالي وملفك الشخصي الأساسي.

curl https://jiema.my/api/v1/account \
  -H "Authorization: Bearer jm_xxx"

# 200 OK
{ "ok": true, "data": {
  "id": "clxxxxxxxxxxx",
  "balanceCents": "1200",       // string to preserve precision; $12.00
  "referralCode": "abc123",
  "displayName": "Alice",
  "lang": "en"
}}

GET /v1/services

اعرض الخدمات المتاحة مع المخزون. مخزّن مؤقتًا على الخادم لمدة ~5 دقائق.

curl https://jiema.my/api/v1/services -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "items": [
  { "code": "tg", "slug": "telegram", "name": "Telegram",
    "minCostUsd": 0.18, "totalCount": 1234, "countryCount": 24 },
  ...
] }}

استخدم code (أو الـ slug الودود) كحقل service عند إنشاء طلب.

GET /v1/countries

curl https://jiema.my/api/v1/countries -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "items": [
  { "id": 7, "slug": "my", "name": "Malaysia" },
  ...
] }}

id هو معرّف الدولة الرقمي من المصدر الأعلى؛ slug هو الرمز القصير المخصص لـ SEO (مثل "my" / "us"). كلا الصيغتين تعمل كحقل country.

GET /v1/prices?service=tg

السعر والمخزون لكل دولة لخدمة معينة. الأسعار تتضمن بالفعل هامش الربح / الخصم المُهيأ من قِبل التشغيل.

curl "https://jiema.my/api/v1/prices?service=tg" -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": {
  "service": "tg",
  "items": [
    { "countryId": 7, "countrySlug": "my", "priceCents": "32", "count": 540 },
    ...
  ]
}}

POST /v1/orders

أنشئ طلب تحقق عبر SMS. يحجز النظام رقم هاتف من المصدر الأعلى ويخصم المبلغ من رصيدك.

curl -X POST https://jiema.my/api/v1/orders \
  -H "Authorization: Bearer jm_xxx" \
  -H "content-type: application/json" \
  -d '{ "service": "tg", "country": 7 }'

{ "ok": true, "data": {
  "id": "ckxxxxx",
  "status": "WAITING",
  "service": "tg",
  "country": "7",
  "phone": "+60123456789",
  "expiresAt": "2026-05-22T08:30:00.000Z",
  "chargedCents": "32"
}}

لا توجد حقول اختيارية بخلاف service / country.

أكواد الخطأ الشائعة: INSUFFICIENT (يلزم شحن الرصيد)، NO_NUMBERS، BAD_SERVICE، BAD_COUNTRY.

GET /v1/orders/:id

استعلم بشكل دوري حتى تصبح status بقيمة RECEIVED ويصبح smsBody غير فارغ.

curl https://jiema.my/api/v1/orders/ckxxxxx -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": {
  "id": "ckxxxxx",
  "status": "RECEIVED",
  "phone": "+60123456789",
  "smsBody": "Your verification code is 123456",
  "smsHistory": [
    { "body": "Your verification code is 123456", "receivedAt": "..." }
  ],
  "smsReceivedAt": "2026-05-22T08:12:34.000Z",
  ...
}}

الحالات: WAITING (الرقم نشط، بانتظار SMS) · RECEIVED (وصل الكود) · COMPLETED / FAILED / CANCELLED حالات نهائية.

الاستعلام المقترح: كل 3–5 ثوانٍ. تتم مزامنة المصدر الأعلى داخل نقطة النهاية هذه، لذا فإن استعلامك يدفع الحالة حتى لو كان العامل الخلفي مشغولًا.

POST /v1/orders/:id/cancel

ألغِ طلبًا لم يستلم كودًا بعد. استرداد كامل المبلغ إلى رصيدك.

curl -X POST https://jiema.my/api/v1/orders/ckxxxxx/cancel \
  -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "id": "ckxxxxx", "status": "CANCELLED" }}

يُرفض بـ CODE_RECEIVED إذا كان الرقم قد استقبل أي SMS، أو ALREADY_CHANGED إذا تغيّرت الحالة بشكل متزامن.

POST /v1/orders/:id/next-sms

بعد RECEIVED، اطلب من المصدر الأعلى إبقاء الرقم نشطًا وانتظار SMS آخر (دون رسوم إضافية ضمن النافذة النشطة).

curl -X POST https://jiema.my/api/v1/orders/ckxxxxx/next-sms \
  -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "id": "ckxxxxx", "status": "WAITING" }}

GET /v1/orders

قائمة بطلباتك الأخيرة مع ترقيم صفحات قائم على المؤشر.

curl "https://jiema.my/api/v1/orders?limit=20" -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": {
  "items": [ { "id": "ck...", "status": "RECEIVED", "service": "tg", ... }, ... ],
  "nextCursor": "ck..." | null
}}

استعلام اختياري: status · limit 1–100 (الافتراضي 20) · cursor = nextCursor الصفحة السابقة.

سير العمل النموذجي

اشحن الرصيد عبر واجهة الويب → GET /v1/account لتأكيد الرصيد.
اختر خدمة: GET /v1/services و GET /v1/prices?service=tg.
أنشئ طلبًا: POST /v1/orders مع service + country.
اقرأ data.phone وشغّل إرسال SMS من المصدر الأعلى من تطبيقك (مثلًا الصقه في تسجيل Telegram).
استعلم GET /v1/orders/:id كل 3–5s. عندما تصبح status === "RECEIVED"، اقرأ smsBody.
إذا كان SMS خاطئًا أو تريد كودًا ثانيًا: POST /v1/orders/:id/next-sms → تعود إلى WAITING.
انتهى. إذا ألغيت قبل وصول أي SMS: POST /v1/orders/:id/cancel لاسترداد كامل.

jiema.my