التجار

استخدم نقاط نهاية الفواتير لشحن عملائك بأي رمز مدعوم واستلام رمز مختلف في محفظتك الخاصة. يتولى p3p التوجيه عبر السلاسل.

كيف يعمل

1

سجل كشريكاحصل على معرّف الشريك من لوحة التحكم

2

أنشئ فاتورةPOST /invoice/create

3

يدفع العميلإلى `deposit_address`

4

تستلم الأموالتسوية مباشرة إلى محفظتك

لا يحتفظ p3p أبداً بأموالك لأكثر من بضع ثوانٍ لازمة لتوجيه المبادلة. الاستردادات، عند الاقتضاء، تذهب إلى مرسل الإيداع تلقائياً.

1. كن تاجراً

سجّل في لوحة تحكم الشريك باستخدام محفظة تتحكم بها. استخدم معرّف الشريك المعيّن لك كـ opts.partner_id (في /exchange/create) أو كـ wallet_merchant (في /invoice/create) لإسناد المعاملات إلى حسابك.

لا يوجد نموذج تسجيل، ولا تأكيد بريد إلكتروني، ولا رمز API. المحفظة هي بيانات الاعتماد.

تعامل مع محفظة التاجر كمفتاح API

من يتحكم بالمحفظة يتحكم بحساب التاجر. استخدم محفظة مخصصة لعملك، منفصلة عن الأموال الشخصية.

2. إنشاء فاتورة

طريقتان للقيام بذلك.

برمجياً (موصى به)

POST /invoice/create

const invoice = await fetch("https://api.p3p.xyz/invoice/create", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    chain_from: "eth",  token_from: "usdt", amount_from: "50",
    chain_to:   "ton",  token_to:   "usdt",
    wallet_merchant: "UQYourMerchantTonWallet"
  }),
}).then(r => r.json())

console.log(invoice.deposit_address) // اعرضه لعميلك

الاستجابة:

{
  "id": "in_ab12cd...",
  "invoice": true,
  "chain_from": "eth",  "token_from": "usdt", "amount_from": "50",
  "chain_to":   "ton",  "token_to":   "usdt",
  "amount_to":  "50.0",
  "wallet_merchant": "UQYourMerchantTonWallet",
  "deposit_address": "0xDepositAddressForCustomer",
  "rate":     "1.0",
  "duration": 60
}

رابط URL قابل للمشاركة (لا حاجة لتكامل)

لزر دفع أو رمز QR أو رابط مشاركة، يمكنك بناء الفاتورة من رابط URL:

https://api.p3p.xyz/invoice/create/:merchantId/:pathFrom/:pathTo?

أمثلة:

# يدفع العميل 100 USDT على TON، تستلم USDT على TON
https://api.p3p.xyz/invoice/create/0xYourMerchantWallet/100:usdt.ton/usdt.ton

# يدفع العميل 50 TON، تستلم USDT على TON
https://api.p3p.xyz/invoice/create/acme/50:ton.ton/usdt.ton

# نموذج بسيط: ادفع واستلم نفس الأصل
https://api.p3p.xyz/invoice/create/acme/100:usdt.ton

:merchantId قد يكون:

• معرف الشريك المُعاد أثناء التسجيل،
• اسم الشريك name إذا قمت بتعيينه، أو
• عنوان محفظة مسجل بالفعل كتاجر.

3. عرض عنوان الإيداع

اعرض invoice.deposit_address و invoice.amount_from في واجهتك، ويفضل كرمز QR:

import QRCode from "qrcode"

const dataUrl = await QRCode.toDataURL(
  `${invoice.chain_from}:${invoice.deposit_address}?amount=${invoice.amount_from}`
)

يرسل العميل amount_from من token_from إلى ذلك العنوان. أي شيء آخر (كمية خاطئة، رمز خاطئ، نافذة منتهية) يتم استرداده تلقائياً.

4. تأكيد الدفع

استعلم /check/:id تماماً كتبادل عادي:

async function waitForInvoicePayment(id: string) {
  while (true) {
    const s = await fetch(`https://api.p3p.xyz/check/${id}`).then(r => r.json())
    if (s.status === "complete") return s
    if (s.status === "failed" || s.status === "refunded") throw new Error(s.status)
    await new Promise(r => setTimeout(r, 4000))
  }
}

await waitForInvoicePayment(invoice.id)
// الأموال الآن في wallet_merchant

5. فحص أرباحك

