Vito API والمشتريات

يتطلّب عضوية سيلفر أو أعلى — للتقديم ولكل استدعاء موثَّق. إن انقضت عضوية مالك المفتاح، يُجمَّد المشروع حتى يُجدِّد اشتراكه.

واجهة REST تتيح لتطبيقك التعامل مع رصيد Vito الخاص بالمستخدم من داخل ديسكورد — قراءته، أو الخصم منه، أو الإضافة إليه، أو تحريكه بين المستخدمين. كل نقاط النهاية تُعيد JSON وتقع تحت الإصدار /v1.

Vito لا ينتقل من أو إلى أموال حقيقية أبداً. هو يتحرّك بين أرصدة فيتوكس فقط.

كل نقاط النهاية تقع تحت https://api.vetox.io/public/vito.المسارات المكتوبة في هذه الصفحة — مثل /v1/deduct و/v1/balance/:discordId — نسبية إلى هذه البادئة، وهي ما تضيفه مكتبة SDK نيابةً عنك. وعند استدعائها بنفسك استخدم الرابط الكامل:

https://api.vetox.io/public/vito/v1/deduct

أما https://api.vetox.io/v1/deduct فليس مساراً موجوداً ويعيد 404.

تبني بـ Node.js؟ لا تستدعِ REST يدوياً — استخدم الحزمة الرسمية @vetox-bot/vito. تغطي نقاط النهاية التسع كلها والتحقّق من الـ webhooks، وتتولّى عنك منع التكرار وإعادة المحاولة. انظر قسم SDK الرسمي لـ Node.js أدناه.

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

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

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

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

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

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

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

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

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

يمنحها طاقم فيتوكس بناءً على ما وصفته.

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

النطاقات

النطاق	يمنح
`balance:read`	قراءة رصيد Vito الخاص بمستخدم
`deduct:create`	الخصم من رصيد مستخدم
`credit:create`	إضافة Vito لمستخدم، مموَّلة من رصيدك أنت
`transfer:create`	تحريك Vito بين مستخدمَين
`transactions:read`	عرض وقراءة معاملات مشروعك

المصادقة

أرسل مفتاحك السرّي كرمز Bearer:

Authorization: Bearer vito_live_xxxxxxxxxxxxxxxx

طبقتان اختياريتان تزيدان تحصين المشروع:

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

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

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

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

SDK الرسمي لـ Node.js

الحزمة الرسمية @vetox-bot/vito تغلّف نقاط النهاية التسع كلها إضافةً إلى التحقّق من الـ webhooks. تتولّى عنك ترويسة Idempotency-Key، وإعادة المحاولة بتباعد تصاعدي، والمهل الزمنية، وتصنيف الأخطاء إلى أصناف مكتوبة النوع.

التثبيت

npm install @vetox-bot/vito

يتطلّب Node.js 20 أو أحدث. الحزمة بلا أي اعتماديات وقت تشغيل — تستخدم fetch وnode:crypto المدمجَين — وتُشحَن بصيغتَي ESM وCommonJS معاً مع تعريفات TypeScript كاملة.

التهيئة

import { VitoClient } from '@vetox-bot/vito';

const vito = new VitoClient({ apiKey: process.env.VITO_API_KEY });

إن لم تمرّر apiKey فستقرأه الحزمة من متغيّر البيئة VITO_API_KEY. يُتحقَّق من صيغة المفتاح عند الإنشاء، فالمفتاح المشوَّه يفشل فوراً بدل أن يكلّفك رحلة شبكة و401.

المفتاح يحرّك أموالاً — أبقِه على الخادم دائماً، ولا تضعه في حزمة عميل أو متصفّح. console.log(vito) يطبع [redacted] بدل المفتاح، وترفض الحزمة أي baseUrl بصيغة http:// لمضيف غير محلي حتى لا يمرّ المفتاح بنص صريح.

خيارات العميل

