Vito API दस्तावेज़

Vito API आपके एप्लिकेशन को Discord के भीतर से किसी उपयोगकर्ता के Vito बैलेंस के साथ काम करने देता है — इसे पढ़ना, इससे शुल्क लेना, या इसमें वापस क्रेडिट करना। उपयोगकर्ता किसी भी Vito के हिलने से पहले vetox.io पर अपने PIN से हर शुल्क की पुष्टि करता है, और परिणाम की सूचना आपके ऐप को दी जाती है। Vito, Vetox की इकोसिस्टम-आंतरिक वर्चुअल करेंसी है; Vito-आधारित अनुभव बनाने के लिए API का उपयोग करें — सामग्री, सुविधाएँ, लाभ या पुरस्कार अनलॉक करना। वास्तविक पैसे से कोई खरीद या बिक्री नहीं होती।

यह एक गुप्त कुंजी से प्रमाणित REST API है। सभी एंडपॉइंट JSON लौटाते हैं और /v1 के अंतर्गत संस्करणित हैं।

आपकी API कुंजी आपके Vetox खाते से जुड़ी है। हर शुल्क आपके पक्ष में निपटाया जाता है: जब आपका ऐप किसी उपयोगकर्ता से Vito काटता है, तो वह Vito आपके अपने बैलेंस में जमा होता है (प्लेटफ़ॉर्म शुल्क घटाकर), कभी नष्ट नहीं होता। जब आपका ऐप किसी उपयोगकर्ता को Vito जोड़ता है, तो वह आपके बैलेंस से वित्तपोषित होता है।

Vito हमेशा बैलेंस के बीच चलता है — कभी वास्तविक पैसे से या उसमें नहीं। उपयोगकर्ता से आपके द्वारा माँगी गई पूरी राशि ली जाती है; आपको प्लेटफ़ॉर्म शुल्क के बाद की राशि मिलती है; क्रेडिट और पुरस्कार आपके बैलेंस से /add के माध्यम से वित्तपोषित होते हैं।

Vito API एक्सेस प्रति प्रोजेक्ट दिया जाता है। इसे कॉल करने से पहले आपको चाहिए:

• एक सक्रिय उपयोगकर्ता सदस्यता (Silver या उच्चतर स्तर)। यदि स्वामी की सदस्यता समाप्त हो जाती है तो API स्वतः फ़्रीज़ हो जाता है, और पुनः सदस्यता लेने पर बहाल हो जाता है।
• एक स्वीकृत डेवलपर आवेदन। इस पृष्ठ से एक जमा करें; Vetox टीम इसकी मैन्युअल समीक्षा करती है।
• स्वीकृत API डेवलपर शर्तें — आपके डेवलपर आवेदन सबमिट करते समय स्वीकार की जाती हैं।
• आपके प्रोजेक्ट को आवश्यक स्कोप। ये आपके आवेदन के आधार पर Vetox टीम द्वारा दिए जाते हैं।

प्रत्येक अनुरोध को Authorization हेडर में अपनी गुप्त API कुंजी के साथ Bearer टोकन के रूप में प्रमाणित करें। कुंजियों में vito_live_ उपसर्ग होता है।

Authorization: Bearer vito_live_xxxxxxxxxxxxxxxx

दो वैकल्पिक परतें आपके प्रोजेक्ट को और सुरक्षित करती हैं:

• IP अनुमति सूची — अनुरोधों को विशिष्ट सर्वर IP तक सीमित करें (इसे सेटिंग्स टैब में कॉन्फ़िगर करें)।
• दर सीमाएँ — प्रति-प्रोजेक्ट अनुरोध सीमाएँ जो आपकी सदस्यता स्तर के साथ बढ़ती हैं।

आपकी कुंजी आवेदन स्वीकृत होने पर बनाई जाती है। यह केवल एक बार दिखाई जाती है — इसे API कुंजियाँ टैब से दिखाएँ और तुरंत संग्रहीत करें।

Vetox आपकी कुंजी को कभी भी पठनीय रूप में संग्रहीत नहीं करता (केवल एक साल्टेड हैश)। इसे सर्वर-साइड सीक्रेट के रूप में रखें — एक पर्यावरण चर या सीक्रेट मैनेजर — कभी भी क्लाइंट कोड, git रिपॉज़िटरी या ब्राउज़र में नहीं।

