توثيق API

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

Authorization: Bearer jm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

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

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

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

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

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

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"
}}

اعرض الخدمات المتاحة مع المخزون. مخزّن مؤقتًا على الخادم لمدة ~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 عند إنشاء طلب.

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.

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

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 },
    ...
  ]
}}

أنشئ طلب تحقق عبر 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.

استعلم بشكل دوري حتى تصبح 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 ثوانٍ. تتم مزامنة المصدر الأعلى داخل نقطة النهاية هذه، لذا فإن استعلامك يدفع الحالة حتى لو كان العامل الخلفي مشغولًا.

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

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 إذا تغيّرت الحالة بشكل متزامن.

بعد 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" }}

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

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 الصفحة السابقة.

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