الخيار	الافتراضي	ماذا يفعل
`apiKey`	`process.env.VITO_API_KEY`	مفتاح المشروع (`vito_live_…`)
`baseUrl`	`https://api.vetox.io`	جذر الـ API
`timeoutMs`	`15000`	مهلة كل طلب
`maxRetries`	`2`	عدد إعادات المحاولة للأعطال العابرة
`retryBaseDelayMs`	`500`	أول تأخير قبل إعادة المحاولة، ويتضاعف بعدها
`maxRetryDelayMs`	`8000`	سقف التباعد، وحدّ القطع لترويسة `Retry-After`
`fetch`	`globalThis.fetch`	لتمرير تنفيذ خاص عبر وكيل أو بروكسي
`onResponse`	—	يُستدعى بعد كل رد ويحمل `requestId` وحصّة حدود المعدّل والمدة
`onRetry`	—	يُستدعى قبل كل إعادة محاولة

التوابع المتاحة

التابع	نقطة النهاية	النطاق
`vito.auth.verify()`	`GET /v1/auth/verify`	أي
`vito.auth.rotateKey()`	`POST /v1/auth/rotate-key`	أي
`vito.balance.retrieve(discordId)`	`GET /v1/balance/:discordId`	`balance:read`
`vito.payments.deduct(params)`	`POST /v1/deduct`	`deduct:create`
`vito.payments.credit(params)`	`POST /v1/add`	`credit:create`
`vito.payments.transfer(params)`	`POST /v1/transfer`	`transfer:create`
`vito.transactions.list({ page, limit })`	`GET /v1/transactions`	`transactions:read`
`vito.transactions.iterate({ limit, maxPages })`	تصفّح تلقائي للصفحات	`transactions:read`
`vito.transactions.retrieve(id)`	`GET /v1/transactions/:id`	`transactions:read`
`vito.webhookEvents.list({ page, limit })`	`GET /v1/webhooks/events`	`transactions:read`
`vito.webhookEvents.iterate({ limit, maxPages })`	تصفّح تلقائي للصفحات	`transactions:read`
`Webhooks.constructEvent(…)`	— (تحقّق محلي)	—

كل تابع يُعيد حقل data بعد فكّ التغليف مباشرةً — لا حاجة للمرور بـ success أو data بنفسك. ويقبل كل تابع خيارات لكل استدعاء: { timeoutMs, maxRetries, signal, headers }، وتقبل توابع الكتابة { idempotencyKey } إضافةً إليها.

أمثلة الاستخدام

فحص المفتاح عند الإقلاع

const project = await vito.auth.verify();

console.log(project.status);   // "active"
console.log(project.scopes);   // ["balance:read", "deduct:create", …]
console.log(project.rateLimit); // { tier, requestsPerMinute, requestsPerHour }

قراءة رصيد

const wallet = await vito.balance.retrieve('123456789012345678');

if (!wallet.hasPin) {
  // لا يملك رمز PIN لمحفظته، فلا يستطيع تأكيد أي خصم بعد.
}

الخصم من مستخدم (بيع منتج)

const confirmation = await vito.payments.deduct({
  discordId: '123456789012345678',
  guildId: '987654321098765432',
  amount: 250,
  reason: 'سيف أسطوري',
  merchantRef: 'order_10423',
  metadata: { sku: 'sword-legendary' },
  product: {
    type: 'virtual_item',
    name: 'سيف أسطوري',
    description: 'يسبّب 120 نقطة ضرر.',
    imageUrl: 'https://cdn.example.com/sword.png',
  },
});

console.log(confirmation.confirmUrl); // أرسل المستخدم إلى هنا
console.log(confirmation.expiresAt);  // unix ms، بعد 10 دقائق

سجّل الطلب كـ معلّق هنا فقط. الخصم لم يحدث بعد — أكمِل عند webhook الحدث confirmation.completed لا عند هذا الرد.

إضافة رصيد لمستخدم

const credit = await vito.payments.credit(
  {
    discordId: '123456789012345678',
    amount: 250,
    reason: 'استرداد الطلب order_10423',
    merchantRef: 'refund_10423',
  },
  // اشتقاق المفتاح من سجلّك يجعل إعادة التشغيل من طابور مهام آمنة:
  // التكرار يُعيد النتيجة الأصلية بدل أن يدفع مرتين.
  { idempotencyKey: 'refund_10423' },
);

console.log(credit.transactionId, credit.ownerBalance, credit.recipientBalance);

تصفّح المعاملات

const since = Date.now() - 24 * 60 * 60 * 1000;

