الدليل الكامل للواجهة البرمجية

ما الذي يُستبدل في الطلب؟

في كل مثال ستجد قيماً بين أقواس أو بصيغة واضحة. استبدلها بقيمك الحقيقية قبل التشغيل:

المصادقة

أرسل المفتاح بإحدى الطريقتين (الترويسة أفضل):

العنوان الأساسي: /api/v1

أسلوب المسارات (Query vs REST)

البوابة تدعم نمطين معاً — نفس النتيجة. استخدم REST للتكاملات الجديدة؛ الـ Query يبقى للتوافق:

سحب سجل الحوالات بالكامل

ما يُستبدل هنا

• YOUR_ADDR → عنوان المحفظة المرتبطة
• YOUR_KEY → مفتاحك في الترويسة أو الاستعلام

بدائل الإجراء: outgoing_logs · all_logs

البحث برقم العملية

ما يُستبدل في هذا الطلب

التحقق برقم العملية + المبلغ

ما يُستبدل هنا

عرض الرصيد الكامل · balances

استعلام واحد يرجع أرصدة المحفظة المرتبطة بالعملات الثلاث: SYP · USD · EUR.

ما يُستبدل هنا

التحويلات عبر شام كاش

أرسل حوالة من محفظة مرتبطة إلى عنوان شام كاش آخر. الصلاحية write:transfers اختيارية وغير مفعّلة افتراضياً — فعّلها من لوحة التحكم قبل الاستخدام.

تحذير: على مفتاح Live يتم خصم رصيد حقيقي من المحفظة المرتبطة. اختبر أولاً بمفتاح sk_test_.

التحقق من المستلم قبل التحويل

{
  "account_address": "YOUR_ADDR",
  "address": "PEER_ADDR"
}

تنفيذ التحويل + ملاحظة اختيارية

{
  "account_address": "YOUR_ADDR",
  "to": "PEER_ADDR",
  "amount": 1000,
  "currency": "SYP",
  "note": "طلب #99",
  "pin": "OPTIONAL_PIN",
  "unique_key": "OPTIONAL_UUID"
}

منع التكرار · unique_key

• إذا أرسلت unique_key بنفسك: ShamGate تحتفظ بالنتيجة 24 ساعة (Mongo TTL).
• إعادة نفس المفتاح + نفس الطلب (محفظة/مستلم/مبلغ/عملة/ملاحظة) → تُرجع نفس الاستجابة مع meta.idempotent_replay: true بدون تحويل ثانٍ.
• نفس المفتاح مع طلب مختلف → 409 IDEMPOTENCY_KEY_CONFLICT.
• إن لم ترسل المفتاح، تولّد البوابة UUID جديداً (كل طلب = تحويل مستقل، بلا replay).
• يُمرَّر المفتاح أيضاً إلى شام كاش كـ UniqueKey.

تأكيد التحويل بالإيميل (اختياري)

من لوحة التحكم يمكن تفعيل تأكيد التحويل بالإيميل لأي حساب شام كاش مرتبط. عند التفعيل: التحويل الحقيقي (Live) لا يُنفَّذ فوراً — تُرسل البوابة رمزاً من 6 أرقام إلى بريد صاحب الحساب، ولا يكتمل التحويل إلا بعد إدخال الرمز.

ملاحظة: Sandbox (sk_test_) يتجاوز التأكيد. التأكيد يطبَّق على Live فقط وللحسابات التي فعّلت الخيار.

1) طلب التحويل — إن كان التأكيد مفعّلاً

نفس جسم التحويل العادي. الاستجابة تكون HTTP 202:

{
{
  "success": false,
  "code": "TRANSFER_CONFIRMATION_REQUIRED",
  "error": "يتطلب التحويل تأكيداً برمز أُرسل إلى بريدك",
  "data": {
    "challenge_id": "tch_…",
    "expires_in": 600,
    "email_hint": "no***@gmail.com",
    "account_address": "YOUR_ADDR",
    "to": "PEER_ADDR",
    "amount": 1000,
    "currency": "SYP",
    "next": "POST /api/v1/transfers/confirm مع challenge_id و code"
  }
}

2) تأكيد الرمز وتنفيذ التحويل

