Skip to main content
يتطلّب عضوية سيلفر أو أعلى — للتقديم ولكل استدعاء موثَّق. إن انقضت عضوية مالك المفتاح، يُجمَّد المشروع حتى يُجدِّد اشتراكه.
واجهة REST تتيح لتطبيقك التعامل مع رصيد Vito الخاص بالمستخدم من داخل ديسكورد — قراءته، أو الخصم منه، أو الإضافة إليه، أو تحريكه بين المستخدمين. كل نقاط النهاية تُعيد JSON وتقع تحت الإصدار /v1.
Vito لا ينتقل من أو إلى أموال حقيقية أبداً. هو يتحرّك بين أرصدة فيتوكس فقط.

الحصول على الوصول

الوصول يُمنَح لكل مشروع على حدة. تحتاج الأربعة جميعاً:
1

عضوية نشطة، سيلفر أو أعلى

تُفحَص عند كل استدعاء، لا عند الموافقة فقط.
2

طلب مطوّر تمت الموافقة عليه

يُقدَّم من صفحة Vito API في لوحة التحكم، ويراجعه فريق فيتوكس يدوياً.
3

الموافقة على شروط مطوّري API

تُقَرّ عند تقديم الطلب.
4

النطاقات التي يحتاجها مشروعك

يمنحها طاقم فيتوكس بناءً على ما وصفته.
كن محدَّداً في وصف ما تبنيه وكيف ستخزّن المفتاح. الطلبات المبهمة هي التي تُرفَض.

النطاقات

المصادقة

أرسل مفتاحك السرّي كرمز Bearer:
طبقتان اختياريتان تزيدان تحصين المشروع:
  • قائمة عناوين IP المسموح بها — حصر الاستدعاءات بعناوين خوادم بعينها
  • حدود المعدّل — سقوف لكل مشروع تتوسّع مع مستوى عضوية المالك

المفاتيح: التدوير والتخزين

يُكشَف المفتاح وسرّ التوقيع مرة واحدة فقط. بعد الموافقة لديك نافذة 7 أيام لكشفهما من تبويب مفاتيح API. لا يحتفظ فيتوكس إلا بتجزئة ولا يمكنه عرضهما مجدداً — إن فاتتك النافذة فعليك التدوير للحصول على مفتاح جديد.
  • احتفظ به على الخادم فقط — من يملكه يستطيع الخصم من مستخدميك
  • دوّره من تبويب مفاتيح API. يظل المفتاح السابق يعمل 24 ساعة كفترة سماح كي تنشر التحديث دون انقطاع
  • سرّ توقيع الـ webhook يُدوَّر بشكل منفصل، وله فترة تداخل 24 ساعة خاصة به
  • إن تسرّب المفتاح، دوّره فوراً

الخصم من مستخدم

مفتاحك وحده لا يستطيع تحريك Vito الخاص بمستخدم. كل عملية خصم تتطلّب موافقة المستخدم برمز PIN الخاص بمحفظته، على vetox.io — لا داخل تطبيقك ولا داخل ديسكورد.
1

تطبيقك يستدعي POST /v1/deduct

مع المستخدم، والمبلغ، وguildId الذي انطلقت منه العملية، وتفاصيل المنتج.
2

Vito يُعيد confirmUrl

طلب تأكيد معلّق، صالح 10 دقائق. تُرسَل للمستخدم رسالة خاصة أيضاً.
3

المستخدم يوافق برمز PIN

على vetox.io.
4

Vito يسوّي العملية ويُخطِر

يُخصَم الرصيد، وتُسجَّل المعاملة، ويُرسَل webhook موقَّع إن كنت قد ضبطت واحداً.
5

تطبيقك يتحقّق ويُكمِل

تحقّق من التوقيع، ثم افتح المحتوى أو سلّم المنتج.
أكمِل عمليتك عند confirmation.completed فقط — لا عند رد /deduct. الخصم لا يكون نهائياً عند تلك النقطة.

مُعامِلات الطلب — /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 موقَّعاً كلما وصل طلب تأكيد إلى حالة نهائية.
لا تُرسَل الـ webhooks إلا إذا كان لمشروعك رابط استدعاء وسرّ توقيع معاً. اكشف السرّ (whsec_…) مرة واحدة من تبويب مفاتيح API.

