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

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

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

المصادقة

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

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

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

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

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

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

من لوحة التحكم يمكن تفعيل تأكيد التحويل بالإيميل لأي حساب شام كاش مرتبط. عند التفعيل: التحويل الحقيقي (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 → البوت يسلّم بدون رقم عملية من الزبون.

الصلاحيات

• write:invoices — إنشاء / إلغاء
• read:invoices — جلب / قائمة

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": "اشتراك شهري"
}

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

الجسم يتضمن الفاتورة المدفوعة مع tran_id والحوالة. تحقق التوقيع بنفس طريقة Webhooks العامة باستخدام سر لوحتك.

مسارات أخرى

مثال 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.amount

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

Webhooks

من اللوحة فعّل الرابط. عند حوالة واردة جديدة (أو invoice.paid) نرسل POST إلى رابطك:

مهم: استخدم الجسم الخام (raw body) كما وصل — لا تعيد تنسيق JSON قبل حساب التوقيع.

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

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

مثال جسم وارد

{
  "type": "transaction.incoming",
  "data": {
    "tran_id": "184627893",
    "amount": 5000,
    "currency": "SYP",
    "account_address": "YOUR_ADDR",
    "note": ""
  }
}

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

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

رموز الأخطاء