Tài liệu Developer

Tài liệu API & Hướng dẫn Tích hợp

Tất cả API đều dùng phương thức GET cho dễ tích hợp.

Dễ dàng tích hợp vào phần mềm, tool tự động hóa hoặc hệ thống riêng. Hỗ trợ đầy đủ định dạng chuẩn REST JSON và giao thức một dòng URL tiện lợi.

Xác thực API (API Key)

Đăng nhập để xem và quản lý API Key của bạn.

Đăng nhập Đăng ký

Bước 1: Chọn dịch vụ

GET /prices?service=tg&country=vn

Kiểm tra số lượng và giá thấp nhất.

Bước 2: Mua số

GET /activations/create?service=tg&country=vn

Nhận số điện thoại và ID đơn hàng.

Bước 3: Nhận mã OTP

GET /activations/{id}

Hoặc nhận tự động qua Webhook.

Bước 4: Hoàn thành

GET /activations/{id}/complete

Đóng đơn sau khi nhập mã thành công.

Nếu không có OTP: Hủy

GET /activations/{id}/cancel

Tiền sẽ được tự động hoàn 100% vào ví.

Bước 1: Xem giá Email

GET /mail-prices?service=openai

Kiểm tra domain và mức giá.

Bước 2: Mua Email

GET /mail-activations/create?service=openai

Nhận địa chỉ email tạm thời.

Bước 3: Lấy mã OTP Mail

GET /mail-activations/{id}

Lấy mã xác nhận từ hòm thư.

Bước 4: Hoàn thành / Hủy

GET /mail-activations/{id}/complete

Hoặc gọi cancel để nhận lại tiền.

Xem file JSON

01 Import vào Postman / Insomnia:

Mở ứng dụng Postman hoặc Insomnia.
Bấm nút Import ở góc trên bên trái.
Dán đường link URL OpenAPI ở trên vào và bấm Import.
Toàn bộ 21 API kèm tham số mẫu sẽ được tạo tự động trong 1 Collection.

02 Tự động sinh Client SDK:

Dùng CLI để tự sinh mã nguồn client cho dự án (Python, TypeScript, PHP, Go, C#...):

npx @openapitools/openapi-generator-cli generate \
  -i https://36otp.com/openapi.json?locale=vi \
  -g python -o ./sms-client

Kiểm tra số dư tài khoản (Balance)

Kiểm tra số dư ví USD

Tham số

Tham số	Loại	Bắt buộc	Mô tả
api_key	string	Không	API Key của bạn (có thể truyền qua query ?api_key=... hoặc header X-API-Key)

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": {
    "balance": "100.500000",
    "currency": "USD"
  }
}

Danh mục dịch vụ SMS

Danh sách dịch vụ SMS hỗ trợ

Tham số

Tham số	Loại	Bắt buộc	Mô tả
search	string	Không	Từ khóa tìm kiếm theo tên hoặc mã dịch vụ (ví dụ: telegram, tg, whatsapp)

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": [
    {
      "id": 1,
      "code": "tg",
      "name": "Telegram",
      "popular_rank": 1
    }
  ]
}

Danh sách quốc gia hỗ trợ

Tham số

Tham số	Loại	Bắt buộc	Mô tả
search	string	Không	Từ khóa tìm kiếm theo tên hoặc mã quốc gia (ví dụ: vietnam, vn)

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": [
    {
      "id": 1,
      "code": "vn",
      "name": "Vietnam",
      "phone_code": "84"
    }
  ]
}

Bảng giá SMS theo dịch vụ và quốc gia

Tham số

Tham số	Loại	Bắt buộc	Mô tả
service	string	Không	Mã dịch vụ (ví dụ: tg, wa)
country	string	Không	Mã quốc gia (ví dụ: vn, us, id)

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": [
    {
      "service": "tg",
      "country": "vn",
      "price": "0.250000",
      "currency": "USD",
      "count": 142
    }
  ]
}

Chi tiết offers theo từng nhà mạng / provider

Tham số

Tham số	Loại	Bắt buộc	Mô tả
service	string	Có	Mã dịch vụ (ví dụ: tg)
country	string	Có	Mã quốc gia (ví dụ: vn)

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": [
    {
      "provider": "telecom_vn",
      "price": "0.250000",
      "count": 95
    }
  ]
}

Đơn thuê số SMS

Danh sách các đơn thuê số SMS của bạn

Tham số

Tham số	Loại	Bắt buộc	Mô tả
status	string	Không	Lọc theo trạng thái: pending, ready, code_received, completed, cancelled
page	integer	Không	Số trang (mặc định 1)
per_page	integer	Không	Số lượng mỗi trang (mặc định 15, tối đa 50)

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": [
    {
      "id": "act_9a8b7c6d5e",
      "service": "tg",
      "country": "vn",
      "phone_number": "84987654321",
      "status": "code_received",
      "price": "0.250000",
      "last_code": "123456",
      "expires_at": "2026-09-11T12:00:00Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "total": 1 }
}

Thuê số SMS mới (Đặt mua số)

