توثيق الواجهة البرمجية — AccSouq API

واجهة REST واحدة لكل خدماتنا: المنتجات الرقمية، أرقام SMS، تفعيل App Store و iCloud 5GB، ربط أجهزة الماك وفك حسابات Apple. كل عملية تُخصم من رصيد محفظتك في AccSouq، وكل ردّ JSON.

أنشئ مفتاحك تحقق من الهوية (مطلوب)

البداية

Base URL: https://accsouq.com/api/public/v1

اعتمد التحقق من الهوية (KYC) من صفحة التحقق.
أنشئ مفتاح API وحدّد صلاحياته (scopes).
اشحن محفظتك — كل طلب يُخصم من رصيدك مباشرة.
أرسل الطلبات مع request_id فريد لكل عملية.

المصادقة

أرسل المفتاح بأي من الطريقتين. أي طلب بدون مفتاح صالح يرجع 401.

curl "https://accsouq.com/api/public/v1/balance" \
  -H "Authorization: Bearer ask_live_XXXXXXXXXXXX"

# أو
curl "https://accsouq.com/api/public/v1/balance" -H "x-api-key: ask_live_XXXXXXXXXXXX"

{ "balance_usd": 152.4, "currency": "USD" }

الرصيد والحساب

GET

/balance

scope: wallet

رصيد المحفظة

{ "balance_usd": 152.4, "currency": "USD" }

GET

/me

scope: wallet

بيانات الحساب والصلاحيات

{
  "user_id": "…",
  "name": "متجري",
  "balance_usd": 152.4,
  "scopes": ["digital", "sms"]
}

المنتجات الرقمية

GET

/digital/products

scope: digital

قائمة المنتجات والمخزون

{
  "count": 31,
  "products": [
    {
      "product_id": "0f1c…",
      "name": "ChatGPT Plus 1 Month",
      "description": "اشتراك شهر كامل",
      "category": "AI",
      "price_usd": 12.5,
      "stock": 24,
      "requires_customer_input": false,
      "delivery_type": "text",
      "is_active": true
    }
  ]
}

POST

/digital/orders

scope: digital

شراء منتج (idempotent)

curl -X POST "https://accsouq.com/api/public/v1/digital/orders" \
  -H "Authorization: Bearer ask_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "0f1c…",
    "quantity": 1,
    "request_id": "my-shop-order-1042"
  }'

{
  "order_id": "8a2e…",
  "request_id": "my-shop-order-1042",
  "status": "completed",
  "delivery": "user@mail.com:Pa55word",
  "total_usd": 12.5,
  "error": null
}

تكرار نفس request_id يعيد نفس الطلب الأصلي ولا يخصم الرصيد مرة أخرى.

GET

/digital/orders/{request_id}

scope: digital

متابعة حالة الطلب

الحالات: pending / processing / completed / failed / refunded. عند الفشل بعد الخصم يُردّ المبلغ تلقائيًا.

أرقام SMS

GET

/sms/catalog

scope: sms

الدول والخدمات المتاحة

curl "https://accsouq.com/api/public/v1/sms/catalog" -H "x-api-key: ask_live_XXXX"

GET

/sms/offers?country_id=…&service_id=…

scope: sms

العروض والأسعار النهائية

{
  "count": 3,
  "offers": [
    { "offer_id": "3c1…", "rank": 1, "price_usd": 0.42, "stock": 180, "ttl_days": 1, "otp_type": "API" }
  ]
}

POST

/sms/orders

scope: sms

شراء أرقام

curl -X POST "https://accsouq.com/api/public/v1/sms/orders" \
  -H "x-api-key: ask_live_XXXX" -H "Content-Type: application/json" \
  -d '{"offer_id":"3c1…","quantity":2,"request_id":"sms-889"}'

{
  "order_id": "…",
  "status": "completed",
  "total_usd": 0.84,
  "numbers": [
    { "number_id": "…", "phone": "+447…", "status": "active", "otp_url": null, "last_code": null }
  ]
}

GET

/sms/numbers/{number_id}

scope: sms

متابعة الأكواد الواردة

{
  "number_id": "…",
  "phone": "+447…",
  "status": "active",
  "last_code": "483920",
  "messages": [{ "sender": "Apple", "body": "…", "code": "483920", "received_at": "…" }]
}

تفعيل App Store / iCloud 5GB

POST

/activation/batches

scope: activation

إرسال دفعة تفعيل