ثلاث نقاط نهاية للشريك هي للقراءة فقط ولا تتطلب أي مصادقة بخلاف معرفة partnerId. تتم تسوية الأرباح وفقًا لإعدادات الدفع التي قمت بتكوينها (إما فوراً لكل مبادلة أو عبر سحوبات USDT مجدولة) — قم بتكوين ذلك في لوحة تحكم الشريك.

نقطة النهاية	تعيد
GET /partners/:partnerId/stats	الحجم، عدد المعاملات، حصة الإيرادات
GET /partners/:partnerId/exchanges	جميع التبادلات المنسوبة لهذا الشريك
GET /partners/:partnerId/invoices	جميع الفواتير المنشأة لهذا الشريك

curl https://api.p3p.xyz/partners/0xYourMerchantWallet/stats

نصائح وتحذيرات

• محفظة واحدة لكل سلسلة: يتراكم لدى الشريك محافظ، واحدة لكل سلسلة. استخدم المحفظة الصحيحة لسلسلة الوجهة في wallet_merchant.
• نفس السلسلة + نفس الرمز: يتخطى محرك المبادلة ويعمل كعنوان توجيه بسيط — مفيد لروابط "ادفع لي X USDT على TON" البسيطة.
• نافذة الإيداع: تشارك الفواتير نافذة الـ ~6 دقائق القياسية. إذا استغرق العميل وقتاً أطول، استدع /check/:id?bump=true لتحديثها.
• الاستردادات: متاحة فقط عندما يتم اكتشاف الإيداع لكن تفشل المبادلة. للفواتير بدون wallet_refund، تحاول الأموال الاسترداد إلى عنوان المرسل المكتشف على السلسلة.

---

مرجع نقاط النهاية

جميع نقاط نهاية التاجر مفتوحة — لا حاجة لرأس api-key. محفظتك هي بيانات الاعتماد.

1. إنشاء فاتورة2. إنشاء رابط فاتورة قابل للمشاركة3. الحصول على إحصائيات الشريك4. الحصول على تبادلات الشريك5. الحصول على فواتير الشريك

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

POST /invoice/create

الحقل	النوع	مطلوب	الوصف
chain_from	string	نعم	السلسلة التي يدفع منها العميل
token_from	string	نعم	الرمز الذي يدفع به العميل
amount_from	string	نعم	المبلغ الذي يدفعه العميل
chain_to	string	نعم	السلسلة التي تستلم عليها الأموال
token_to	string	نعم	الرمز الذي تستلمه
wallet_merchant	string	نعم	محفظتك على سلسلة الوجهة

يعيد كائن فاتورة يتضمن id و deposit_address و amount_from و amount_to و rate و duration.

2. إنشاء رابط فاتورة قابل للمشاركة

GET /invoice/create/:merchantId/:pathFrom/:pathTo?

رابط فاتورة قابل للمشاركة — ضعه في رمز QR أو زر.

• merchantId — معرف الشريك، اسم الشريك، أو محفظة مسجلة بالفعل كتاجر
• pathFrom — <amount>:<token>.<chain> (مثلاً 100:usdt.ton)
• pathTo — اختياري، <token>.<chain> إذا أردت التحويل؛ الافتراضي هو pathFrom

يعيد نفس الكائن مثل POST /invoice/create.

3. الحصول على إحصائيات الشريك

GET /partners/:partnerId/stats

الحجم المجمع، عدد المعاملات وحصة الإيرادات مدى الحياة لمحفظة الشريك.

4. الحصول على تبادلات الشريك

GET /partners/:partnerId/exchanges

قائمة مقسمة على صفحات بالتبادلات المنسوبة للشريك.

5. الحصول على فواتير الشريك

GET /partners/:partnerId/invoices

قائمة مقسمة على صفحات بالفواتير المنشأة للشريك.

الأخطاء

{ "error": "merchant_id_required", "message": "..." }

الرمز	المعنى
invalid_json	جسم الطلب ليس JSON صالحاً
merchant_id_required	استدعاء نقطة نهاية GET الفاتورة بدون معرف تاجر
partner_not_found	لا يوجد شريك يطابق merchantId المُعطى
merchant_wallet_not_found	الشريك موجود لكن ليس لديه محفظة على سلسلة الوجهة
amount_too_small	المبلغ أقل من الحد الأدنى للمزود
amount_too_big	المبلغ أكبر من الحد الأقصى للمزود