Skip to main content
Yêu cầu Hội viên Silver trở lên — cả khi đăng ký lẫn cho mọi lệnh gọi đã xác thực. Nếu Hội viên của chủ khóa hết hạn, dự án bị đóng băng cho đến khi họ đăng ký lại.
Một REST 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 từ trong Discord — đọc, trừ, cộng, hoặc chuyển giữa những người dùng. Mọi endpoint đều trả về JSON và được đánh phiên bản dưới /v1.
Vito không bao giờ chuyển sang hay đến từ tiền thật. Nó chỉ di chuyển giữa các số dư Vetox.

Nhận quyền truy cập

Quyền truy cập được cấp theo từng dự án. Bạn cần cả bốn điều kiện:
1

Một Hội viên đang hoạt động, Silver trở lên

Được kiểm tra ở mọi lệnh gọi, không chỉ lúc phê duyệt.
2

Một đơn đăng ký nhà phát triển đã được duyệt

Gửi từ trang Vito API trong bảng điều khiển của bạn. Đội ngũ Vetox xét duyệt thủ công.
3

Đã 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.
4

Các scope mà dự án của bạn cần

Do đội ngũ Vetox cấp dựa trên những gì bạn mô tả.
Hãy viết cụ thể về thứ bạn đang xây dựng và cách bạn sẽ lưu khóa. Chính những đơn mơ hồ mới bị từ chối.

Scope

Xác thực

Gửi khóa bí mật của bạn dưới dạng token Bearer:
Hai lớp tùy chọn giúp gia cố dự án thêm nữa:
  • Danh sách IP cho phép — giới hạn lệnh gọi ở những IP máy chủ nhất định
  • Giới hạn tần suất — trần theo dự án, tăng dần theo cấp Hội viên của chủ sở hữu

Khóa, xoay vòng và lưu trữ

Khóa và khóa bí mật ký của bạn chỉ hiển thị đúng một lần. Sau khi được duyệt, bạn có cửa sổ 7 ngày để hiện chúng ở tab khóa API. Vetox chỉ lưu một bản băm và không thể hiện lại — bỏ lỡ cửa sổ này thì bạn phải xoay vòng khóa.
  • Chỉ giữ nó ở phía máy chủ — ai cầm được khóa đều có thể trừ tiền người dùng của bạn
  • Xoay vòng từ tab khóa API. Khóa cũ vẫn hoạt động thêm 24 giờ như thời gian ân hạn, để bạn triển khai mà không gián đoạn
  • Khóa bí mật ký webhook được xoay vòng riêng, với khoảng chồng lấn 24 giờ của chính nó
  • Nếu bị lộ, hãy xoay vòng ngay

Trừ tiền một người dùng

Chỉ riêng khóa của bạn không thể làm Vito của người dùng dịch chuyển. Mọi lần trừ tiền đều cần người dùng phê duyệt bằng mã PIN ví của họ, trên vetox.io — không bao giờ trong ứng dụng của bạn và không bao giờ trong Discord.
1

Ứng dụng của bạn gọi POST /v1/deduct

Kèm người dùng, số tiền, guildId khởi phát và chi tiết mặt hàng.
2

Vito trả về một confirmUrl

Một xác nhận đang chờ, có hiệu lực 10 phút. Người dùng cũng nhận được tin nhắn riêng.
3

Người dùng phê duyệt bằng mã PIN

Trên vetox.io.
4

Vito quyết toán và thông báo

Số dư bị trừ, giao dịch được ghi lại, và một webhook có chữ ký được gửi đi nếu bạn đã cấu hình.
5

Ứng dụng của bạn xác minh và hoàn tất

Kiểm tra chữ ký, rồi mở khóa nội dung hoặc giao mặt hàng.
Chỉ hoàn tất hành động của bạn khi có confirmation.completed — đừng bao giờ dựa vào phản hồi của /deduct. Ở thời điểm đó khoản trừ chưa phải là cuối cùng.

Tham số yêu cầu — /v1/deduct

Cộng Vito cho người dùng

POST /v1/add cộng Vito cho một người dùng từ số dư của chính bạn — để thưởng hoặc hoàn tiền. Cùng các trường như /deduct, trừ guildIdproduct.
Khác với khoản trừ, khoản cộng không có bước xác nhận — nó được quyết toán ngay. Cần scope credit:create và đủ số dư, nếu không lệnh gọi trả về 402 VITO_INSUFFICIENT_OWNER_FUNDS.

Phí

Mỗi khoản trừ được quyết toán cho bạn sau khi trừ phí nền tảng — cùng biểu phí với chuyển Vito trong ứng dụng, dựa trên cấp Hội viên của bạn:
Các khoản 5 Vito trở xuống được miễn phí, và khoản cộng qua /v1/add thì luôn miễn phí.