// مولّد غير متزامن يجلب الصفحات عند الحاجة — بلا حلقة تصفّح يدوية.
for await (const tx of vito.transactions.iterate({ limit: 100 })) {
  if (tx.date < since) break; // الأحدث أولاً
  // tx.type هو الاتجاه بالنسبة لـ tx.discordId: 1 = وارد، 0 = صادر.
}

منع التكرار وإعادة المحاولة

ترسل الحزمة ترويسة Idempotency-Key مع كل عملية كتابة (deduct وcredit وtransfer). وإن لم تمرّر مفتاحاً فهي تولّده مرّة واحدة لكل استدعاء وتعيد إرساله نفسه مع كل إعادة محاولة، فلا يمكن لإعادة محاولة أن تُسوّي العملية مرتين. مرّر مفتاحك الخاص عندما قد تُعاد المحاولة نفسها من عملية جديدة — طابور مهام، أو إعادة تسليم، أو مهمة مجدولة:

await vito.payments.credit(params, { idempotencyKey: `refund_${orderId}` });

السلوك	الحالات
تُعاد المحاولة تلقائياً	أعطال الشبكة، انتهاء المهلة، `408`، `429`، `5xx`، و`409 VITO_IDEMPOTENCY_IN_PROGRESS`
لا تُعاد المحاولة أبداً	`409 VITO_IDEMPOTENCY_CONFLICT`، وبقيّة أخطاء `4xx`، و`auth.rotateKey()`

auth.rotateKey() مستثنى عمداً — إعادة المحاولة عليه تُصدر مفتاحاً ثانياً وتُبطل المفتاح الذي أعادته المحاولة الأولى.

إن كانت قيمة Retry-After أطول من maxRetryDelayMs (أي أن حصّتك بالساعة استُهلكت فعلاً) فترمي الحزمة VitoRateLimitError فوراً بدل أن تنام خلال مهلة طلبك.

التحقّق من الـ webhooks بالـ SDK

import { Webhooks, VitoSignatureVerificationError } from '@vetox-bot/vito';

try {
  const event = Webhooks.constructEvent({
    payload: rawRequestBody, // الجسم الخام — انظر التحذير أدناه
    signature: req.header('x-vito-signature') ?? '',
    secret: process.env.VITO_WEBHOOK_SECRET,
  });

  if (event.eventType === 'confirmation.completed') {
    // نوع الحقل data يُضيَّق تلقائياً حسب eventType.
    await fulfil(event.data.merchantRef);
  }
} catch (error) {
  if (error instanceof VitoSignatureVerificationError) {
    // ارفض التسليم بـ 400 — توقيع مزوّر أو منتهي أو جسم مُعاد صياغته.
  }
}

يتحقّق constructEvent من نافذة إعادة التشغيل البالغة 5 دقائق، ثم يقارن بزمن ثابت مع كل توقيع h1 في الترويسة — فيعمل تلقائياً خلال فترة تداخل تدوير السرّ البالغة 24 ساعة — ثم يحلّل الحمولة ويُعيدها مكتوبة النوع. في Next.js (موجّه App Router) استخدم النسخة التي تقرأ الجسم الخام بنفسها:

export const runtime = 'nodejs'; // التحقّق يستخدم node:crypto

export async function POST(request: Request) {
  const event = await Webhooks.constructEventFromRequest(request, {
    secret: process.env.VITO_WEBHOOK_SECRET,
  });

  return Response.json({ received: true });
}

التوقيع يغطّي البايتات الخام. في Express ركّب express.raw({ type: 'application/json' }) على مسار الـ webhook — لأن express.json() يستهلك الجسم فيفشل كل تحقّق. وفي Next.js لا تستدعِ request.json() قبل constructEventFromRequest.

التسليم مرّة واحدة على الأقل. امنع التكرار باستخدام event.eventId قبل أن تنفّذ أي أثر جانبي.

معالجة الأخطاء

كل ما ترميه الحزمة يرث من VitoError، ويحمل code وstatus وtype وrequestId وretryable.

