API التبادل للشركاء

1. نظرة عامة

تتيح لك API التبادل للشركاء تنفيذ عمليات تبادل العملات المشفرة من تطبيقك عبر طلبات HTTP بسيطة. ترسل JSON — فتُعيد API سعر الصرف وعنوان الإيداع وحالة التبادل. يشرح هذا القسم المسار العام؛ وكل خطوة مشروحة بالتفصيل أدناه.

كيف يتم التبادل

يتبع كل تبادل المسار نفسه المكوّن من أربع خطوات:

1. الكتالوج (GET /assets). تعرّف على الأصول المتاحة وحدودها. يوفّر الكتالوج الرموز المختصرة للأصول — usdt وbtc وeth وxmr وغيرها.
2. عرض السعر (POST /quotes). تسأل: "كم BTC سيحصل العميل مقابل 20 USDT؟" فتجيب API بسعر الصرف والمبالغ الدقيقة. عرض السعر غير ملزم ويبقى صالحًا لمدة دقيقتين.
3. إنشاء التبادل (POST /exchanges). تؤكّد عرض السعر — فتفتح API طلبًا وتُعيد عنوان إيداع يجب على العميل إرسال الأموال إليه.
4. الحالة (GET /exchanges/{quote_id}). تستعلم من API لمعرفة ما إذا وصل الإيداع وتم إرسال الدفعة.

ما تحتاجه للبدء

1. حساب في لوحة تحكم الشريك.
2. طلب وصول إلى API تمت الموافقة عليه (يُرسل من لوحة التحكم ويراجعه المشرف).
3. مفتاح API يبدأ بـ spx_… — يُصدر في لوحة التحكم بعد الموافقة. يُعرض المفتاح مرة واحدة فقط عند إصداره أو إعادة إصداره: احفظه في مكان آمن فورًا.

الطرق

صيغة البيانات

• جميع الطلبات والاستجابات بصيغة JSON وبترميز UTF-8.
• جميع المبالغ المالية نصوص (strings): "20"، "0.000312". الفاصل العشري هو النقطة. استخدام النصوص مقصود: الأرقام العشرية العائمة تفقد الدقة مع مبالغ العملات المشفرة.
• التواريخ بصيغة ISO-8601 مع المنطقة الزمنية، مثل 2026-07-27T13:02:00+00:00.

الترويسات (headers) لكل طلب

X-API-Key: spx_your_key
Content-Type: application/json   (POST requests only)
Accept: application/json

القواعد الأساسية

• عرض السعر صالح لمدة دقيقتين (الحقل expires_at) — يجب إنشاء التبادل قبل انتهاء صلاحيته.
• طلب واحد كحد أقصى لكل عنوان IP كل 7 ثوانٍ عبر جميع الطرق؛ تجاوز ذلك يُعيد HTTP 429 (انظر "الأخطاء والحدود").
• إعادة محاولة إنشاء التبادل بالمعاملات نفسها آمنة: لا يُنشأ تبادل مكرر — بل يُعاد التبادل نفسه.

2. المصادقة

يجب أن يتضمن كل طلب إلى API الترويسة X-API-Key مع مفتاحك. لا رموز ولا تواقيع ولا جلسات — هذه الترويسة فقط.

GET https://snapex.pro/api/v1/partner/assets
X-API-Key: spx_your_key
Accept: application/json

من أين تحصل على المفتاح

لوحة تحكم الشريك ← تبويب "API" ← "إصدار مفتاح". يبدأ المفتاح بـ spx_ ويُعرض مرة واحدة. إعادة الإصدار تُبطل المفتاح القديم فورًا.

أخطاء المصادقة

3. كتالوج الأصول — GET /assets

دليل الأصول المتاحة وحدود مبالغ الإرسال. يبدأ الدمج من هنا: فهو يوفّر رموز الأصول لعروض الأسعار ونطاقات المبالغ المسموح بها. الاستجابة عند النجاح — HTTP 200.