curl -X POST "https://accsouq.com/api/public/v1/activation/batches" \
  -H "x-api-key: ask_live_XXXX" -H "Content-Type: application/json" \
  -d '{
    "tool": "both",
    "account_type": "3q",
    "request_id": "act-551",
    "accounts": [{ "email": "a@mail.com", "password": "Pass123" }]
  }'

tool: appstore | icloud5gb | both — account_type: 3q | 2fa | mac (مع 2fa/mac يجب إرسال otp_link لكل حساب).

GET

/activation/batches/{id}

scope: activation

نتيجة الدفعة

{
  "batch_id": "…",
  "status": "settled",
  "total": 28,
  "counts": { "success": 26, "failed": 2 },
  "charged_usd": 1.04,
  "refunded_usd": 0.08,
  "accounts": [{ "email": "a@mail.com", "status": "success", "appstore": true, "icloud": true }]
}

ربط أجهزة الماك

POST

/mac/bindings

scope: mac

رفع حسابات للربط

curl -X POST "https://accsouq.com/api/public/v1/mac/bindings" \
  -H "x-api-key: ask_live_XXXX" -H "Content-Type: application/json" \
  -d '{
    "request_id": "mac-77",
    "accounts": [{
      "email": "a@mail.com", "password": "Pass123",
      "phone": "+201…", "captcha_api": "https://otp.example/api/xyz"
    }]
  }'

GET

/mac/bindings?email=…

scope: mac

حالة الربط وكود الجهاز

{
  "bindings": [
    { "binding_id": "…", "email": "a@mail.com", "status": "bound", "device_code": "XXXX-XXXX" }
  ]
}

فك حسابات Apple المقفلة

POST

/unlock/batches

scope: unlock

إرسال دفعة فك

curl -X POST "https://accsouq.com/api/public/v1/unlock/batches" \
  -H "x-api-key: ask_live_XXXX" -H "Content-Type: application/json" \
  -d '{"request_id":"unl-12","accounts":[{"email":"a@mail.com","phone":"+201234567"}]}'

GET

/unlock/batches/{id}

scope: unlock

نتيجة الدفعة

{ "batch_id": "…", "status": "settled", "total": 10, "counts": { "unlocked": 9, "error": 1 } }

الويبهوك (اختياري)

سجّل رابطك من صفحة المفاتيح، وستستلم POST عند اكتمال أو فشل الطلبات. تحقّق من التوقيع:

// Node.js
import crypto from "crypto";

const ts = req.headers["x-accsouq-timestamp"];
const sig = req.headers["x-accsouq-signature"];
const expected = crypto
  .createHmac("sha256", process.env.ACCSOUQ_WEBHOOK_SECRET)
  .update(`${ts}.${rawBody}`)
  .digest("hex");

if (sig !== expected) return res.status(401).end();

الأحداث: order.completed · order.failed · order.processing · number.code_received. تُعاد المحاولة حتى 6 مرات بتأخير متزايد.

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

{ "error": { "code": "insufficient_balance", "message": "رصيد المحفظة غير كافٍ" } }

أكواد الأخطاء

كل خطأ يرجع بصيغة JSON موحّدة مع HTTP status مناسب.

code	HTTP	المعنى
invalid_key	401	المفتاح مفقود أو غير صالح
key_revoked	401	المفتاح معطّل
kyc_required	403	التحقق من الهوية غير معتمد
forbidden_scope	403	المفتاح لا يملك صلاحية هذه الخدمة
invalid_request	400	بيانات الطلب غير صحيحة
insufficient_balance	402	رصيد المحفظة غير كافٍ
out_of_stock	409	المخزون غير كافٍ
product_unavailable	409	المنتج/العرض غير متاح
duplicate_request_id	409	request_id مستخدم أو قيد التنفيذ
rate_limited	429	تجاوز الحد — راجع هيدر Retry-After
service_disabled	503	الخدمة متوقفة مؤقتًا
provider_error	502	خطأ من المزوّد
not_found	404	العنصر غير موجود
internal_error	500	خطأ داخلي

الحدود

قراءة: حتى 120 طلب/دقيقة لكل مفتاح (متابعة الأرقام حتى 600).
شراء: 60 طلب/دقيقة للمنتجات والأرقام، 30 للدفعات الكبيرة.
أقصى كمية: 50 للمنتج الرقمي، 500 رقم، 2000 حساب تفعيل، 500 ربط ماك، 5000 فك.
عند التجاوز: 429 مع هيدر Retry-After بالثواني.