Tài liệu API đại lý

URL gốc và giao thức truyền

Mọi path trong tài liệu này đều tính từ URL gốc bên dưới. Yêu cầu và phản hồi dùng JSON qua HTTPS. Số tiền là chuỗi để không bị sai số làm tròn số thực, còn mọi mốc thời gian đều theo UTC, định dạng ISO 8601.

https://shop2topup.com/api/endpoints/v1

Xác thực

Mỗi yêu cầu chỉ cần một header. Cặp key được cấp ở trang API Access trong trang quản lý đại lý và có thể giới hạn theo danh sách IP cho phép. Lời gọi từ địa chỉ khác sẽ bị từ chối với IP_NOT_ALLOWED trước khi đến phần xử lý nghiệp vụ.

Authorization: Bearer <keyId>.<secret>

Gọi API lần đầu

Không cần cài đặt gì. Thay bằng khóa API của bạn là lệnh này trả về dữ liệu danh mục thực tế.

curl -s "https://shop2topup.com/api/endpoints/v1/catalog/categories?bigCategoryId=1" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

Quy ước phản hồi

• Mọi phản hồi đều có trường boolean success, nên chỉ cần một nhánh điều kiện là tách được trường hợp thành công khỏi mọi lỗi.
• Khi lỗi, API trả về đối tượng error gồm mã lỗi cố định, thông báo dễ đọc và details (không bắt buộc). Hãy rẽ nhánh theo mã lỗi, đừng dựa vào thông báo.
• Số tiền luôn là chuỗi thập phân tính bằng USD, ví dụ "0.950000". Đừng chuyển sang kiểu float nhị phân trước khi so sánh hay cộng dồn.
• Các endpoint trả về danh sách đều kèm đối tượng pagination gồm page, limit, total và total_pages.
• Việc tạo đơn hàng có tính idempotent theo UUID order_id do bạn cung cấp, nên gửi lại yêu cầu sẽ không bao giờ bị trừ tiền hai lần.

{
  "success": false,
  "error": {
    "code": "PRICE_INCREASED",
    "message": "Price has increased beyond expected",
    "action": "FIX_INPUT",
    "retryable": false,
    "retry_after": null,
    "details": {
      "expected_unit_price": "0.950000",
      "current_unit_price": "0.980000"
    }
  }
}

Các mục tham khảo

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

Giới hạn tính theo từng tài khoản trong khung thời gian trượt. Các endpoint danh mục, đơn hàng và tài khoản trả về X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset; lệnh gọi bị giới hạn sẽ nhận 429 kèm header Retry-After. Riêng kiểm tra người chơi được tính theo hạn mức kiểm tra người chơi hằng ngày: không có header X-RateLimit, hạn mức được báo trong body của phản hồi 429.

Webhook

Kết quả đơn hàng được đẩy về endpoint HTTPS mà bạn đăng ký, có chữ ký HMAC-SHA256 tính trên body gốc. Danh sách sự kiện, danh sách header, cấu trúc payload và đoạn code mẫu để xác minh chữ ký đều có ở trang tổng quan API.