الصنف	الحالة	متى
`VitoInvalidRequestError`	—	معطيات مرفوضة قبل إرسال أي طلب
`VitoConfigurationError`	—	مفتاح ناقص أو مشوَّه، أو `baseUrl` غير صالح
`VitoValidationError`	400	رفض الـ API جسم الطلب أو معطياته
`VitoAuthenticationError`	401	مفتاح غير صالح أو ملغى
`VitoInsufficientFundsError`	402	المحفظة لا تغطّي المبلغ (المستخدم أو المالك)
`VitoPermissionError`	403	نطاق ناقص، أو IP، أو الشروط، أو تجميد، أو سيرفر غير مسموح، أو عضوية منقضية
`VitoNotFoundError`	404	مستخدم أو معاملة أو طلب تأكيد غير موجود
`VitoConflictError`	409	تعارض في منع التكرار، أو طلب ما زال قيد التنفيذ
`VitoGoneError`	410	انقضت نافذة التأكيد
`VitoRateLimitError`	429	تجاوز الحد — يحمل `retryAfterSeconds`
`VitoServerError`	5xx	عطل لدينا
`VitoConnectionError`	—	`VITO_SDK_TIMEOUT` أو `VITO_SDK_CONNECTION` أو `VITO_SDK_ABORTED`
`VitoSignatureVerificationError`	—	فشل التحقّق من توقيع webhook

import { isVitoError, VitoInsufficientFundsError } from '@vetox-bot/vito';

try {
  await vito.payments.deduct(params);
} catch (error) {
  if (error instanceof VitoInsufficientFundsError) return notEnoughVito();

  if (isVitoError(error)) {
    logger.error({ code: error.code, requestId: error.requestId });
  }
  throw error;
}

سجّل requestId دائماً — هو ما يحتاجه الدعم لتتبّع استدعاء بعينه.

إلغاء استدعاء

const controller = new AbortController();
setTimeout(() => controller.abort(), 2000);

await vito.balance.retrieve(id, { signal: controller.signal });

الإلغاء يوقف أيضاً أي إعادة محاولة منتظرة، ويرمي VitoConnectionError بالرمز VITO_SDK_ABORTED.

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

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

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

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

Vito يُعيد confirmUrl

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

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

على vetox.io.

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

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

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

تحقّق من التوقيع، ثم افتح المحتوى أو سلّم المنتج.

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

مُعامِلات الطلب — `/v1/deduct`

الحقل	مطلوب	ملاحظات
`discordId`	نعم	معرّف ديسكورد للمستخدم — رقم snowflake من 17 إلى 20 خانة
`amount`	نعم	عدد صحيح موجب
`guildId`	نعم	سيرفر ديسكورد الذي انطلقت منه العملية. كل عملية خصم يجب أن تأتي من سيرفر
`reason`	لا	حتى 256 حرفاً. يُعرَض للمستخدم ويُعاد في الـ webhook
`merchantRef`	لا	مرجعك الخاص، حتى 128 حرفاً. استخدمه لمطابقة الـ webhook بسجلاتك
`product`	لا	`{ type, name, description?, imageUrl? }` — يظهر في صفحة التأكيد وفي الرسالة الخاصة
`imageUrl`	لا	يجب أن يبدأ بـ `https://`
`metadata`	لا	حتى 10 أزواج نصية (مفتاح/قيمة)، تُمرَّر كما هي

إضافة رصيد لمستخدم

POST /v1/add يضيف Vito لمستخدم من رصيدك أنت — للمكافآت أو الاستردادات. نفس حقول /deduct عدا guildId وproduct.

على عكس الخصم، الإضافة بلا خطوة تأكيد — تُسوّى فوراً. تتطلّب النطاق credit:create ورصيداً كافياً، وإلا أعاد الاستدعاء 402 VITO_INSUFFICIENT_OWNER_FUNDS.

الرسوم

كل عملية خصم تُسوّى لصالحك بعد خصم رسوم المنصّة — بنفس جدول تحويلات Vito داخل التطبيق، وبحسب مستوى عضويتك أنت:

عضويتك	الرسوم
نورمال، سيلفر، جولد	7%
بلاتينيوم	6%
دايموند	5%

المبالغ 5 Vito أو أقل بلا رسوم، والإضافات عبر /v1/add بلا رسوم دائماً.

Webhooks

أضف رابط استدعاء واحداً أو أكثر بصيغة https من تبويب الإعدادات. يرسل Vito طلب POST موقَّعاً كلما وصل طلب تأكيد إلى حالة نهائية.

لا تُرسَل الـ webhooks إلا إذا كان لمشروعك رابط استدعاء وسرّ توقيع معاً. اكشف السرّ (whsec_…) مرة واحدة من تبويب مفاتيح API.

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

