دۆکیومێنتی Vito API

Vito API dihêle ku sepana te bi hevsengiya Vito ya bikarhênerekî ji nav Discord re bixebite — wê bixwîne, jê pere bistîne, an jê re kredî vegerîne. Bikarhêner her standina perê beriya ku tu Vito biguhere bi PIN-a xwe li vetox.io piştrast dike, û encam ji sepana te re tê agahdarkirin. Vito dirava virtual a hundirê ekosîstema Vetox e; API bikar bîne da ku ezmûnên li ser bingeha Vito ava bikî — vekirina naverok, taybetmendî, feyde an xelatan. Tu kirîn an firotina bi pereyê rastîn pêk nayê.

Ev API-yeke REST e ku bi kilîleke veşartî tê pejirandin. Hemû xalên dawî JOSN vedigerînin û li jêr /v1 hatine guhertoyandin.

Mifteya APIya te bi hesabê te yê Vetox ve girêdayî ye. Her kêşan ji bo te tê veqetandin: dema bernameya te Vito ji bikarhênerek kêm dike, ew Vito li balansa te tê zêdekirin (piştî kêmkirina xerca platformê), tu carî nayê şewitandin. Dema bernameya te Vito li bikarhênerek zêde dike, ji balansa te tê dabînkirin.

Vito her dem di navbera balansan de digere — tu carî ji pere an bo pereyê rastîn na. Ji bikarhêner tevahiya mîqdara ku tu daxwaz dikî tê standin; tu piştî xerca platformê mîqdarê werdigirî; kredî û xelat ji balansa te bi riya /add têne dabînkirin.

Gihîştina Vito API ji bo her projeyekê tê dayîn. Beriya ku tu wê gazî bikî pêdivî bi te heye:

• Endamtiyeke bikarhênerî ya çalak (asta Silver an bilindtir). Eger endamtiya xwedî biqede API bixweber tê cemidandin, û dema ku ji nû ve abone bibe vedigere.
• Sepanek pêşvebirî ya pejirandî. Yekê ji vê rûpelê bişîne; tîma Vetox wê bi destan dinirxîne.
• Mercên Pêşvebirê API yên pejirandî — dema ku tu serlêdana pêşvebiriya xwe dişînî tê pejirandin.
• Qadên ku projeya te pêdivî pê hene. Ji aliyê tîma Vetox ve li gor sepana te tê dayîn.

Her daxwazê bi kilîla API ya veşartî di sernavê Authorization de wek tokena Bearer pejirandinê bike. Kilîl pêşgira vito_live_ hene.

Authorization: Bearer vito_live_xxxxxxxxxxxxxxxx

Du qatên vebijarkî projeya te bêtir diparêzin:

• Lîsteya destûrê ya IP — daxwazan bi IP-ên taybet ên serverê sînor bike (li tabê Mîheng wê mîheng bike).
• Sînorên rêjeyê — banî daxwazan ji bo her projeyê yên ku bi asta endamtiya te re mezin dibin.

Kilîla te dema ku sepana te tê pejirandin tê çêkirin. Ew tenê carekê tê nîşandan — wê ji tabê Kilîlên API nîşan bide û tavilê hilîne.

Vetox kilîla te tu carî bi awayekî xwendinbar hilnayne (tenê heşek bi xwê). Wê wek veşartiyekê li aliyê serverê hilîne — guhêrbarek hawîrdorê an rêveberek veşartiyan — tu carî di koda muşteriyê, depoya git an gerokê de.

Wê ji tabê Kilîlên API bizivirîne. Kilîla berê di heyama lêborînê ya 24 saetan de berdewam dixebite da ku tu ya nû bê rawestan belav bikî, paşê radiweste.

Her standina perê di nav piştrastkirinekê re derbas dibe ku bikarhêner bi PIN-a xwe pejirandinê dike — kilîla te bi tena serê xwe tu carî Vito naguhêze:

1. 1Sepana te POST /deduct bi bikarhêner, mîqdar, guildId-a jêderkê û hûrgiliyên tiştî gazî dike.
2. 2Vito piştrastkirineke li benda (10 xulek derbasdar) çêdike û confirmUrl vedigerîne. Eger guildId hat dayîn, peyamek rasterast a bi hûrgiliyan û bişkokeke ber bi rûpela piştrastkirinê re jî ji bikarhêner re tê şandin.
3. 3Bikarhêner confirmUrl li vetox.io vedike û standina perê bi PIN-a berîka xwe pejirandinê dike.
4. 4Vito Vito kêm dike, danûstandinê tomar dike û — eger te webhook mîheng kiribe — bûyereke îmzekirî ya confirmation.completed ji URL-a callback-a te re dişîne.
5. 5Sepana te îmzeyê piştrast dike û çalakiya xwe temam dike (mînak, naverokê vedike).

Xala dawî ya kêmkirinê van qadên laş qebûl dike:

* qada pêwîst.

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 ji balansa te bo bikarhênerek dide — ji bo xelat an krediyan. Heman qadan wek /deduct werdigire ji bilî guildId û product. Berevajî kêşanek, ew lezgîn e û hewceyî PINa bikarhêner nake — mifteya APIya te desthilatiya te ye — loma bersiv jixwe veguhastina temamkirî nîşan dide. Bikarhêner tevahiya mîqdarê werdigire; tu xerca platformê nayê sepandin.

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
}

Li tabê Mîheng yek an çend URL-ên callback ên https zêde bike. Vito her car ku piştrastkirinek digihîje rewşeke dawî, POST-eke îmzekirî ji her URL-a mîhengkirî re radigihîne, heta 5 caran bi paşvekişîna ekponansiyel ji nû ve hewl dide.

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 yek ji çar cureyên bûyeran dişîne. Hemû heman şêwaza barê parve dikin; data.status encamê nîşan dide.

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
  }
}

Çewtî rewşeke ne-2xx bi laşeke JSON ku error.code-ya asta jor hildigire vedigerînin. Rewşên gelemperî:

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

Entegrasyoneke demoyê ya serbixwe tê pêşkêşkirin da ku tu tevahiya herikînê ji destpêkê heta dawiyê bêyî nivîsandina koda biceribînî. Daxwaz → piştrastkirin → PIN → webhook → temamkirin derbas dike.

1. 1Peldanka entegrasyona demoyê veke û kilîla Vito API, tokeneke botê ya Discord û nasnameya servera (guild) ceribandinê ya xwe li config.json zêde bike.
2. 2npm install && npm start bimeşîne, paşê http://localhost:4000 veke.
3. 3Bikarhênerekî bi nasnameya Discord bigere, tiştekî hilbijêre û standina perê dest pê bike — demo /deduct gazî dike û confirmUrl nîşan dide.
4. 4PIN-ê li vetox.io pejirandinê bike; demo temamiyê tespît dike (bi webhook eger mîhengkirî be, wekî din bi pirsîn) û çalakiya mînak temam dike.