Tài liệu API tích hợp

Tổng quan #

Ý tưởng: thay vì nhân viên copy-paste lệnh nạp lên bangiftcode.com, hệ thống nhận đơn qua API, đẩy vào hàng đợi, worker login + giải captcha + submit, ghi kết quả vào DB và gọi callback về website của bạn.

Luồng xử lý

1. Website của bạn POST /api/order/create → trả lại order_id + status: queued.
2. Worker pick đơn → đăng nhập bangiftcode (cached session) → fetch captcha → solve → submit topup.
3. Khi xong: cập nhật status + bgc_topup_id trong DB; nếu có callback_url → POST kết quả về.
4. Website tự xác minh + trả lượng cho khách. external_id bảo đảm idempotent (gửi lại không bị nạp 2 lần).

Authentication #

Mỗi request phải kèm API key. Có 2 cách:

Cách 1 — Header (khuyên dùng)

curl -H "X-API-Key: bgc_xxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     "https://topup.accnro.vn/api/me"

Cách 2 — Query string (tiện debug, chú ý log)

curl "https://topup.accnro.vn/api/me?key=bgc_xxxxxxxxxxxxxxxxxxxxxxxxxxx"

IP Whitelist (tùy chọn nhưng nên bật)

Trong dashboard, mỗi user có thể thêm IP / CIDR được phép gọi API. Nếu để trống = không giới hạn IP. Web UI luôn vào được bằng cookie session đăng nhập.

Quickstart — gửi đơn đầu tiên #

1. Đăng nhập dashboard → tab Tích hợp API.
2. Copy API key (định dạng bgc_xxx...).
3. Cấu hình Tài khoản bangiftcode (username + password của bạn trên BANGIFTCODE.COM) — bot sẽ login bằng creds này.
4. (Tùy chọn) Set IP whitelist cho IP server backend của bạn.
5. Gọi endpoint /api/order/create:

curl "https://topup.accnro.vn/api/order/create" \
  -H "X-API-Key: bgc_xxx..." \
  --data-urlencode "game=nr" \
  --data-urlencode "server=21" \
  --data-urlencode "account=customer@gmail.com" \
  --data-urlencode "price=10000" \
  --data-urlencode "external_id=acc_001" \
  --data-urlencode "callback_url=https://accnro.vn/api/cb" \
  -G

<?php
$ch = curl_init();
$params = http_build_query([
    'key'          => 'bgc_xxx...',
    'game'         => 'nr',
    'server'       => '21',
    'account'      => 'customer@gmail.com',
    'price'        => 10000,
    'external_id'  => 'acc_001',
    'callback_url' => 'https://accnro.vn/api/cb',
]);
curl_setopt($ch, CURLOPT_URL, "https://topup.accnro.vn/api/order/create?" . $params);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$resp = json_decode(curl_exec($ch), true);
echo $resp['id']; // order_id để tra cứu sau

const resp = await fetch(
  'https://topup.accnro.vn/api/order/create?' + new URLSearchParams({
    key:          'bgc_xxx...',
    game:         'nr',
    server:       '21',
    account:      'customer@gmail.com',
    price:        10000,
    external_id:  'acc_001',
    callback_url: 'https://accnro.vn/api/cb',
  })
);
const order = await resp.json();
console.log(order.id, order.status); // 42 "queued"

Response 200:

{
  "id": 42,
  "external_id": "acc_001",
  "status": "queued",
  "game": "nr", "server": "21",
  "account": "customer@gmail.com",
  "price": 10000, "amount": 1,
  "created_at": "2026-05-09T17:30:00Z",
  "callback_url": "https://accnro.vn/api/cb"
}

Endpoints chi tiết

Mọi endpoint dưới đây đều cần API key. {token} trong URL = chỗ thay bằng giá trị thật.

Trạng thái đơn #

Đơn đi qua: queued → processing → success | failed | cancelled.

Idempotency #

Mỗi đơn nên có external_id duy nhất từ phía bạn (vd. "order_2026_001").

• Gửi lại request với cùng external_id + cùng user → KHÔNG tạo đơn mới, trả lại đơn cũ kèm field "_idempotent": true.
• Hữu ích khi network timeout — bạn cứ retry, không sợ nạp 2 lần.
• Trong 1 user, external_id phải duy nhất. Khác user thì OK.

Callback / Webhook #

Khi đơn xong (status đổi sang success hoặc failed), bot POST JSON về callback_url:

Body

{
  "order_id": 42,
  "external_id": "acc_001",
  "status": "success",
  "ok": true,
  "attempts": 1,
  "server_message": "Bạn đã nạp 13 lượng vào tài khoản customer@gmail.com",
  "bgc_topup_id": "1001053"
}

Yêu cầu phía bạn

• Endpoint phải HTTPS, public, không xác thực phức tạp (bot chỉ POST plain JSON).
• Phản hồi 2xx trong <10s — bot không retry callback.
• Xác minh đơn bằng cách GET lại /api/order/{id} trước khi cộng lượng cho khách.

Bot block IP private / metadata (169.254.169.254) trong callback_url để chống SSRF.

Mã lỗi HTTP #

Format response lỗi

{
  "detail": "invalid price 5000; valid: [10000, 20000, 50000, ...]"
}

Bảo mật #

• HTTPS bắt buộc — mọi request đều TLS 1.2+, HSTS preloaded.
• API key dạng SHA-256 hash trong DB — không thể truy ngược nếu DB bị lộ. Plain text chỉ hiển thị 1 lần lúc tạo / sinh lại.
• Session cookie HMAC-signed — không thể giả mạo.
• SSRF guard trên callback_url: chặn private IPs (10.x, 172.16-31.x, 192.168.x), loopback, link-local, AWS metadata 169.254.169.254.
• Per-user IP whitelist — nên enable cho production.
• Rate limit nginx: ~50 req/s per IP, burst 100. Vượt giới hạn → 429.
• PBKDF2-SHA256 100k iterations cho mật khẩu user.

Khi key bị lộ

1. Đăng nhập dashboard → tab Tích hợp API.
2. Bấm icon ↻ bên cạnh API key.
3. Key cũ vô hiệu ngay lập tức. Cập nhật key mới vào backend của bạn.