تقبل API فقط الرموز المختصرة من الحقل code في هذا الكتالوج (usdt وbtc وeth وxmr وغيرها). لا تُقبل المعرّفات الداخلية الخام للبلوكتشين. نادرًا ما يتغير الكتالوج — يمكنك تخزينه مؤقتًا لديك لمدة 5–10 دقائق.

مثال على الطلب

GET https://snapex.pro/api/v1/partner/assets
X-API-Key: spx_your_key
Accept: application/json

مثال على الاستجابة

{
  "assets": [
    {
      "code": "usdt",
      "network": "TRON",
      "symbol": "USDT",
      "name": "USDT TRON",
      "min_amount": "10",
      "max_amount": "5000",
      "min_usd": "10",
      "max_usd": "5000"
    },
    {
      "code": "btc",
      "network": "Bitcoin",
      "symbol": "BTC",
      "name": "BTC",
      "min_amount": "0.000085",
      "max_amount": "0.0425",
      "min_usd": "10",
      "max_usd": "5000"
    }
  ]
}

حقول الاستجابة

حدود USD حسب نوع المسار

تعتمد الحدود على ما إذا كانت Monero (XMR) جزءًا من التبادل. يُطبَّق التحقق على قيمة USD للمبلغ الذي يرسله العميل.

الكتالوج الحالي

يعرض الجدول أدناه البيانات نفسها التي يُعيدها GET /assets، للرجوع السريع.

4. عرض السعر — POST /quotes

يحسب سعر الصرف ومبالغ التبادل الدقيقة. لا يُنشئ شيئًا ولا يُلزمك بشيء: لا يُخصَّص عنوان إيداع ولا تُحجز أي أموال. الاستجابة عند النجاح — HTTP 201. عرض السعر صالح لمدة دقيقتين.

وضعان: side=send وside=receive

تحدد المعاملة side أيّ المبلغين هو الثابت:
side=send — "يرسل العميل X بالضبط، فكم سيستلم؟" يُحدَّد المبلغ بأصل الإرسال (from).
side=receive — "يريد العميل استلام Y بالضبط، فكم يجب أن يرسل؟" يُحدَّد المبلغ بأصل الاستلام (to).

مرّر إما amount أو amount_usd — واحدًا منهما فقط. إرسال الاثنين معًا يُعيد الخطأ 422.

مثال على الطلب

POST https://snapex.pro/api/v1/partner/quotes
Content-Type: application/json
X-API-Key: spx_your_key

{
  "from_asset_id": "usdt",
  "to_asset_id": "btc",
  "side": "send",
  "amount": "20",
  "recipient_address": "bc1qexampleaddress"
}

معاملات الطلب

مثال على الاستجابة

{
  "quote_id": "pq_abc123",
  "status": "quoted",
  "side": "send",
  "from_symbol": "USDT",
  "to_symbol": "BTC",
  "from_network": "TRON",
  "to_network": "Bitcoin",
  "request_amount": "20",
  "send_amount": "20",
  "receive_amount": "0.000312",
  "amount_in_usd": "20",
  "amount_out_usd": "19.85",
  "expires_at": "2026-07-27T13:02:00+00:00"
}

حقول الاستجابة

5. إنشاء التبادل — POST /exchanges

يحوّل عرض السعر إلى تبادل فعلي: يُفتح طلب ويُعاد عنوان إيداع لتحويل العميل. استدعِه قبل انتهاء صلاحية عرض السعر (دقيقتان). الاستجابة عند النجاح — HTTP 201.

مثال على الطلب

POST https://snapex.pro/api/v1/partner/exchanges
Content-Type: application/json
X-API-Key: spx_your_key

{
  "quote_id": "pq_abc123",
  "recipient_address": "bc1qexampleaddress"
}

معاملات الطلب

ما الذي يحدث عند هذا الاستدعاء