{
  "challenge_id": "tch_…",
  "code": "123456"
}

const axios = require('axios');

// 1) طلب التحويل
const first = await axios.post('BASE/api/v1/transfers', {
  account_address: 'YOUR_ADDR',
  to: 'PEER_ADDR',
  amount: 1000,
  currency: 'SYP',
  note: 'طلب #99'
}, { headers: { 'X-Api-Key': 'YOUR_KEY' }, validateStatus: () => true });

if (first.status === 202 && first.data.code === 'TRANSFER_CONFIRMATION_REQUIRED') {
  const code = '123456'; // من الإيميل
  const { data } = await axios.post('BASE/api/v1/transfers/confirm', {
    challenge_id: first.data.data.challenge_id,
    code
  }, { headers: { 'X-Api-Key': 'YOUR_KEY' } });
  console.log(data);
}

Sandbox

بمفتاح sk_test_ جرّب بدون شام كاش:

• TX_SANDBOX_100 + مبلغ 100
• TX_SANDBOX_5000 + مبلغ 5000
• التحويلات: أي to + مبلغ → يرجع TX_SANDBOX_XFER_… بدون خصم حقيقي

تذكير: Sandbox لا يلمس شام كاش الحقيقي. Live يخصم/يقرأ من المحفظة المرتبطة فعلياً.

نظام الفواتير (اختياري)

فعّله من لوحة التحكم. التدفق الموصى به: البوت ينشئ فاتورة مع webhook_url → الزبون يدفع → بوابتنا تطابق الحوالة تلقائياً وترسل invoice.paid → البوت يسلّم بدون رقم عملية من الزبون.

مهم جداً: لا تستخدم نفس رابط الفواتير كـ webhook عام في لوحة «Webhooks». خصّص webhook_url لكل فاتورة (أو لمسار invoice في بوتك)، واترك الـ webhook العام لـ transaction.incoming فقط إن احتجته.

كيف تتم المطابقة؟ ولماذا المبلغ الفريد؟

حوالة شام كاش الواردة لا تحمل اسم الزبون ولا رقم فاتورة — فقط: المحفظة + العملة + المبلغ + الوقت + tran_id. لذلك تطابق البوابة الفاتورة هكذا:

• نفس account_address (محفظة الاستلام)
• نفس العملة + نفس المبلغ (بهامش 0.01)
• الفاتورة pending وغير منتهية
• وقت الحوالة ≥ وقت إنشاء الفاتورة (ناقص هامش دقيقتين)
• كل tran_id يُستخدم مرة واحدة فقط لكل مستخدم API

إذا وُجدت عدة فواتير معلّقة بنفس المبلغ على نفس المحفظة، تُربط الحوالة بـأقدم فاتورة مطابقة — وقد لا تكون فاتورة الزبون الصحيح.

أمان إضافي: اختيارياً من اللوحة «رفض الحوالات التي فيها ملاحظة» — يرفض فقط إذا خانة الملاحظة في تحويل شام كاش الوارد غير فارغة. حقل note عند إنشاء الفاتورة (ملاحظة البوت/الطلب) لا يمنع المطابقة. الهامش الزمني للمطابقة: دقيقتان قبل إنشاء الفاتورة.

الصلاحيات

• write:invoices — إنشاء / إلغاء / دفع تجريبي
• read:invoices — جلب / قائمة

إذا رجعت 403 FORBIDDEN_SCOPE: من لوحة التحكم فعّل نظام الفواتير ثم فعّل صلاحيات الفواتير على مفتاح الـ API.

1) إنشاء فاتورة

{
  "amount": 5000,
  "currency": "SYP",
  "account_address": "YOUR_ADDR",
  "webhook_url": "https://your-bot.com/hooks/invoice",
  "expires_in_minutes": 30,
  "unique_amount": true,
  "metadata": { "order_id": "ORD-99" },
  "note": "اشتراك شهري"
}

expires_in_minutes: بين 5 و 1440 (افتراضي 30).

2) إشعار الدفع

