API Documentation v2.0
BOM.ASIA API
Tài liệu hướng dẫn tích hợp ZNS, TopUp và các API khác. RESTful JSON API với JWT authentication.
Authentication & Authorization
BOM.ASIA API v2 sử dụng JWT Bearer Token authentication. Bạn cần login bằng secret key để lấy access token.
1
Lấy Secret Key
Đăng nhập và vào My API Dashboard để lấy Secret Key. Format: sk_live_xxxxxxxxxxxxx
⚠️ Bảo mật: Không chia sẻ Secret Key của bạn. Nếu bị lộ, hãy tạo lại API key ngay lập tức.
2
Login để lấy Access Token
Gọi endpoint POST /api/v2/auth/login với secret key:
Request
POST https://bom.asia/api/v2/auth/login
Content-Type: application/json
{
"secret_key": "sk_live_xxxxxxxxxxxxx"
}
Response
{
"success": true,
"data": {
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
"refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
"expires_in": 3600,
"token_type": "bearer"
}
}
3
Sử dụng Bearer Token trong requests
Thêm header Authorization: Bearer {access_token} vào mỗi API request:
cURL
curl -X POST https://bom.asia/api/v2/zns/send \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..." \
-H "Content-Type: application/json" \
-d '{"phone": "0987654321", "template_id": "494686"}'
PHP
$ch = curl_init('https://bom.asia/api/v2/zns/send');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer ' . $accessToken,
'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($ch);
JavaScript
const response = await fetch('https://bom.asia/api/v2/zns/send', {
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(data)
});
Python
import requests
response = requests.post(
'https://bom.asia/api/v2/zns/send',
headers={'Authorization': f'Bearer {access_token}'},
json=data
)
4
Rate Limits & Security
- Rate Limit: Mặc định 1000 requests/hour
- Endpoint Permissions: Admin có thể cấp quyền truy cập từng endpoint
- IP Whitelist: Giới hạn API key chỉ hoạt động từ các IP được phép
- Vào Dashboard → API → Edit Key để cấu hình
- Nhập danh sách IP cách nhau bằng dấu phẩy:
192.168.1.1, 10.0.0.1 - Để trống = cho phép tất cả IP
- Nếu IP không trong whitelist sẽ nhận lỗi
INVALID_CREDENTIALS
- Expiry Date: Có thể đặt ngày hết hạn cho API key
Error Codes Reference
Danh sách đầy đủ các mã lỗi có thể xảy ra khi gọi BOM.ASIA API.
Authentication Errors
| Error Code | HTTP | Mô tả | Giải pháp |
|---|---|---|---|
| INVALID_CREDENTIALS | 401 | Secret key không hợp lệ hoặc IP không được phép | ✓ Kiểm tra secret key và IP whitelist từ dashboard |
| IP_NOT_ALLOWED | 401 | IP của bạn không nằm trong whitelist | ✓ Thêm IP vào whitelist trong Dashboard → API → Edit Key |
| TOKEN_EXPIRED | 401 | Access token đã hết hạn | ✓ Dùng refresh token để lấy token mới |
| PERMISSION_DENIED | 403 | Không có quyền truy cập | ✓ Liên hệ admin để cấp quyền |
| RATE_LIMIT_EXCEEDED | 429 | Vượt quá giới hạn request | ✓ Đợi và thử lại (xem Retry-After) |
ZNS API Errors
📖 Nguồn tham khảo: Zalo ZNS Error Codes
| Error Code | HTTP | Mô tả | Giải pháp |
|---|---|---|---|
| TEMPLATE_NOT_FOUND | 404 | Template không tồn tại | ✓ Kiểm tra template ID |
| INSUFFICIENT_BALANCE | 402 | Số dư không đủ | ✓ Nạp tiền vào ví ZNS |
| -124 | 400 | Template not found (Zalo) | ✓ Template chưa được duyệt |
| -125 | 400 | Template data invalid | ✓ Kiểm tra template_data params |
| -126 | 400 | Invalid phone number | ✓ Format: 84xxxxxxxxx |
TopUp API Errors
| Error Code | HTTP | Mô tả | Giải pháp |
|---|---|---|---|
| INSUFFICIENT_BALANCE | 402 | Số dư không đủ | ✓ Nạp tiền vào ví TopUp |
| INVALID_PHONE_NUMBER | 400 | SĐT không hợp lệ | ✓ 10 số, bắt đầu 03/05/07/08/09 |
| INVALID_AMOUNT | 400 | Mệnh giá không hợp lệ | ✓ 10k, 20k, 50k, 100k, 200k, 500k |
| TOPUP_PROCESSING | 200 | Đang xử lý | ✓ Đợi callback hoặc check status |
| TOPUP_FAILED | 400 | Nạp thất bại | ✓ Tiền hoàn lại tự động |
ZNS API
Send Zalo Notification Service messages
TopUp API
Buy mobile topup for all carriers
Rate Limits
1000 requests/hour (customizable)
Support
support@bom.asia