1. تعثر API على عرض السعر الخاص بك وتتحقق من أنه لم تنتهِ صلاحيته.
2. يُعاد التحقق من سعر الصرف مقابل السوق. إذا تحرّك عكس عرض السعر بأكثر من 2%، فلن يُنشأ تبادل ويُعاد 422 (ما عليك إلا طلب عرض سعر جديد).
3. يُفتح طلب ويُخصَّص عنوان إيداع.
4. تتضمن الاستجابة الكتلة deposit — العنوان والمبلغ اللذين يجب على العميل تحويلهما.

مثال على الاستجابة

{
  "quote_id": "pq_abc123",
  "status": "awaiting_deposit",
  "side": "send",
  "from_symbol": "USDT",
  "to_symbol": "BTC",
  "from_network": "TRON",
  "to_network": "Bitcoin",
  "request_amount": "20",
  "send_amount": "20",
  "receive_amount": "0.000312",
  "amount_in_usd": "20",
  "amount_out_usd": "19.85",
  "expires_at": "2026-07-27T13:02:00+00:00",
  "deposit": {
    "asset": "USDT",
    "amount": "20",
    "address": "TXyz…",
    "amount_usd": "20"
  },
  "exchange": {
    "public_id": "ex_…",
    "status": "awaiting_deposit",
    "recipient_address": "bc1qexampleaddress"
  }
}

الحقول الجديدة مقارنةً بعرض السعر

إعادة المحاولة (Idempotency)

إذا انقطع الاتصال ولم تتلقَّ أي استجابة — فقط كرّر الطلب بنفس quote_id وrecipient_address. لن يُنشأ تبادل مكرر: ستُعيد API التبادل الموجود بالفعل. لا يمكن تغيير recipient_address بعد الإنشاء — ومحاولة ذلك تُعيد 422.

الأخطاء المحتملة

• 409 quote_expired — انتهت صلاحية عرض السعر (مرّ أكثر من دقيقتين). اطلب عرضًا جديدًا عبر POST /quotes.
• 422 validation_error — معاملات غير صالحة؛ أو محاولة تغيير recipient_address عند إعادة المحاولة؛ أو تحرّك سعر الصرف بأكثر من 2% — اطلب عرض سعر جديدًا.
• 404 not_found — quote_id غير موجود أو يخص شريكًا آخر.
• 503 upstream_unavailable — عطل مؤقت لدى مزوّد السيولة. أعد المحاولة لاحقًا بنفس عرض السعر (إن كان لا يزال صالحًا) أو بعرض جديد.

6. الحالة — GET /exchanges/{quote_id}

يُعيد الحالة الحالية لعرض السعر أو التبادل. صيغة الاستجابة مطابقة لاستجابة الإنشاء. الاستجابة عند النجاح — HTTP 200. استعلم مرة واحدة كل 7 ثوانٍ كحد أقصى.

مثال على الطلب

GET https://snapex.pro/api/v1/partner/exchanges/pq_abc123
X-API-Key: spx_your_key
Accept: application/json

قيم status

الحالات النهائية: completed وerror وcancelled وexpired. لا تتغير الحالة بعدها — ولا داعي لمزيد من الاستعلام.

عندما تكون status=completed، قد تتضمن الكتلة exchange الحقل partner_api_earning_usd — أرباحك من الصفقة بالدولار الأمريكي.

مثال على الاستجابة

{
  "quote_id": "pq_abc123",
  "status": "completed",
  "side": "send",
  "from_symbol": "USDT",
  "to_symbol": "BTC",
  "from_network": "TRON",
  "to_network": "Bitcoin",
  "request_amount": "20",
  "send_amount": "20",
  "receive_amount": "0.000312",
  "amount_in_usd": "20",
  "amount_out_usd": "19.85",
  "expires_at": "2026-07-27T13:02:00+00:00",
  "deposit": {
    "asset": "USDT",
    "amount": "20",
    "address": "TXyz…",
    "amount_usd": "20"
  },
  "exchange": {
    "public_id": "ex_…",
    "status": "completed",
    "recipient_address": "bc1qexampleaddress",
    "partner_api_earning_usd": "0.20"
  }
}

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

تشترك جميع الأخطاء في صيغة JSON واحدة. رمز حالة HTTP يعكس معنى الحقل error — يمكنك الاعتماد على أيّ منهما.

