نماذج HTML

طريقة من طرق إضافة الدفع بالعملات المشفرة إلى موقع أو متجر إلكتروني أو بوت. يضغط المشتري زرًا، فتنفتح صفحة الدفع مع الفاتورة.

يُرسل النموذج عبر POST فقط إلى https://dash.bitsby.app/invoices/form ويحتوي على حقلين:

الحقل	ما يحمله
data	base64url لكائن JSON بحقول الفاتورة
signature	HMAC-SHA256 للسلسلة data، بطول 64 محرفًا ست عشريًا

يمكن أن يكون للمشروع في أي لحظة 50 فاتورة غير مدفوعة منشأة بهذه الطريقة كحد أقصى.

مثال على النموذج

<form method="post" action="https://dash.bitsby.app/invoices/form" target="_blank">
    <input type="hidden" name="data" value="eyJwcm9qZWN0SWQiOiJhMWIyYzNkNC01ZTZm...">
    <input type="hidden" name="signature" value="f77d6da1be35bd2900e0bfed9f202b04...">
    <button type="submit">Pay</button>
</form>

يملأ خادم المتجر القيمتين عند عرض الصفحة. ولا يظهر المفتاح السري في الترميز أبدًا.

السمة target="_blank" اختيارية: معها تبقى سلة المشتريات مفتوحة في التبويب الأصلي.

كيف تُبنى الحاوية

1. ابنِ كائن JSON بحقول الفاتورة.
2. رمّزه بترميز base64url. هذه هي السلسلة data.
3. احسب signature = HMAC-SHA256(data, formSecret).

تُوقَّع السلسلة data كاملة، لذلك لا يهم ترتيب مفاتيح JSON ولا الإزاحة ولا أسلوب تهريب Unicode. وتقبل جهة الاستقبال أيضًا base64 القياسي، مع الحشو أو من دونه.

لا تُعد بناء data بعد التوقيع: إذا تغيّر بايت واحد، وجب حساب التوقيع من جديد.

طريقة حساب التوقيع، مع أمثلة جاهزة بأربع لغات، يشرحها قسم توقيع نموذج HTML.

المفاتيح داخل data

المفتاح	إلزامي	ما يحمله
projectId	نعم	معرّف المشروع من الإعدادات في لوحة التحكم، uuid
amountFiat	نعم	المبلغ من 1 إلى 100,000، بمنزلتين عشريتين كحد أقصى. كسلسلة نصية "10.50" أو رقم 10.5
currencyFiat	نعم	العملة الورقية: USD أو EUR أو RUB
timeToPay	نعم	مهلة الدفع بالساعات: 0.5 و1 و3 و6 و12. كسلسلة نصية أو رقم
description	لا	الوصف للمشتري، حتى 1,000 حرف
serviceData	لا	معرّف الطلب في المتجر، حتى 1,000 حرف. لا يظهر للمشتري لكنه مرئي في كود مصدر النموذج — لا تضع فيه أي شيء حساس
output	لا	errors — اعرض تفاصيل أخطاء التحقق

يمكن إسقاط المفتاح الاختياري من JSON — وهذا يعادل سلسلة فارغة. وتذهب المفاتيح بأي ترتيب؛ وتتجاهل جهة الاستقبال المفاتيح المجهولة.

القيم سلاسل JSON نصية أو أرقام. القيم المنطقية والمصفوفات والكائنات المتداخلة لا تُعد قيم حقول وتصل كسلسلة فارغة.

مثال على محتوى data:

{
    "projectId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "amountFiat": 10.5,
    "currencyFiat": "USD",
    "timeToPay": 1,
    "description": "Order #7, delivery",
    "serviceData": "order-7"
}

هنا يُمرَّر المبلغ ومهلة الدفع كأرقام؛ وتُقبل السلاسل النصية أيضًا. والمفتاح الاختياري output غير محدد إطلاقًا.

صيغة المبلغ

أرقام ونقطة عشرية فقط، وبمنزلتين عشريتين كحد أقصى: 10 و10.00 و1000.50. وتُقص المسافات المحيطة.