كل عملية تسليم تحمل ترويسة X-Vito-Signature:

X-Vito-Signature: ts=<unix>;h1=<hex>

وترافقها ترويستان إضافيتان — استخدم X-Vito-Event-Id مفتاحاً لمنع التكرار، فإعادة المحاولة تُرسل المعرّف نفسه:

الترويسة	تحتوي
`X-Vito-Event-Id`	معرّف ثابت لهذا الحدث — لا يتغيّر عبر إعادات المحاولة
`X-Vito-Event-Type`	مثل `confirmation.completed`

أثناء تدوير سرّ التوقيع تحمل الترويسة أكثر من توقيع واحد، الأحدث أولاً:

X-Vito-Signature: ts=<unix>;h1=<new>;h1=<old>

اقبل التسليم إذا طابق أي h1. المُتحقِّق الذي يقرأ الأول فقط سيرفض كل webhook إلى أن ينشر السرّ الجديد — وهو ما يُبطل الغرض من فترة التداخل البالغة 24 ساعة.

مستخدمو Node.js: التابع Webhooks.constructEvent في حزمة @vetox-bot/vito ينفّذ كل ما يلي نيابةً عنك — نافذة إعادة التشغيل، ومطابقة كل توقيع h1، والمقارنة بزمن ثابت — ويُعيد الحدث مكتوب النوع. الشيفرة أدناه للتنفيذ اليدوي أو للغات الأخرى.

أعِد حساب HMAC على <ts>:<rawBody> بسرّ التوقيع الخاص بك، وقارِن بزمن ثابت.

const crypto = require('crypto');

function verify(rawBody, header, secret) {
  const parts = header.split(';');
  const ts = parts.find(p => p.startsWith('ts='))?.slice(3);
  const sigs = parts.filter(p => p.startsWith('h1=')).map(p => p.slice(3));
  if (!ts || sigs.length === 0) return false;

  // Reject anything older than ~5 minutes — replay protection.
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const expected = Buffer.from(
    crypto.createHmac('sha256', secret).update(`${ts}:${rawBody}`).digest('hex'),
  );

  // Any matching signature is valid — a rotation emits several.
  return sigs.some(sig => {
    const actual = Buffer.from(sig);
    // timingSafeEqual throws when the lengths differ, so check first.
    return (
      actual.length === expected.length && crypto.timingSafeEqual(actual, expected)
    );
  });
}

تحقّق من الجسم الخام للطلب، قبل أي تحليل JSON أو وسيط يعيد صياغته.

الأحداث

خمسة أنواع من الأحداث، تشترك كلها في شكل حمولة واحد. الحقل data.status يحمل النتيجة.

الحدث	المعنى
`confirmation.completed`	تمت الموافقة والخصم. يحمل `transactionId`. أكمِل عمليتك هنا
`confirmation.failed`	تعذّر الإكمال — رصيد غير كافٍ أو خطأ داخلي. يحمل `failureReason`
`confirmation.expired`	لم يُؤكَّد خلال 10 دقائق. لم يتحرّك أي Vito
`confirmation.cancelled`	ألغاه المستخدم. لم يتحرّك أي Vito
`credit.completed`	تمّت تسوية إضافة `/add` مموَّلة من المالك. يُرسَل فوراً — بلا خطوة تأكيد

تُعاد محاولة الـ webhooks 5 مرات مع تباعد تصاعدي. ردّ بـ 2xx بسرعة ونفّذ التسليم لديك بشكل غير متزامن.

رموز الأخطاء

كل رد مُغلَّف. النجاح يحمل data، والفشل يحمل error، ولا يجتمعان أبداً:

{
  "success": false,
  "error": {
    "type": "Forbidden",
    "message": "API key lacks the required scope for this operation.",
    "code": "VITO_INSUFFICIENT_SCOPE"
  },
  "requestId": "…",
  "timestamp": 1735161600000
}

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