{
  "ok": false,
  "error": "validation_error",
  "message": "Human-readable explanation in English"
}

مرجع الأخطاء

حدود معدل الطلبات

8. مثال: تبادل من البداية إلى النهاية

سيناريو كامل: يرسل العميل 20 USDT (شبكة TRON) ويستلم BTC على عنوان Bitcoin الخاص به. استبدل YOUR_KEY بمفتاح API الخاص بك.

الخطوة 1. اطلب عرض سعر

curl -sS -X POST 'https://snapex.pro/api/v1/partner/quotes' \
  -H 'X-API-Key: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "from_asset_id": "usdt",
    "to_asset_id": "btc",
    "side": "send",
    "amount": "20",
    "recipient_address": "bc1qexample"
  }'

تحتوي الاستجابة على quote_id (pq_…) والمبالغ. اعرض على العميل receive_amount — أي كمية BTC التي سيحصل عليها. لديك دقيقتان للخطوة التالية.

الخطوة 2. أنشئ التبادل

curl -sS -X POST 'https://snapex.pro/api/v1/partner/exchanges' \
  -H 'X-API-Key: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "quote_id": "pq_FROM_STEP_1",
    "recipient_address": "bc1qexample"
  }'

تتضمن الاستجابة الآن الكتلة deposit مع عنوان ومبلغ. اعرض على العميل deposit.address وdeposit.amount — يجب أن يحوّل هذا المبلغ بالضبط إلى هذا العنوان.

الخطوة 3. تابع الحالة

curl -sS 'https://snapex.pro/api/v1/partner/exchanges/pq_FROM_STEP_1' \
  -H 'X-API-Key: YOUR_KEY' \
  -H 'Accept: application/json'

كرّر الطلب مع فاصل 7–10 ثوانٍ. بمجرد أن يحوّل العميل الأموال، تتغير الحالة إلى processing، ثم إلى completed — أي تم إرسال الدفعة. الحالات النهائية: completed وerror وcancelled وexpired.

السيناريو نفسه بلغة Python

import time
import requests

API = "https://snapex.pro/api/v1/partner"
HEADERS = {
    "X-API-Key": "YOUR_KEY",
    "Content-Type": "application/json",
    "Accept": "application/json",
}

# Step 1. Quote: the client sends 20 USDT, receives BTC
quote = requests.post(f"{API}/quotes", headers=HEADERS, json={
    "from_asset_id": "usdt",
    "to_asset_id": "btc",
    "side": "send",
    "amount": "20",
    "recipient_address": "bc1qexample",
}).json()
print("Client receives:", quote["receive_amount"], quote["to_symbol"])

# Step 2. Create the exchange (within 2 minutes of the quote)
exchange = requests.post(f"{API}/exchanges", headers=HEADERS, json={
    "quote_id": quote["quote_id"],
    "recipient_address": "bc1qexample",
}).json()
deposit = exchange["deposit"]
print("Client must transfer:", deposit["amount"], deposit["asset"])
print("To address:", deposit["address"])

# Step 3. Poll the status until terminal
while True:
    time.sleep(10)  # at most 1 request every 7 seconds
    state = requests.get(
        f"{API}/exchanges/{quote['quote_id']}", headers=HEADERS
    ).json()
    print("Status:", state["status"])
    if state["status"] in ("completed", "error", "cancelled", "expired"):
        break

أخطاء شائعة لدى المبتدئين

• إرسال المبلغ كرقم بدلًا من نص. الصحيح: "amount": "20"، وليس "amount": 20.
• مع side=receive، تحديد المبلغ بأصل الإرسال. في receive يكون amount بأصل الاستلام (to).
• إنشاء التبادل بعد أكثر من دقيقتين من عرض السعر — ستحصل على 409 quote_expired. اطلب عرض السعر مباشرة قبل الإنشاء.
• إرسال الطلبات أكثر من مرة كل 7 ثوانٍ — ستحصل على 429. أضف فاصلًا زمنيًا بين الطلبات.