Tham số

Tham số	Loại	Bắt buộc	Mô tả
service	string	Có	Mã dịch vụ (ví dụ: tg, wa, google)
country	string	Có	Mã quốc gia (ví dụ: vn, us)
provider	string	Không	Mã nhà mạng lấy từ /api/v1/offers (ví dụ: 3193). Khi chỉ định, hệ thống thuê đúng nhà mạng này với đúng giá của offer; nếu nhà mạng hết số sẽ trả NO_NUMBERS thay vì tự chuyển sang nhà mạng khác
max_price	string	Không	Giá bán tối đa bạn chấp nhận trả (theo bảng giá của hệ thống, ví dụ: 0.30)

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": {
    "id": "act_9a8b7c6d5e",
    "service": "tg",
    "country": "vn",
    "phone_number": "84987654321",
    "status": "pending",
    "price": "0.250000",
    "currency": "USD",
    "expires_at": "2026-09-11T12:00:00Z"
  }
}

Chi tiết đơn & Lấy mã OTP SMS

Tham số

Tham số	Loại	Bắt buộc	Mô tả
activation	string	Có	ID của đơn thuê (ví dụ: act_9a8b7c6d5e)

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": {
    "id": "act_9a8b7c6d5e",
    "status": "code_received",
    "phone_number": "84987654321",
    "last_code": "123456",
    "messages": [
      {
        "code": "123456",
        "text": "Telegram code 123456",
        "received_at": "2026-09-11T11:45:00Z"
      }
    ]
  }
}

Báo sẵn sàng nhận tin nhắn

Tham số

Tham số	Loại	Bắt buộc	Mô tả
activation	string	Có	ID đơn thuê

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": {
    "id": "act_9a8b7c6d5e",
    "status": "ready"
  }
}

Yêu cầu gửi lại mã SMS mới (lần 2)

Tham số

Tham số	Loại	Bắt buộc	Mô tả
activation	string	Có	ID đơn thuê

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": {
    "id": "act_9a8b7c6d5e",
    "status": "ready"
  }
}

Hoàn thành đơn thuê số

Tham số

Tham số	Loại	Bắt buộc	Mô tả
activation	string	Có	ID đơn thuê

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": {
    "id": "act_9a8b7c6d5e",
    "status": "completed"
  }
}

Hủy đơn thuê & Hoàn tiền vào ví USD

Tham số

Tham số	Loại	Bắt buộc	Mô tả
activation	string	Có	ID đơn thuê

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": {
    "id": "act_9a8b7c6d5e",
    "status": "cancelled",
    "refunded": true,
    "refund_amount": "0.250000"
  }
}

Danh mục dịch vụ Email

Danh mục dịch vụ Email hỗ trợ

Tham số

Tham số	Loại	Bắt buộc	Mô tả
search	string	Không	Từ khóa tìm kiếm (ví dụ: openai, discord)

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": [
    {
      "id": 12,
      "code": "openai",
      "name": "OpenAI / ChatGPT"
    }
  ]
}

Danh sách domain email sẵn có

Tham số

Tham số	Loại	Bắt buộc	Mô tả
service	string	Không	Lọc theo mã dịch vụ

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": [
    {
      "id": 1,
      "domain": "mailto.plus"
    }
  ]
}

Bảng giá dịch vụ Email

Tham số

Tham số	Loại	Bắt buộc	Mô tả
service	string	Không	Mã dịch vụ (ví dụ: openai)
domain	string	Không	Domain email cụ thể

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": [
    {
      "service": "openai",
      "domain": "mailto.plus",
      "price": "0.100000",
      "count": 850
    }
  ]
}

Đơn thuê Email

Danh sách đơn thuê Email của bạn

Tham số

Tham số	Loại	Bắt buộc	Mô tả
status	string	Không	Lọc trạng thái: pending, ready, code_received, completed, cancelled
page	integer	Không	Số trang (mặc định 1)

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": [
    {
      "id": "mact_11223344",
      "service": "openai",
      "email_address": "[email protected]",
      "status": "code_received",
      "price": "0.100000"
    }
  ]
}

Thuê Email mới

Tham số

Tham số	Loại	Bắt buộc	Mô tả
service	string	Có	Mã dịch vụ email (ví dụ: openai, discord)
domain	string	Không	Domain mong muốn (tùy chọn)
quantity	integer	Không	Số lượng muốn thuê (1-100, mặc định 1)
max_price	string	Không	Mức giá tối đa chấp nhận (ví dụ: 0.15)

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": {
    "id": "mact_11223344",
    "service": "openai",
    "email_address": "[email protected]",
    "status": "pending",
    "price": "0.100000",
    "currency": "USD",
    "expires_at": "2026-09-11T12:00:00Z"
  }
}

Chi tiết đơn email & Lấy mã OTP

Tham số