الرمز	الحالة	المعنى
`VITO_VALIDATION_ERROR`	400	حقل ناقص أو بصيغة غير صحيحة
`VITO_INVALID_AMOUNT`	400	`amount` ليس عدداً صحيحاً موجباً
`VITO_AMOUNT_LIMIT_EXCEEDED`	400	تجاوز سقف المعاملة الواحدة لديك
`VITO_DAILY_VOLUME_EXCEEDED`	400	هذا الاستدعاء سيتجاوز سقف حجمك اليومي
`VITO_SELF_TRANSFER`	400	المُرسِل والمستلِم هما المستخدم نفسه
`VITO_INVALID_API_KEY`	401	مفتاح ناقص أو غير صالح أو ملغى أو غير معروف
`VITO_INSUFFICIENT_FUNDS`	402	رصيد المستخدم لا يغطّي المبلغ
`VITO_INSUFFICIENT_OWNER_FUNDS`	402	رصيدك أنت لا يكفي لتمويل `/add`
`VITO_INSUFFICIENT_SCOPE`	403	المفتاح لا يملك النطاق الذي تتطلّبه نقطة النهاية
`VITO_IP_NOT_ALLOWED`	403	عنوان IP المُستدعي ليس في قائمة السماح
`VITO_OWNER_MEMBERSHIP_INACTIVE`	403	انقضت عضوية المالك — مجمّد حتى يُجدِّد
`VITO_GUILD_NOT_ALLOWED`	403	`guildId` ليس ضمن قائمة السيرفرات المسموح بها للمشروع
`VITO_TOS_NOT_ACCEPTED`	403	شروط المطوّرين غير مقبولة، أو هناك نسخة أحدث بانتظار الموافقة
`VITO_PROJECT_FROZEN`	403	مجمَّد — غالباً بسبب انقضاء عضوية المالك
`VITO_PROJECT_SUSPENDED`	403	موقوف من طاقم فيتوكس
`VITO_PROJECT_BANNED`	403	محظور من طاقم فيتوكس
`VITO_USER_BLACKLISTED`	403	المستخدم محظور من عمليات Vito
`VITO_ACCOUNT_LOCKED`	403	محفظة المستخدم مقفلة بعد محاولات PIN فاشلة
`VITO_USER_NOT_FOUND`	404	لا يوجد حساب Vito لمعرّف ديسكورد هذا
`VITO_CONFIRMATION_NOT_FOUND`	404	رمز تأكيد غير معروف
`VITO_IDEMPOTENCY_CONFLICT`	409	نفس `Idempotency-Key` بجسم طلب مختلف
`VITO_IDEMPOTENCY_IN_PROGRESS`	409	طلب مطابق ما زال قيد التنفيذ — أعد المحاولة بعد قليل
`VITO_CONFIRMATION_ALREADY_PROCESSED`	409	طلب التأكيد وصل حالة نهائية من قبل
`VITO_KEY_ROTATION_IN_PROGRESS`	409	هناك تدوير جارٍ بالفعل
`VITO_CONFIRMATION_EXPIRED`	410	انقضت نافذة التأكيد البالغة 10 دقائق
`VITO_RATE_LIMITED`	429	تمهّل وأعد المحاولة
`VITO_INTERNAL_ERROR`	500	عطل غير متوقّع لدينا

حدود المعدّل

عضوية المالك	لكل دقيقة	لكل ساعة
بلا	60	1,000
سيلفر أو جولد	180	5,000
بلاتينيوم أو دايموند	600	15,000

يوجد أيضاً حد لكل عنوان IP يساوي نصف حصّتك في الدقيقة، بحد أدنى 30.

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

أرسل ترويسة Idempotency-Key لمنع تكرار إعادات المحاولة بأمان.

نقاط النهاية

نقطة النهاية	النطاق	تابع الـ SDK
`GET /v1/auth/verify`	أي	`vito.auth.verify()`
`POST /v1/auth/rotate-key`	أي	`vito.auth.rotateKey()`
`GET /v1/balance/:discordId`	`balance:read`	`vito.balance.retrieve(id)`
`POST /v1/deduct`	`deduct:create`	`vito.payments.deduct(params)`
`POST /v1/add`	`credit:create`	`vito.payments.credit(params)`
`POST /v1/transfer`	`transfer:create`	`vito.payments.transfer(params)`
`GET /v1/transactions` و `/:id`	`transactions:read`	`vito.transactions.list()` / `.retrieve(id)`
`GET /v1/webhooks/events`	`transactions:read`	`vito.webhookEvents.list()`

الحدود

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

قائمة الأمان

أبقِ الأسرار على الخادم

مفتاح API وسرّ التوقيع لا مكان لهما في كود العميل إطلاقاً. دوّر أيّاً منهما فوراً إن تسرّب.