इसे API कुंजियाँ टैब से घुमाएँ। पुरानी कुंजी रुकने से पहले 24 घंटे की छूट अवधि तक काम करती रहती है ताकि आप नई कुंजी बिना डाउनटाइम के तैनात कर सकें।

हर शुल्क एक पुष्टि से गुज़रता है जिसे उपयोगकर्ता PIN से स्वीकृत करता है — अकेले आपकी कुंजी कभी Vito नहीं हिलाती:

1. 1आपका ऐप उपयोगकर्ता, राशि, स्रोत guildId और आइटम विवरण के साथ POST /deduct कॉल करता है।
2. 2Vito एक लंबित पुष्टि (10 मिनट के लिए मान्य) बनाता है और एक confirmUrl लौटाता है। यदि guildId दिया गया है, तो उपयोगकर्ता को विवरण और पुष्टि पृष्ठ के बटन के साथ एक DM भी भेजा जाता है।
3. 3उपयोगकर्ता vetox.io पर confirmUrl खोलता है और अपने वॉलेट PIN से शुल्क को स्वीकृत करता है।
4. 4Vito, Vito घटाता है, लेनदेन रिकॉर्ड करता है, और — यदि आपने वेबहुक कॉन्फ़िगर किया है — आपके कॉलबैक URL पर एक हस्ताक्षरित confirmation.completed इवेंट भेजता है।
5. 5आपका ऐप हस्ताक्षर सत्यापित करता है और अपनी क्रिया पूरी करता है (उदाहरण के लिए, सामग्री अनलॉक करता है)।

कटौती एंडपॉइंट निम्नलिखित बॉडी फ़ील्ड स्वीकार करता है:

* आवश्यक फ़ील्ड।

POST https://api.vetox.io/public/vito/v1/deduct
Authorization: Bearer vito_live_xxxxxxxxxxxxxxxx
Content-Type: application/json
Idempotency-Key: req_9a1f2b   # optional, dedupes retries for 24h

{
  "discordId": "123456789012345678",
  "amount": 500,
  "guildId": "1470389021162209280",
  "reason": "Unlock premium theme",
  "merchantRef": "ref_1042",
  "product": {
    "type": "feature",
    "name": "Premium theme",
    "description": "Unlocks the premium theme pack",
    "imageUrl": "https://cdn.example.com/theme.png"
  },
  "metadata": { "ref": "1042" }
}

{
  "success": true,
  "data": {
    "confirmationId": "f3c9...e1",
    "confirmUrl": "https://vetox.io/confirm/vito/f3c9...e1",
    "amount": 500,
    "expiresAt": 1735689600000,
    "status": "pending"
  },
  "requestId": "req_abc123",
  "timestamp": 1735689300000
}

POST /add आपके अपने बैलेंस से किसी उपयोगकर्ता को Vito जमा करता है — पुरस्कार या क्रेडिट के लिए। यह guildId और product को छोड़कर /deduct जैसे ही फ़ील्ड लेता है। शुल्क के विपरीत यह तत्काल है और उपयोगकर्ता के PIN की ज़रूरत नहीं — आपकी API कुंजी ही आपका अधिकार है — इसलिए प्रतिक्रिया पहले से ही पूर्ण ट्रांसफ़र दर्शाती है। उपयोगकर्ता को पूरी राशि मिलती है; कोई प्लेटफ़ॉर्म शुल्क लागू नहीं होता।

POST https://api.vetox.io/public/vito/v1/add
Authorization: Bearer vito_live_xxxxxxxxxxxxxxxx
Content-Type: application/json
Idempotency-Key: credit_7f3a   # optional, dedupes retries for 24h

{
  "discordId": "123456789012345678",
  "amount": 250,
  "reason": "Event reward",
  "merchantRef": "reward_1042",
  "metadata": { "ref": "1042" }
}

{
  "success": true,
  "data": {
    "transactionId": "txn_91b2",
    "toDiscordId": "123456789012345678",
    "amount": 250,
    "ownerBalance": 48250,
    "recipientBalance": 1250,
    "status": "completed"
  },
  "requestId": "req_def456",
  "timestamp": 1735689300000
}

सेटिंग्स टैब में एक या अधिक https कॉलबैक URL जोड़ें। जब भी कोई पुष्टि अंतिम स्थिति तक पहुँचती है, Vito प्रत्येक कॉन्फ़िगर URL पर एक हस्ताक्षरित POST वितरित करता है, घातीय बैकऑफ़ के साथ 5 बार तक पुनः प्रयास करता है।