Webhook

Thêm một hoặc nhiều URL callback https ở tab cài đặt. Vito gửi một POST có chữ ký mỗi khi một xác nhận đạt tới trạng thái cuối.
Webhook chỉ được gửi khi dự án của bạn có cả URL callback khóa bí mật ký. Hãy hiện khóa bí mật (whsec_…) một lần duy nhất từ tab khóa API.

Xác minh chữ ký

Mỗi lần gửi đều kèm header X-Vito-Signature:
Hai header khác đi kèm mỗi lần gửi — hãy dùng X-Vito-Event-Id làm khóa chống trùng lặp, vì lần thử lại sẽ gửi đúng id đó:
Trong lúc xoay vòng khóa bí mật ký, header mang nhiều hơn một chữ ký, mới nhất trước:
Hãy chấp nhận nếu bất kỳ h1 nào khớp. Bộ xác minh chỉ đọc cái đầu tiên sẽ từ chối mọi webhook cho tới khi triển khai xong khóa mới — đúng thứ mà khoảng chồng lấn 24 giờ sinh ra để tránh.
Tính lại HMAC trên <ts>:<rawBody> bằng khóa bí mật ký của bạn và so sánh trong thời gian hằng số.
Hãy xác minh trên body thô, trước khi việc phân tích JSON hay middleware viết lại nó.

Sự kiện

Năm loại sự kiện, tất cả dùng chung một dạng payload. data.status mang kết quả.
Webhook được thử lại 5 lần với thời gian chờ tăng dần. Hãy phản hồi 2xx thật nhanh và xử lý giao hàng theo cách bất đồng bộ.

Mã lỗi

Mọi phản hồi đều được bọc trong một phong bì. Thành công mang data, thất bại mang error, không bao giờ có cả hai:
Mọi mã đều có tiền tố VITO_. Hãy so khớp toàn bộ chuỗi — một RATE_LIMITED hay FORBIDDEN trần trụi không bao giờ xuất hiện trong phản hồi.

Giới hạn tần suất

Còn có giới hạn theo từng IP bằng một nửa hạn mức mỗi phút của bạn, với mức sàn là 30.
Khi tải cao, các endpoint ghi thất bại theo hướng đóng — khoản trừ bị từ chối thay vì mạo hiểm chi tiêu trùng. Các endpoint đọc thất bại theo hướng mở. Hãy coi một thao tác ghi bị từ chối là “chưa xảy ra” và thử lại.
Gửi header Idempotency-Key để chống trùng lặp khi thử lại một cách an toàn.

Endpoint

Hạn mức

  • Xác nhận hết hạn sau 10 phút — hãy coi các yêu cầu chưa xác nhận là đã bỏ dở
  • amount phải là số nguyên dương
  • metadata giới hạn ở 10 khóa
  • Trần mỗi giao dịch và trần hằng ngày do đội ngũ Vetox đặt và chỉ hiển thị ở chế độ đọc trong tab cài đặt

Danh sách kiểm tra bảo mật

Khóa API và khóa bí mật ký không bao giờ thuộc về mã phía client. Hãy xoay vòng ngay nếu một trong hai bị lộ.
Kiểm tra chữ ký trên body thô và từ chối những lần gửi cũ hơn ~5 phút.
Đừng bao giờ giao hàng dựa trên phản hồi /deduct — khoản trừ chỉ là cuối cùng khi có confirmation.completed.
Chỉ xin những scope bạn thực sự dùng, và bật danh sách IP cho phép.

Khắc phục sự cố

Hội viên của chủ sở hữu đã hết hạn. Nó được kiểm tra lại ở mọi lệnh gọi.
Không thể khôi phục — chỉ một bản băm được lưu. Hãy xoay vòng để lấy khóa mới.
Hãy chấp nhận cả hai khóa bí mật trong khoảng chồng lấn 24 giờ.
Người dùng đã không phê duyệt. Xác nhận hết hạn sau 10 phút.
Một dự án cần cả URL callback lẫn khóa bí mật ký. Chỉ có một trong hai thì không có gì được gửi đi.
Đó là phí quyết toán. Dùng các khoản 5 Vito trở xuống để tránh nó, hoặc tính nó vào giá của bạn.
/v1/add được chi trả từ số dư của chính bạn, không phải tạo ra từ hư không. Hãy nạp thêm.

Vito

Số dư, mã PIN và phí.

Yêu cầu thanh toán

Những gì người dùng thấy khi bạn trừ tiền họ.