أي صيغة أخرى مرفوضة — فواصل الآلاف، أو فاصلة بدل النقطة، أو الترميز الأسي، أو إشارة قبل الرقم، أو رمز عملة. ولا تقريب: المنزلة العشرية الثالثة لا تُقص، بل تسبب رفضًا.

المفتاح السري للنموذج

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

يجب أن يبقى المفتاح السري على خادم المتجر. فإذا انتهى به المطاف في HTML واجهة المتجر، فقد التوقيع معناه.

المفتاح السري للنموذج والمفتاح السري للـ Webhook مفتاحان مختلفان؛ فلا تخلط بينهما.

معرّف الطلب

املأ serviceData دائمًا: ضع فيه معرّف الطلب من متجرك. تعود القيمة في إشعار الدفع — ويستخدمها المتجر للعثور على الطلب.

امتلاء serviceData يحمي من التكرارات. إعادة إرسال النموذج أو النقر المزدوج على الزر لا ينشئ فاتورة ثانية: تُرسل الخدمة المشتري إلى الفاتورة غير المدفوعة الموجودة. وتجري المطابقة على حقول الطلب — المشروع والمبلغ والعملة والوصف وserviceData — لا على بايتات data.

يجب أن تكون القيمة فريدة لكل طلب. فمع القيمة نفسها يصل مشترٍ ثانٍ إلى فاتورة المشتري الأول غير المدفوعة.

أما serviceData الفارغ فيزيل هذه الحماية: لا شيء يُعرف به التكرار، وكل إرسال ينشئ فاتورة جديدة. تستهلك التكرارات حد الخمسين فاتورة غير مدفوعة، وعندما تُدفع إحداها، لا يجد المتجر ما يربط به الدفعة بطلب.

الأخطاء ووضع التصحيح

يمر النموذج بفحصين: أولًا التوقيع والحاوية، ثم قيم الحقول.

ما حدث	ما تعرضه الخدمة
التوقيع لا يتطابق، أو الحاوية غير قابلة للقراءة، أو المشروع لغيرك أو غير موجود	خطأ عام من دون ذكر السبب
التوقيع متطابق لكن أحد الحقول معبأ بشكل خاطئ	خطأ عام. ومع "output":"errors" — أخطاء مفصلة
اجتاز النموذج الفحصين	صفحة الدفع مع الفاتورة

الفحص الأول لا يكشف السبب أبدًا، بأي إعدادات.

الزوج "output":"errors" في JSON يفعّل التفاصيل للفحص الثاني: تسمّي الخدمة الحقل، وتسرد القيم المسموحة، وتبلّغ عند بلوغ سقف الخمسين فاتورة غير مدفوعة. يقيم المفتاح داخل الحاوية الموقَّعة، فلا يمكن حقنه من الخارج.

أثناء إعداد النموذج ضع "output":"errors" في JSON؛ وبعد اكتمال الإعداد أزل المفتاح وأعد بناء الحاوية.

إذا كان التوقيع نفسه لا يتطابق، فقارن data والتوقيع لديك بالمجموعة المرجعية في توقيع نموذج HTML.

ما التالي

تُعالج الفاتورة المنشأة بالنموذج بالطريقة نفسها التي تُعالج بها فاتورة من API أو من لوحة التحكم:

• تأكيد الدفع يصل إلى Webhook URL. تحقق من توقيع الإشعار بالمفتاح السري للـ Webhook وسلّم الطلبات بناءً عليه وحده.
• إعادة المشتري إلى موقعك تُضبط عبر رابط النجاح (Successful URL) ورابط الإخفاق (Unsuccessful URL) — انظر قسم «إعادة المشتري إلى موقع المتجر» على صفحة دورة حياة الفاتورة. الوصول إلى هذين الرابطين لا يؤكد الدفع.
• حالات الفاتورة ونافذة البحث عن الدفعات يصفها قسم دورة حياة الفاتورة.
• حوّل المشتري مبلغًا خاطئًا — انظر ربط الدفعات واختلاف المبالغ.