Tham số	Loại	Bắt buộc	Mô tả
mailActivation	string	Có	ID đơn thuê email (ví dụ: mact_11223344)

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": {
    "id": "mact_11223344",
    "status": "code_received",
    "email_address": "[email protected]",
    "last_code": "859402",
    "messages": [
      {
        "code": "859402",
        "subject": "Your OpenAI verification code",
        "from": "[email protected]",
        "received_at": "2026-09-11T11:48:00Z"
      }
    ]
  }
}

Yêu cầu nhận lại email mới

Tham số

Tham số	Loại	Bắt buộc	Mô tả
mailActivation	string	Có	ID đơn thuê email

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": {
    "id": "mact_11223344",
    "status": "ready"
  }
}

Hoàn thành đơn thuê email

Tham số

Tham số	Loại	Bắt buộc	Mô tả
mailActivation	string	Có	ID đơn thuê email

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": {
    "id": "mact_11223344",
    "status": "completed"
  }
}

Hủy đơn email & Hoàn tiền vào ví USD

Tham số

Tham số	Loại	Bắt buộc	Mô tả
mailActivation	string	Có	ID đơn thuê email

Đường dẫn gọi API (Full Request URL)

Mở trình duyệt

Response mẫu

{
  "data": {
    "id": "mact_11223344",
    "status": "cancelled",
    "refunded": true,
    "refund_amount": "0.100000"
  }
}

Webhook nhận mã tự động

Real-time Push

⚡ Dùng Webhook thay vì polling

Thay vì gọi API liên tục để kiểm tra OTP (tốn rate limit, tăng latency), hãy đăng ký Webhook để nhận mã ngay lập tức khi có. Tiết kiệm 95% số lần gọi API.

Xác minh chữ ký (Signature Verification)

Mỗi webhook gửi đi đều chứa header X-OTP-Signature được tính bằng HMAC-SHA256 của timestamp + "." + body:

<?php
$secret = 'YOUR_WEBHOOK_SECRET';
$timestamp = $_SERVER['HTTP_X_OTP_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_OTP_SIGNATURE'] ?? '';
$payload = file_get_contents('php://input');

$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($payload, true);
// Xử lý OTP: $data['activation']['last_code']
http_response_code(200);
echo json_encode(['received' => true]);

import hmac
import hashlib

def verify_webhook(request_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    signed_payload = f"{timestamp}.".encode() + request_body
    expected = "sha256=" + hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

# Flask / FastAPI:
# is_valid = verify_webhook(await request.body(), request.headers.get("X-OTP-Timestamp"), request.headers.get("X-OTP-Signature"), WEBHOOK_SECRET)

const crypto = require('crypto');

function verifyWebhook(bodyBuffer, timestamp, signatureHeader, secret) {
    const expected = 'sha256=' + crypto.createHmac('sha256', secret)
        .update(`${timestamp}.${bodyBuffer.toString()}`)
        .digest('hex');
    return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

// Express:
// const valid = verifyWebhook(req.rawBody, req.headers['x-otp-timestamp'], req.headers['x-otp-signature'], process.env.WEBHOOK_SECRET);

Danh sách Events

Event	Mô tả
activation.created	Đơn thuê số SMS mới được khởi tạo thành công.
sms.received	Tin nhắn SMS chứa mã OTP vừa gửi đến số điện thoại.
activation.completed	Đơn thuê số hoàn tất thành công.
activation.cancelled	Đơn thuê số bị hủy và tiền hoàn vào ví.
mail_activation.code_received	Hòm thư email nhận được mã xác nhận OTP mới.

Retry Policy: Hệ thống thử lại 5 lần với backoff: ngay → 1 phút → 5 phút → 30 phút → 2 giờ.

Bảng mã lỗi API

Mô tả trạng thái đơn

pending	Đang chờ xử lý
ready	Sẵn sàng nhận mã
code_received	Đã nhận mã OTP
completed	Đã hoàn tất
cancelled	Đã hủy & Hoàn tiền

Bảng mã lỗi API

401 Unauthorized	API Key không hợp lệ hoặc đã bị vô hiệu hóa.
402 Payment Required	Số dư ví không đủ để thanh toán đơn hàng.
404 Not Found	Không tìm thấy đơn thuê hoặc dịch vụ tương ứng.
429 Too Many Requests	Vượt quá giới hạn gọi API (Rate Limit).

Tài liệu API & Hướng dẫn Tích hợp

Xác thực API (API Key)

Hướng dẫn nhanh: Thuê số & nhận OTP SMS

Hướng dẫn nhanh: Thuê email & nhận OTP email

OpenAPI 3.0 JSON Spec (Postman / Insomnia / SDK)

01 Import vào Postman / Insomnia:

02 Tự động sinh Client SDK:

Kiểm tra số dư tài khoản (Balance)

Danh mục dịch vụ SMS

Đơn thuê số SMS

Danh mục dịch vụ Email

Đơn thuê Email

Webhook nhận mã tự động

⚡ Dùng Webhook thay vì polling

Xác minh chữ ký (Signature Verification)

Danh sách Events

Bảng mã lỗi API

Mô tả trạng thái đơn

Bảng mã lỗi API

Cấu hình Webhook nhận mã

Lịch sử gửi gần nhất