يتطلّب عضوية سيلفر أو أعلى — للتقديم ولكل استدعاء موثَّق. إن انقضت عضوية مالك المفتاح، يُجمَّد المشروع حتى يُجدِّد اشتراكه.
/v1.
الحصول على الوصول
الوصول يُمنَح لكل مشروع على حدة. تحتاج الأربعة جميعاً:1
عضوية نشطة، سيلفر أو أعلى
تُفحَص عند كل استدعاء، لا عند الموافقة فقط.
2
طلب مطوّر تمت الموافقة عليه
يُقدَّم من صفحة Vito API في لوحة التحكم، ويراجعه فريق فيتوكس يدوياً.
3
الموافقة على شروط مطوّري API
تُقَرّ عند تقديم الطلب.
4
النطاقات التي يحتاجها مشروعك
يمنحها طاقم فيتوكس بناءً على ما وصفته.
النطاقات
المصادقة
أرسل مفتاحك السرّي كرمز Bearer:- قائمة عناوين IP المسموح بها — حصر الاستدعاءات بعناوين خوادم بعينها
- حدود المعدّل — سقوف لكل مشروع تتوسّع مع مستوى عضوية المالك
المفاتيح: التدوير والتخزين
- احتفظ به على الخادم فقط — من يملكه يستطيع الخصم من مستخدميك
- دوّره من تبويب مفاتيح API. يظل المفتاح السابق يعمل 24 ساعة كفترة سماح كي تنشر التحديث دون انقطاع
- سرّ توقيع الـ webhook يُدوَّر بشكل منفصل، وله فترة تداخل 24 ساعة خاصة به
- إن تسرّب المفتاح، دوّره فوراً
الخصم من مستخدم
1
تطبيقك يستدعي POST /v1/deduct
مع المستخدم، والمبلغ، و
guildId الذي انطلقت منه العملية، وتفاصيل المنتج.2
Vito يُعيد confirmUrl
طلب تأكيد معلّق، صالح 10 دقائق. تُرسَل للمستخدم رسالة خاصة أيضاً.
3
المستخدم يوافق برمز PIN
على
vetox.io.4
Vito يسوّي العملية ويُخطِر
يُخصَم الرصيد، وتُسجَّل المعاملة، ويُرسَل webhook موقَّع إن كنت قد ضبطت واحداً.
5
تطبيقك يتحقّق ويُكمِل
تحقّق من التوقيع، ثم افتح المحتوى أو سلّم المنتج.
مُعامِلات الطلب — /v1/deduct
إضافة رصيد لمستخدم
POST /v1/add يضيف Vito لمستخدم من رصيدك أنت — للمكافآت أو الاستردادات. نفس حقول /deduct عدا guildId وproduct.
على عكس الخصم، الإضافة بلا خطوة تأكيد — تُسوّى فوراً. تتطلّب النطاق
credit:create ورصيداً كافياً، وإلا أعاد الاستدعاء 402 VITO_INSUFFICIENT_OWNER_FUNDS.الرسوم
كل عملية خصم تُسوّى لصالحك بعد خصم رسوم المنصّة — بنفس جدول تحويلات Vito داخل التطبيق، وبحسب مستوى عضويتك أنت:المبالغ 5 Vito أو أقل بلا رسوم، والإضافات عبر
/v1/add بلا رسوم دائماً.Webhooks
أضف رابط استدعاء واحداً أو أكثر بصيغةhttps من تبويب الإعدادات. يرسل Vito طلب POST موقَّعاً كلما وصل طلب تأكيد إلى حالة نهائية.
التحقّق من التوقيع
كل عملية تسليم تحمل ترويسةX-Vito-Signature:
X-Vito-Event-Id مفتاحاً لمنع التكرار، فإعادة المحاولة تُرسل المعرّف نفسه:
أعِد حساب HMAC على
<ts>:<rawBody> بسرّ التوقيع الخاص بك، وقارِن بزمن ثابت.
الأحداث
خمسة أنواع من الأحداث، تشترك كلها في شكل حمولة واحد. الحقلdata.status يحمل النتيجة.
تُعاد محاولة الـ webhooks 5 مرات مع تباعد تصاعدي. ردّ بـ 2xx بسرعة ونفّذ التسليم لديك بشكل غير متزامن.
رموز الأخطاء
كل رد مُغلَّف. النجاح يحملdata، والفشل يحمل error، ولا يجتمعان أبداً:
حدود المعدّل
يوجد أيضاً حد لكل عنوان IP يساوي نصف حصّتك في الدقيقة، بحد أدنى 30.
أرسل ترويسة
Idempotency-Key لمنع تكرار إعادات المحاولة بأمان.نقاط النهاية
الحدود
- تنتهي صلاحية طلبات التأكيد بعد 10 دقائق — عامِل غير المؤكَّد منها كأنه مهجور
amountيجب أن يكون عدداً صحيحاً موجباًmetadataمحدودة بـ 10 مفاتيح- سقوف المعاملة الواحدة والحجم اليومي يضبطها طاقم فيتوكس، وتظهر للقراءة فقط في تبويب الإعدادات
قائمة الأمان
أبقِ الأسرار على الخادم
أبقِ الأسرار على الخادم
مفتاح API وسرّ التوقيع لا مكان لهما في كود العميل إطلاقاً. دوّر أيّاً منهما فوراً إن تسرّب.
تحقّق من كل webhook
تحقّق من كل webhook
افحص التوقيع مقابل الجسم الخام، وارفض ما مضى عليه أكثر من ~5 دقائق.
سوِّ عند completed فقط
سوِّ عند completed فقط
لا تسلّم أبداً بناءً على رد
/deduct — الخصم ليس نهائياً حتى confirmation.completed.أقل صلاحية ممكنة
أقل صلاحية ممكنة
اطلب النطاقات التي تستخدمها فعلاً فقط، وفعّل قائمة عناوين IP المسموح بها.
استكشاف الأخطاء
كل استدعاء يُعيد خطأ عدم التصريح
كل استدعاء يُعيد خطأ عدم التصريح
انقضت عضوية مالك المفتاح. تُفحَص عند كل استدعاء، لا عند الإصدار فقط.
فقدتُ مفتاحي
فقدتُ مفتاحي
لا يمكن استعادته — لا يُخزَّن إلا تجزئته. دوّره للحصول على واحد جديد.
توقيعات webhook تفشل بعد التدوير
توقيعات webhook تفشل بعد التدوير
اقبل السرَّين خلال فترة التداخل البالغة 24 ساعة.
خصم لا يكتمل أبداً
خصم لا يكتمل أبداً
المستخدم لم يوافق عليه. تنتهي طلبات التأكيد بعد 10 دقائق.
لا تصل أي webhooks
لا تصل أي webhooks
المشروع يحتاج رابط استدعاء وسرّ توقيع معاً. بواحد منهما فقط لا يُسلَّم شيء.
وصل Vito أقل مما خصمت
وصل Vito أقل مما خصمت
هذه رسوم التسوية. استخدم مبالغ 5 Vito أو أقل لتجنّبها، أو احسبها ضمن تسعيرك.
402 VITO_INSUFFICIENT_OWNER_FUNDS
402 VITO_INSUFFICIENT_OWNER_FUNDS
/v1/add يُموَّل من رصيدك أنت، ولا يُنشأ من العدم. اشحن رصيدك.Vito
الأرصدة، ورمز PIN، والرسوم.
طلبات الدفع
ما يراه المستخدم عندما تخصم منه.