الجسم يتضمن الفاتورة المدفوعة مع tran_id وmatch_reason والحوالة. عند انتهاء المدة تُرسل invoice.expired تلقائياً. إعادة المحاولة نفس سياسة الـ Webhooks العامة أدناه.

3) Sandbox للفواتير

بمفتاح sk_test_:

1. أنشئ فاتورة: POST /api/v1/invoices
2. حاكِ الدفع: POST /api/v1/invoices/{invoice_number}/simulate-pay
3. يصلك invoice.paid على webhook_url

مسارات أخرى

قائمة الفواتير · التقسيم (Pagination)

• page — رقم الصفحة (افتراضي 1)
• limit — عناصر الصفحة (افتراضي 20، أقصى 100)
• status — اختياري: pending / paid / expired / cancelled
• account_address — اختياري: تصفية بمحفظة

حقول التقسيم داخل data، ونسخة احترافية أيضاً داخل meta.pagination:

{
{
  "success": true,
  "data": {
    "items": [ /* فواتير */ ],
    "total": 42,
    "page": 1,
    "pages": 3,
    "limit": 20
  },
  "meta": {
    "request_id": "req_…",
    "mode": "live",
    "pagination": {
      "page": 1,
      "pages": 3,
      "total": 42,
      "limit": 20
    }
  }
}

مثال Node.js — إنشاء

const axios = require('axios');

const { data } = await axios.post('BASE/api/v1/invoices', {
  amount: 5000,
  currency: 'SYP',
  account_address: 'YOUR_ADDR',
  webhook_url: 'https://your-bot.com/hooks/invoice',
  unique_amount: true,
  metadata: { order_id: 'ORD-99' }
}, { headers: { 'X-Api-Key': 'YOUR_KEY' } });

console.log(data.data.invoice_number, data.data.amount, data.data.base_amount);
// أخبر الزبون يدفع المبلغ الظاهر في data.data.amount (قد يختلف عن base_amount)

حالات الفاتورة

Webhooks

من اللوحة فعّل الرابط. عند حوالة واردة جديدة نرسل transaction.incoming. أحداث الفواتير (invoice.paid / invoice.expired) تذهب إلى webhook_url الخاص بالفاتورة.

مهم: استخدم الجسم الخام (raw body) كما وصل — لا تعيد تنسيق JSON قبل حساب التوقيع. لا تربط رابط الفواتير كـ webhook عام لتجنّب خلط الأحداث. عالج Idempotency-Key / id عندك حتى لا تكرر التسليم عند إعادة المحاولة.

معادلة التوقيع

ارفض الطلب إذا انحرف الوقت أكثر من ~5 دقائق، أو إذا فشل مطابقة v1.

إعادة المحاولة عند الفشل (Retry Policy)

إذا كان سيرفرك متوقفاً أو رجع غير 2xx، تُعاد المحاولة تلقائياً من صندوق الصادر (outbox):

مراقبة التسليم وإعادة الجدولة

يرجع صندوق الصادر (outbox: pending / processing / delivered / dead) + آخر المحاولات + نسخة من سياسة الإعادة.

يعيد جدولة تسليم dead (أو pending) من الصفر. مفيد بعد إصلاح سيرفرك.

مثال جسم · transaction.incoming

{
  "id": "evt_…",
  "type": "transaction.incoming",
  "created_at": "2026-09-22T12:00:00.000Z",
  "mode": "live",
  "data": {
    "account_address": "YOUR_ADDR",
    "transaction": {
      "tran_id": "184627893",
      "amount": 5000,
      "currency": "SYP",
      "note": "",
      "type": "incoming"
    }
  }
}

مثال جسم · invoice.paid

{
  "id": "evt_…",
  "type": "invoice.paid",
  "created_at": "2026-09-22T12:01:00.000Z",
  "mode": "live",
  "data": {
    "invoice": {
      "invoice_number": "INV-…",
      "status": "paid",
      "amount": 1.01,
      "base_amount": 1,
      "currency": "USD",
      "tran_id": "184627893",
      "metadata": { "order_id": "ORD-99" }
    }
  }
}

التحقق عملياً — Node.js

التحقق عملياً — PHP

رموز الأخطاء