Tài liệu API - OTP Phone

Xác thực (Authentication)

Tất cả API đều yêu cầu Access Token trong header. Lấy token tại trang Tài khoản.

Header bắt buộc

Authorization: Bearer your_access_token_here

Token chỉ hiển thị 1 lần khi tạo. Nếu quên, hãy tạo token mới tại trang Tài khoản.

Base URL

https://chenglongstore.com/api/v1

Endpoints

GET

/api/v1/otp-phone/services

Lấy danh sách dịch vụ OTP khả dụng kèm giá.

Example Request

cURL

curl "https://chenglongstore.com/api/v1/otp-phone/services" \
  -H "Authorization: Bearer your_access_token_here"

Response

Thành công

{
  "success": true,
  "data": [
    { "id": "1", "serviceName": "Facebook", "price": 2500 },
    { "id": "2", "serviceName": "Gmail", "price": 3000 },
    { "id": "3", "serviceName": "Zalo", "price": 1500 }
  ]
}

Lỗi

{
  "success": false,
  "message": "Unauthorized"
}

POST

/api/v1/otp-phone/buy

Thuê một số điện thoại để nhận mã OTP.

Request Body

Key	Type	Required	Description
serviceId	string	Yes	ID dịch vụ (ví dụ: Facebook, Gmail...)
carrier	string	Yes	Nhà mạng: ALL, VINA, VIETTEL, MOBI. Mặc định: ALL

Example Request

cURL

curl -X POST https://chenglongstore.com/api/v1/otp-phone/buy \
  -H "Authorization: Bearer your_access_token_here" \
  -H "Content-Type: application/json" \
  -d '{"serviceId": "1", "carrier": "ALL"}'

Response

Thành công

{
  "success": true,
  "data": {
    "requestId": "RID_1234567890_abc",
    "phoneNum": "0912345678",
    "price": 2500,
    "ttl": 300,
    "message": "successful"
  }
}

Lỗi

{
  "success": false,
  "message": "Không đủ số dư"
}

GET

/api/v1/otp-phone/getcode

Lấy mã OTP cho số đã thuê. Poll endpoint này mỗi 5 giây cho đến khi nhận được code hoặc hết TTL.

Parameters

Key	Type	Required	Description
requestId	string (query)	Yes	Request ID nhận được khi thuê số

Example Request

cURL

curl "https://chenglongstore.com/api/v1/otp-phone/getcode?requestId=RID_xxx" \
  -H "Authorization: Bearer your_access_token_here"

Response

Thành công

{
  "success": true,
  "status": "SUCCESS",
  "code": "123456",
  "phoneNum": "0912345678"
}

Đang chờ

{
  "success": true,
  "status": "PENDING",
  "code": null,
  "phoneNum": "0912345678",
  "message": "Code chưa sẵn sàng, thử lại sau",
  "retryAfter": 5,
  "remainingSeconds": 245
}

Lỗi

{
  "success": false,
  "status": "EXPIRED",
  "code": null,
  "phoneNum": "0912345678",
  "message": "Đã hết thời gian lấy code"
}

Mã lỗi thường gặp

HTTP Code	Ý nghĩa	Cách xử lý
401	Token không hợp lệ hoặc hết hạn	Kiểm tra lại Access Token
400	Thiếu tham số bắt buộc	Kiểm tra body/query params
404	Không tìm thấy đơn hàng	Kiểm tra requestId
500	Lỗi hệ thống	Thử lại sau hoặc liên hệ hỗ trợ