المصطلحات والمصطلحات الميدانية
التعريفات الأساسية المستخدمة عبر وثائق API.
طلب الرؤوس
| رأس | مطلوب | التعريف |
|---|
| x-api-key | نعم | مفتاح API الصادر في التطبيق (قسم "الأعمال"). يتم حل المنظمة من مضيف الطلب |
| Content-Type | نعم (POST) | application/json لإنشاء الطلبات |
المبلغ والعملة
| مصطلح | التعريف |
|---|
| amount | سلسلة من عدد صحيح بوحدات ثانوية (على سبيل المثال، سنت، أصغر جزء رمزي) |
| amount_with_fee | المبلغ بالإضافة إلى الرسوم المطبقة (الوحدات الثانوية) |
| currency | رمز العملة / الرمز المميز المشابه لـ ISO (على سبيل المثال، USDT) |
| currency_dest | العملة الوجهة للتحويل (FX). خياري؛ الإعدادات الافتراضية إلى currency |
المعرفات
| مصطلح | التعريف |
|---|
| id | النظام الداخلي UUID للمعاملة |
| txid | سلسلة يقدمها العميل تحدد عملية تجارية واحدة؛ UUID هو اختيار مناسب، وليس تنسيقًا مطلوبًا |
التوجيه
| مصطلح | التعريف |
|---|
| route | تم تكوين الاسم المستعار لمسار المعالجة لمفتاح API |
| env | prod (افتراضي). الحفاظ على هذه القيمة عند فتح الطلب وتأكيده. |
دورة حياة الحالة
| الحالة | معنى |
|---|
| created | تم قبوله، في انتظار المعالجة |
| new | الحالة الأولية قبل بدء المعالجة |
| authorizing | التفويض قيد التقدم |
| pre_authorized_3ds | في انتظار مصادقة 3DS |
| action_required | في انتظار إجراء إضافي (3DS/ترخيص إضافي) |
| charging | قيد التنفيذ (تفويض / تمويل) |
| payment_suspended | المعاملة الواردة معلقة مؤقتا |
| payout_suspended | المعاملة الصادرة معلقة مؤقتا |
| charged | تم الانتهاء بنجاح (المحطة) |
| reversed | عكس الشحن (المحطة الطرفية) |
| refunded | ردها (المحطة) |
| rejected | فشل لا رجعة فيه (المحطة) |
| failed | فشل (المحطة) |
الحالات الطرفية هي charged، reversed، refunded، rejected، failed. المسار السعيد الأكثر شيوعًا هو created → charging → charged.
حقول الوقت
| المجال | التعريف |
|---|
| started | الطابع الزمني ISO عند بدء المعالجة |
| finished | الطابع الزمني ISO عند اكتمال المعالجة؛ تحديد النتيجة من الحالة |
كائنات تخزين الأموال
| المجال | التعريف |
|---|
| network | شبكة Blockchain (ETH، TRX، إلخ) |
| type | نوع الأداة (bank_card، p2p_proxy، إلخ) |
| wallet_id | معرف المحفظة الداخلية (هدف الدفع/الدفع) |
| cardnumber | البطاقة الافتراضية PAN (ملثمة في بعض الردود) |
| cvv | رمز أمان البطاقة الافتراضية (لا تقم مطلقًا بتسجيل الدخول بنص عادي) |
| exp_month / exp_year | قيم انتهاء البطاقة (سلسلة، صفر مبطن) |
| cardholder | اسم حامل البطاقة (ASCII أو UTF-8) |
حقول الخطأ
| المجال | التعريف |
|---|
| error_description | سبب فشل يمكن قراءته بواسطة الإنسان (نص غير مستقر) |
إرشادات العجز الجنسي
استخدم txid فريدًا (لمنع تكرار الأثر) لكل عملية تجارية واستمر في ذلك قبل الإرسال. القيمة عبارة عن سلسلة؛ يعد إنشاء UUID مناسبًا ولكن بناء جملة UUID غير مطلوب. أعد محاولة نفس التعليمات بنفس المعرف في نفس الحساب. لا تعيد استخدامه لمستلم أو مبلغ مختلف. استعادة العملية الأصلية بعد انتهاء المهلة؛ يجب ألا تصبح إعادة المحاولة دفعة جديدة بصمت.
استراتيجية الاقتراع
تتم قراءة الاستطلاع مع التراجع المحدود، على سبيل المثال 1s → 2s → 4s → 8s، مع ميزانية تفاعل تبلغ 30 ثانية. توقف عند حالة نهائية معروفة أو عند انتهاء الميزانية. عند انتهاء المهلة، قم بالإبلاغ عن نتيجة معلقة/غير معروفة واحتفظ بـ id/txid الأصلي. الحالات غير المعروفة ليست ناجحة. راجع الأخطاء وإعادة المحاولة.
خطافات الويب (إعلامية)
تشير خطافات الويب إلى تغيير الحالة ولكنها ليست موثوقة. قم دائمًا بالتأكيد عبر معاملة GET.
مقياس المبالغ
الكميات هي سلاسل من الأعداد الصحيحة بوحدات صغيرة، وليست قيم الفاصلة العائمة. احصل على الكسور العشرية للعملة والشبكة من GET https://app.heth.me/api/v1/contracts?env=prod. يستخدم USDT/ETH وUSDT/TRX حاليًا الكسور العشرية 6: 1 USDT = "1000000"، 0.25 USDT = "250000". يحتوي ETH على أرقام عشرية 18؛ هذا لا ينطبق على كل رمز مميز على Ethereum. يجب أن يوقف المقياس غير المعروف تحويل المبلغ. راجع مخطط API.