تحقّق من كل webhook

افحص التوقيع مقابل الجسم الخام، وارفض ما مضى عليه أكثر من ~5 دقائق.

سوِّ عند completed فقط

لا تسلّم أبداً بناءً على رد /deduct — الخصم ليس نهائياً حتى confirmation.completed.

أقل صلاحية ممكنة

اطلب النطاقات التي تستخدمها فعلاً فقط، وفعّل قائمة عناوين IP المسموح بها.

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

كل استدعاء يُعيد خطأ عدم التصريح

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

فقدتُ مفتاحي

لا يمكن استعادته — لا يُخزَّن إلا تجزئته. دوّره للحصول على واحد جديد.

توقيعات webhook تفشل بعد التدوير

اقبل السرَّين خلال فترة التداخل البالغة 24 ساعة.

خصم لا يكتمل أبداً

المستخدم لم يوافق عليه. تنتهي طلبات التأكيد بعد 10 دقائق.

لا تصل أي webhooks

المشروع يحتاج رابط استدعاء وسرّ توقيع معاً. بواحد منهما فقط لا يُسلَّم شيء.

وصل Vito أقل مما خصمت

هذه رسوم التسوية. استخدم مبالغ 5 Vito أو أقل لتجنّبها، أو احسبها ضمن تسعيرك.

402 VITO_INSUFFICIENT_OWNER_FUNDS

/v1/add يُموَّل من رصيدك أنت، ولا يُنشأ من العدم. اشحن رصيدك.

Vito

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

طلبات الدفع

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

@vetox-bot/vito على npm

حزمة Node.js الرسمية — تثبيت واحد وتكامل كامل.

الرئيسية

الأدوات

Vito

لوحة المتصدرين

Vito API والمشتريات

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

النطاقات

المصادقة

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

SDK الرسمي لـ Node.js

التثبيت

التهيئة

خيارات العميل

التوابع المتاحة

أمثلة الاستخدام

فحص المفتاح عند الإقلاع

قراءة رصيد

الخصم من مستخدم (بيع منتج)

إضافة رصيد لمستخدم

تصفّح المعاملات

منع التكرار وإعادة المحاولة

التحقّق من الـ webhooks بالـ SDK

معالجة الأخطاء

إلغاء استدعاء

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

مُعامِلات الطلب — `/v1/deduct`

إضافة رصيد لمستخدم

الرسوم

Webhooks

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

الأحداث

رموز الأخطاء

حدود المعدّل

نقاط النهاية

الحدود

قائمة الأمان

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

Vito

طلبات الدفع

@vetox-bot/vito على npm

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

​النطاقات

​المصادقة

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

​SDK الرسمي لـ Node.js

​التثبيت

​التهيئة

​خيارات العميل

​التوابع المتاحة

​أمثلة الاستخدام

​فحص المفتاح عند الإقلاع

​قراءة رصيد

​الخصم من مستخدم (بيع منتج)

​إضافة رصيد لمستخدم

​تصفّح المعاملات

​منع التكرار وإعادة المحاولة

​التحقّق من الـ webhooks بالـ SDK

​معالجة الأخطاء

​إلغاء استدعاء

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

​مُعامِلات الطلب — /v1/deduct

​إضافة رصيد لمستخدم

​الرسوم

​Webhooks

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

​الأحداث

​رموز الأخطاء

​حدود المعدّل

​نقاط النهاية

​الحدود

​قائمة الأمان

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

Vito

طلبات الدفع

@vetox-bot/vito على npm

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

النطاقات

المصادقة

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

SDK الرسمي لـ Node.js

التثبيت

التهيئة

خيارات العميل

التوابع المتاحة

أمثلة الاستخدام

فحص المفتاح عند الإقلاع

قراءة رصيد

الخصم من مستخدم (بيع منتج)

إضافة رصيد لمستخدم

تصفّح المعاملات

منع التكرار وإعادة المحاولة

التحقّق من الـ webhooks بالـ SDK

معالجة الأخطاء

إلغاء استدعاء

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

مُعامِلات الطلب — `/v1/deduct`

إضافة رصيد لمستخدم

الرسوم

Webhooks

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

الأحداث

رموز الأخطاء

حدود المعدّل

نقاط النهاية

الحدود

قائمة الأمان

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