Trang chủ

Tài liệu API thuê SMS

API cho phép khách hàng tự động hóa quy trình thuê số điện thoại, nhận mã xác thực OTP, hủy đơn và tra cứu lịch sử đơn hàng trực tiếp qua mã API key cá nhân của tài khoản Kho MMO 247.

Base URL: ... JSON response Bearer token
Lưu ý bảo mật: API Key chỉ được hiển thị một lần duy nhất khi khởi tạo trên website. Trong trường hợp mã bị lộ, hãy vô hiệu hóa key cũ ngay lập tức và tạo một API Key mới trong mục Công cụ thuê SMS.

Xác thực

Tất cả các API yêu cầu xác thực bằng cách truyền API Key trong header Authorization dưới dạng Bearer token (Khuyên dùng).

Authorization: Bearer khmmo_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Khi chạy kiểm tra nhanh trên trình duyệt, bạn cũng có thể truyền tạm thời qua tham số URL query api_key.

...
GET /api/sms/v1/me

Kiểm tra tài khoản

Xác thực tính hợp lệ của API key, lấy thông tin cá nhân và số dư khả dụng hiện tại.

curl -H "Authorization: Bearer khmmo_live_xxx" "{{BASE}}/me"
GET /api/sms/v1/services

Danh sách dịch vụ

Lấy danh sách tất cả các ứng dụng, dịch vụ đang được hỗ trợ thuê số SMS (Telegram, Gmail, Facebook...).

curl -H "Authorization: Bearer khmmo_live_xxx" "{{BASE}}/services"
GET /api/sms/v1/countries

Danh sách quốc gia theo dịch vụ

Truy xuất danh sách mã quốc gia, số lượng số đang có sẵn và đơn giá thuê tương ứng với từng dịch vụ cụ thể.

curl -H "Authorization: Bearer khmmo_live_xxx" "{{BASE}}/countries?service=tg"
POST /api/sms/v1/buy-number

Thuê số mới

Tiến hành thuê một số điện thoại mới. Hệ thống sẽ tự động trừ số dư tương ứng trong ví tài khoản Kho MMO 247.

curl -X POST -H "Authorization: Bearer khmmo_live_xxx" \
-H "Content-Type: application/json" \
-d '{"service": "tg", "country": "0"}' \
"{{BASE}}/buy-number"
GET /api/sms/v1/status

Kiểm tra trạng thái & Lấy OTP

Theo dõi tiến trình nhận mã của số điện thoại đã thuê qua mã giao dịch `order_id` để lấy mã OTP.

curl -H "Authorization: Bearer khmmo_live_xxx" "{{BASE}}/status?order_id=123456"
POST /api/sms/v1/cancel

Hủy thuê số

Hủy yêu cầu thuê số khi đơn đang ở trạng thái chờ nhận mã. Chỉ được phép hủy sau tối thiểu 2 phút kể từ khi tạo đơn.

curl -X POST -H "Authorization: Bearer khmmo_live_xxx" \
-H "Content-Type: application/json" \
-d '{"order_id": 123456}' \
"{{BASE}}/cancel"
GET /api/sms/v1/orders

Lịch sử đơn thuê

Tra cứu danh sách các đơn hàng thuê số gần đây của tài khoản để tiện quản lý và theo dõi.

curl -H "Authorization: Bearer khmmo_live_xxx" "{{BASE}}/orders?limit=20"

Bảng tham số truyền

Tham số Bắt buộc Mô tả Ví dụ
api_key Khi dùng URL Query Mã bảo mật API key của tài khoản. Nên gửi bằng Header Bearer khi lập trình. khmmo_live_xxx
service Có (Khi mua/lấy quốc gia) Mã ký hiệu của dịch vụ cần thuê số (lấy ở danh sách dịch vụ). tg (Telegram)
country Có (Khi mua số) Mã định danh quốc gia được lấy từ endpoint countries. 0 (Việt Nam)
order_id Có (Với status/cancel) Mã giao dịch của đơn hàng thuê số được trả về khi mua số thành công. 123456
limit Không (Mặc định: 20) Số lượng đơn hàng muốn lấy ra trong lịch sử đơn thuê. 20

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

HTTP Status Mã lỗi (code) Ý nghĩa và cách khắc phục
401 Unauthorized invalid_api_key API Key không hợp lệ, đã bị khóa hoặc không được truyền lên đúng cách.
400 Bad Request missing_service Thiếu tham số mã dịch vụ (service) trong yêu cầu.
400 Bad Request missing_country Thiếu mã quốc gia (country) khi thực hiện mua số.
402 Payment Required insufficient_balance Số dư trong ví tài khoản Kho MMO 247 không đủ để thực hiện giao dịch này.
403 Forbidden cannot_cancel_yet Không thể hủy đơn trước hạn tối thiểu (cần đợi đủ 2 phút để hủy đơn).

Trình thử nghiệm API (Console)

Bạn có thể thử nghiệm trực tiếp các Endpoint API tại đây bằng cách điền API Key cá nhân của mình.

Kết quả sẽ được trả về dạng JSON tại đây...