Tài liệu Vito API

Vito API cho phép ứng dụng của bạn làm việc với số dư Vito của người dùng ngay trong Discord — đọc số dư, tính phí vào số dư hoặc ghi có trở lại. Người dùng xác nhận mỗi khoản thu bằng PIN trên vetox.io trước khi bất kỳ Vito nào di chuyển, và ứng dụng của bạn được thông báo kết quả. Vito là tiền ảo nội bộ trong hệ sinh thái Vetox; dùng API để xây dựng trải nghiệm dựa trên Vito — mở khóa nội dung, tính năng, đặc quyền hoặc phần thưởng. Không có hoạt động mua hay bán bằng tiền thật nào diễn ra.

Đây là REST API được xác thực bằng một khóa bí mật. Tất cả endpoint đều trả về JSON và được phân phiên bản dưới /v1.

Khóa API của bạn gắn với tài khoản Vetox của bạn. Mọi khoản thu đều được quyết toán cho bạn: khi ứng dụng của bạn trừ Vito của người dùng, số Vito đó được ghi có vào số dư của chính bạn (sau khi trừ phí nền tảng), không bao giờ bị hủy. Khi ứng dụng của bạn cộng Vito cho người dùng, nó được tài trợ từ số dư của bạn.

Vito luôn di chuyển giữa các số dư — không bao giờ từ hay đến tiền thật. Người dùng bị tính đủ số tiền bạn yêu cầu; bạn nhận số tiền sau phí nền tảng; các khoản ghi có và phần thưởng được tài trợ từ số dư của bạn qua /add.

Quyền truy cập Vito API được cấp theo từng dự án. Trước khi gọi, bạn cần:

• Tư cách thành viên người dùng đang hoạt động (cấp Silver trở lên). API tự động đóng băng nếu tư cách của chủ sở hữu hết hạn và được khôi phục khi họ đăng ký lại.
• Một đơn đăng ký nhà phát triển đã được phê duyệt. Gửi từ trang này; đội ngũ Vetox xét duyệt thủ công.
• Đã chấp nhận Điều khoản Nhà phát triển API — được xác nhận khi bạn gửi đơn đăng ký nhà phát triển.
• Các phạm vi mà dự án của bạn cần. Đội ngũ Vetox cấp dựa trên đơn của bạn.

Xác thực mỗi yêu cầu bằng khóa API bí mật trong tiêu đề Authorization dưới dạng token Bearer. Khóa có tiền tố vito_live_.

Authorization: Bearer vito_live_xxxxxxxxxxxxxxxx

Hai lớp tùy chọn bảo vệ dự án của bạn thêm:

• Danh sách IP cho phép — giới hạn yêu cầu ở các IP máy chủ cụ thể (cấu hình ở tab Cài đặt).
• Giới hạn tốc độ — trần yêu cầu theo dự án, tăng theo cấp thành viên của bạn.

Khóa của bạn được tạo khi đơn được phê duyệt. Nó chỉ hiển thị một lần — hiện nó ở tab Khóa API và lưu ngay.

Vetox không bao giờ lưu khóa của bạn ở dạng đọc được (chỉ một hash có muối). Hãy giữ nó như một bí mật phía máy chủ — một biến môi trường hoặc trình quản lý bí mật — không bao giờ trong mã client, kho git hay trình duyệt.

Xoay ở tab Khóa API. Khóa cũ vẫn hoạt động trong thời gian ân hạn 24 giờ để bạn triển khai khóa mới không gián đoạn, rồi ngừng.

Mỗi khoản thu đều đi qua xác nhận mà người dùng phê duyệt bằng PIN — chỉ riêng khóa của bạn không bao giờ chuyển Vito:

1. 1Ứng dụng của bạn gọi POST /deduct với người dùng, số tiền, guildId nguồn và chi tiết mục.
2. 2Vito tạo một xác nhận đang chờ (hợp lệ 10 phút) và trả về confirmUrl. Nếu cung cấp guildId, người dùng cũng nhận được tin nhắn riêng kèm chi tiết và nút đến trang xác nhận.
3. 3Người dùng mở confirmUrl trên vetox.io và phê duyệt khoản trừ bằng PIN ví của họ.
4. 4Vito trừ Vito, ghi lại giao dịch và — nếu bạn đã cấu hình webhook — gửi sự kiện confirmation.completed đã ký đến URL callback của bạn.
5. 5Ứng dụng của bạn xác minh chữ ký và hoàn tất hành động của mình (ví dụ, mở khóa nội dung).

Endpoint trừ chấp nhận các trường thân sau:

* trường bắt buộc.

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 ghi có Vito cho người dùng từ số dư của chính bạn — cho phần thưởng hoặc khoản ghi có. Nó nhận cùng các trường như /deduct ngoại trừ guildId và product. Khác với một khoản thu, nó tức thì và không cần PIN của người dùng — khóa API của bạn là thẩm quyền của bạn — nên phản hồi đã phản ánh giao dịch hoàn tất. Người dùng nhận đủ số tiền; không áp dụng phí nền tảng.

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
}

Thêm một hoặc nhiều URL callback https ở tab Cài đặt. Vito gửi một POST đã ký đến mỗi URL đã cấu hình mỗi khi một xác nhận đạt trạng thái cuối, thử lại tối đa 5 lần với backoff lũy thừa.

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 gửi một trong bốn loại sự kiện. Tất cả đều chung một dạng payload; data.status phản ánh kết quả.

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

Lỗi trả về trạng thái khác 2xx với thân JSON mang error.code ở cấp cao nhất. Các trường hợp phổ biến:

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

Một tích hợp demo độc lập được cung cấp để chạy thử toàn bộ luồng từ đầu đến cuối mà không cần viết mã. Nó đi qua yêu cầu → xác nhận → PIN → webhook → hoàn tất.

1. 1Mở thư mục tích hợp demo và thêm khóa Vito API, một token bot Discord và ID máy chủ (guild) thử nghiệm của bạn vào config.json.
2. 2Chạy npm install && npm start, rồi mở http://localhost:4000.
3. 3Tìm một người dùng theo ID Discord, chọn một mục và bắt đầu thu phí — demo gọi /deduct và hiển thị confirmUrl.
4. 4Phê duyệt PIN trên vetox.io; demo phát hiện hoàn tất (qua webhook nếu đã cấu hình, nếu không thì qua thăm dò) và hoàn tất hành động mẫu.