التحقّق من التوقيع

كل عملية تسليم تحمل ترويسة X-Vito-Signature:
وترافقها ترويستان إضافيتان — استخدم X-Vito-Event-Id مفتاحاً لمنع التكرار، فإعادة المحاولة تُرسل المعرّف نفسه:
أثناء تدوير سرّ التوقيع تحمل الترويسة أكثر من توقيع واحد، الأحدث أولاً:
اقبل التسليم إذا طابق أي h1. المُتحقِّق الذي يقرأ الأول فقط سيرفض كل webhook إلى أن ينشر السرّ الجديد — وهو ما يُبطل الغرض من فترة التداخل البالغة 24 ساعة.
أعِد حساب HMAC على <ts>:<rawBody> بسرّ التوقيع الخاص بك، وقارِن بزمن ثابت.
تحقّق من الجسم الخام للطلب، قبل أي تحليل JSON أو وسيط يعيد صياغته.

الأحداث

خمسة أنواع من الأحداث، تشترك كلها في شكل حمولة واحد. الحقل data.status يحمل النتيجة.
تُعاد محاولة الـ webhooks 5 مرات مع تباعد تصاعدي. ردّ بـ 2xx بسرعة ونفّذ التسليم لديك بشكل غير متزامن.

رموز الأخطاء

كل رد مُغلَّف. النجاح يحمل data، والفشل يحمل error، ولا يجتمعان أبداً:
كل رمز مسبوق بـ VITO_. اعتمد على النص الكامل في شروطك — لن يظهر RATE_LIMITED أو FORBIDDEN مجرّداً في أي رد.

حدود المعدّل

يوجد أيضاً حد لكل عنوان IP يساوي نصف حصّتك في الدقيقة، بحد أدنى 30.
تحت الحمل الكثيف تفشل نقاط نهاية الكتابة بشكل مغلق — يُرفَض الخصم بدل المخاطرة بإنفاق مزدوج، بينما تفشل نقاط نهاية القراءة بشكل مفتوح. عامِل الكتابة المرفوضة على أنها “لم تحدث” وأعد المحاولة.
أرسل ترويسة Idempotency-Key لمنع تكرار إعادات المحاولة بأمان.

نقاط النهاية

الحدود

  • تنتهي صلاحية طلبات التأكيد بعد 10 دقائق — عامِل غير المؤكَّد منها كأنه مهجور
  • amount يجب أن يكون عدداً صحيحاً موجباً
  • metadata محدودة بـ 10 مفاتيح
  • سقوف المعاملة الواحدة والحجم اليومي يضبطها طاقم فيتوكس، وتظهر للقراءة فقط في تبويب الإعدادات

قائمة الأمان

مفتاح API وسرّ التوقيع لا مكان لهما في كود العميل إطلاقاً. دوّر أيّاً منهما فوراً إن تسرّب.
افحص التوقيع مقابل الجسم الخام، وارفض ما مضى عليه أكثر من ~5 دقائق.
لا تسلّم أبداً بناءً على رد /deduct — الخصم ليس نهائياً حتى confirmation.completed.
اطلب النطاقات التي تستخدمها فعلاً فقط، وفعّل قائمة عناوين IP المسموح بها.

استكشاف الأخطاء

انقضت عضوية مالك المفتاح. تُفحَص عند كل استدعاء، لا عند الإصدار فقط.
لا يمكن استعادته — لا يُخزَّن إلا تجزئته. دوّره للحصول على واحد جديد.
اقبل السرَّين خلال فترة التداخل البالغة 24 ساعة.
المستخدم لم يوافق عليه. تنتهي طلبات التأكيد بعد 10 دقائق.
المشروع يحتاج رابط استدعاء وسرّ توقيع معاً. بواحد منهما فقط لا يُسلَّم شيء.
هذه رسوم التسوية. استخدم مبالغ 5 Vito أو أقل لتجنّبها، أو احسبها ضمن تسعيرك.
/v1/add يُموَّل من رصيدك أنت، ولا يُنشأ من العدم. اشحن رصيدك.

Vito

الأرصدة، ورمز PIN، والرسوم.

طلبات الدفع

ما يراه المستخدم عندما تخصم منه.