signature = HMAC_SHA256(signingSecret, "<ts>:<rawBody>")
header    = X-Vito-Signature: ts=<unix-seconds>;h1=<hex-signature>

import crypto from 'crypto';
import express from 'express';

const app = express();
// IMPORTANT: verify against the RAW body, before JSON parsing.
app.post('/webhooks/vito', express.raw({ type: '*/*' }), (req, res) => {
  const sig = req.header('X-Vito-Signature') || '';   // "ts=<unix>;h1=<hmac>[;h1=<hmac>]"
  const pairs = sig.split(';').map(p => p.split('='));
  const ts = pairs.find(([k]) => k === 'ts')?.[1];
  const sigs = pairs.filter(([k]) => k === 'h1').map(([, v]) => v);
  const rawBody = req.body.toString('utf8');

  const expected = crypto
    .createHmac('sha256', process.env.VITO_SIGNING_SECRET)     // whsec_...
    .update(`${ts}:${rawBody}`)
    .digest('hex');
  const expectedBuf = Buffer.from(expected, 'hex');

  // During a 24h secret rotation the header carries TWO h1= values — accept ANY.
  // Length-guard FIRST: crypto.timingSafeEqual throws on a length mismatch.
  const ok = sigs.some(h => {
    const got = Buffer.from(h, 'hex');
    return (
      got.length === expectedBuf.length &&
      crypto.timingSafeEqual(got, expectedBuf)
    );
  });
  // Reject anything older than ~5 minutes to stop replays.
  const fresh = ts && Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  if (!ok || !fresh) return res.status(401).end();

  const event = JSON.parse(rawBody);
  if (event.eventType === 'confirmation.completed') {
    grantPremiumTheme(event.data.merchantRef, event.data.fromDiscordId);
  }
  res.status(200).end();   // ack fast; run your action async if slow
});

Vito चार इवेंट प्रकारों में से एक भेजता है। सभी एक ही पेलोड आकार साझा करते हैं; data.status परिणाम दर्शाता है।

POST https://your-app.com/webhooks/vito
X-Vito-Signature: ts=1735689600;h1=4f8b2c...e9
X-Vito-Event-Id: evt_3a2b1c
X-Vito-Event-Type: confirmation.completed
Content-Type: application/json

{
  "eventId": "evt_3a2b1c",
  "eventType": "confirmation.completed",
  "timestamp": 1735689600000,
  "data": {
    "confirmationId": "f3c9...e1",
    "type": "deduct",
    "fromDiscordId": "123456789012345678",
    "toDiscordId": null,
    "amount": 500,
    "reason": "Unlock premium theme",
    "merchantRef": "ref_1042",
    "product": { "type": "feature", "name": "Premium theme" },
    "status": "completed",
    "transactionId": "txn_77a2",
    "metadata": { "ref": "1042" },
    "failureReason": null
  }
}

त्रुटियाँ एक शीर्ष-स्तरीय error.code वाले JSON बॉडी के साथ गैर-2xx स्थिति लौटाती हैं। सामान्य मामले:

{
  "success": false,
  "error": { "type": "Bad Request", "message": "guildId must be a valid Discord server ID", "code": "VITO_VALIDATION_ERROR" },
  "requestId": "req_abc123",
  "timestamp": 1735689300000
}

बिना कोड लिखे पूरे प्रवाह को आद्योपांत आज़माने के लिए एक स्टैंडअलोन डेमो एकीकरण प्रदान किया गया है। यह अनुरोध → पुष्टि → PIN → वेबहुक → पूर्णता से गुज़रता है।

1. 1डेमो एकीकरण फ़ोल्डर खोलें और अपनी Vito API कुंजी, एक Discord बॉट टोकन और अपना परीक्षण सर्वर (guild) ID config.json में जोड़ें।
2. 2npm install && npm start चलाएँ, फिर http://localhost:4000 खोलें।
3. 3Discord ID से एक उपयोगकर्ता खोजें, एक आइटम चुनें और एक शुल्क शुरू करें — डेमो /deduct कॉल करता है और confirmUrl दिखाता है।
4. 4vetox.io पर PIN स्वीकृत करें; डेमो पूर्णता का पता लगाता है (कॉन्फ़िगर होने पर वेबहुक से, अन्यथा पोलिंग से) और नमूना क्रिया पूरी करता है।