API xác minh SMS
API xác minh SMS chỉ gồm ba lệnh gọi: mua số, chờ mã, trả số. Nó chạm tới 517 dịch vụ tại 225 quốc gia, số bắt đầu từ 0,07 €, và một lượt kích hoạt không nhận được gì sẽ được hoàn tiền mà không cần phiếu hỗ trợ. Khóa có scope, việc mua là idempotent, và các client handler_api cũ vẫn chạy nguyên như trước.
Toàn bộ API trong một khối
Cập nhật 28 thg 8, 2026- URL gốc
- https://virtualsmsnumbers.com/api/v1
- Xác thực
- Bearer key, hoặc X-Api-Key
- Giới hạn tốc độ
- 120/phút, bùng 20/giây
- Cửa sổ idempotency
- 24 giờ
- Tự hoàn tiền sau
- 20 phút
- Kích hoạt rẻ nhất
- 0,07 €
- Quốc gia được phủ
- 225
- Định dạng
- JSON, xu, ISO 8601 UTC
Giá và tồn kho lấy từ kho số của nhà mạng đúng như hiện trạng, không phải từ một bảng giá công bố sẵn.
Luồng ba lệnh gọi
Mọi thứ khác trong tài liệu tham chiếu đều là tùy chọn. Đây là toàn bộ đường đi của một lần xác minh, và nó không đổi từ năm 2019.
- 1
POST /activations
Xin một dịch vụ, kèm quốc gia nếu bạn quan tâm đó là nước nào. Phản hồi mang theo số, giá tính bằng xu và dấu thời gian hết hạn. Hãy gửi Idempotency-Key để một yêu cầu thử lại không mua thêm số thứ hai, và gửi max_price_cents nếu bên gọi là tự động.
- 2
GET /activations/{id}?wait=180
Long poll. Kết nối được giữ mở cho tới khi tin nhắn về hoặc hết thời gian chờ, nên một yêu cầu thay được cả vòng lặp lẽ ra tốn chín mươi lần gọi. Trạng thái trả về là code_received kèm mã đã bóc tách bên cạnh phần văn bản thô, vì mỗi bên gửi lại trình bày một kiểu.
- 3
POST /activations/{id}/complete
Đóng lượt kích hoạt và trả thuê bao lại. Nếu không có gì về thì đừng làm gì cả: cửa sổ tự hết hạn và số dư được cộng lại. Hủy sớm cũng là đúng lệnh gọi đó dưới một cái tên khác.
Một ví dụ chạy được
Đặt VSN_KEY rồi chạy. Các phản hồi trong phần chú thích là hình dạng thật, gồm cả những trường bạn sẽ muốn lưu lại.
# 1. Buy a Telegram number in Portugal
-kw">curl -X POST https://virtualsmsnumbers.com/api/v1/activations \
-H "Authorization: Bearer $VSN_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"service":"telegram","country":"PT"}'
# {"id":"1043872915","phone_number":"351926114508","status":"waiting",
# "price_cents":11,"expires_at":"2026-08-26T12:41:07Z"}
# 2. Long-poll until the code lands (blocks up to 120 s)
-kw">curl "https://virtualsmsnumbers.com/api/v1/activations/1043872915?wait=120" \
-H "Authorization: Bearer $VSN_KEY"
# {"id":"1043872915","status":"code_received",
# "messages":[{"code":"48219","text":"Telegram code: 48219"}]}
# 3. Release the number
-kw">curl -X POST https://virtualsmsnumbers.com/api/v1/activations/1043872915/complete \
-H "Authorization: Bearer $VSN_KEY"Giới hạn tốc độ
120 yêu cầu mỗi phút cho mỗi khóa, bùng lên 20 yêu cầu mỗi giây. Mọi phản hồi đều mang X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset, còn 429 cho bạn biết phải chờ bao lâu thay vì bắt bạn đoán.
Giới hạn hiếm khi là nút thắt nếu API được dùng đúng cách: một long poll thay cho chín mươi lần hỏi, một webhook thay cho một bộ hẹn giờ, và danh sách quốc gia cùng dịch vụ được cache lúc khởi động. Nếu bạn thật sự cần dư địa lớn hơn, hãy nói — nâng giới hạn dễ hơn cho cả hai bên so với việc gỡ rối cả một loạt khóa.
Tính idempotent
Gửi header Idempotency-Key ở POST /activations. Phát lại cùng một khóa trong vòng 24 giờ sẽ trả về đúng lượt kích hoạt ban đầu ở trạng thái hiện tại, kèm header Idempotent-Replay, thay vì mua số thứ hai và tính tiền bạn hai lần.
Khóa không phải là hash của phần thân: một payload khác đi kèm một khóa đã dùng vẫn trả về lượt kích hoạt đầu tiên. Hãy sinh một khóa cho mỗi lần mua về mặt logic — một UUID là đủ — và dùng lại nó qua các lần thử, đừng dùng lại qua các lần mua.
Client handler_api cũ
Các script viết cho giao thức handler_api.php cổ điển vẫn chạy. Trỏ chúng sang endpoint tương thích, đổi api_key, và cùng những hành động đó vẫn trả về đúng các token ACCESS_ và STATUS_ như xưa.
Đó là một lớp dịch đặt trên cùng kho số, nên giá, tồn kho và hoàn tiền hành xử y hệt nhau ở cả hai đường. Code mới vẫn nên dùng /api/v1: phản hồi JSON mang theo dấu thời gian, mã lỗi và trường giá mà định dạng token không có chỗ chứa.
# Existing scripts keep working: same actions, same response tokens.
BASE="https://virtualsmsnumbers.com/stubs/handler_api.php"
-kw">curl "$BASE?api_key=$KEY&action=getNumber&service=tg&country=117"
# ACCESS_NUMBER:1043872915:351926114508
-kw">curl "$BASE?api_key=$KEY&action=getStatus&id=1043872915"
# STATUS_WAIT_CODE
# STATUS_OK:48219
-kw">curl "$BASE?api_key=$KEY&action=setStatus&id=1043872915&status=6"
# ACCESS_ACTIVATION
-kw">curl "$BASE?api_key=$KEY&action=getBalance"
# ACCESS_BALANCE:41.87Tác nhân, MCP và khả năng tự khám phá
Có một máy chủ MCP được lưu trữ sẵn, một tài liệu OpenAPI 3.1 và một chỉ mục llms.txt, nên một tác nhân có thể tự tìm ra ba tool nó cần mà không cần lớp keo viết tay. Trỏ client của bạn tới endpoint bên dưới là nó sẽ thấy mua, chờ và trả.
Trước khi để bất cứ thứ gì tự hành tiêu số dư: giới hạn scope của khóa ở numbers:read và numbers:write, đặt trần max_price_cents cho mọi lần mua, và cấp cho nó khóa riêng để việc thu hồi không kéo sập tích hợp đang chạy trên production.
{
"mcpServers": {
"virtualsmsnumbers": {
"type": "http",
"url": "https://virtualsmsnumbers.com/api/mcp",
"headers": { "Authorization": "Bearer vsn_live_xxxxxxxxxxxx" }
}
}
}Trước khi lên production
- Đặt max_price_cents cho mọi lần mua. Giá dịch chuyển theo kho số, và một tác nhân không bị chặn trần sẽ vui vẻ mua ở đầu đắt nhất.
- Hãy coi các định danh là chuỗi mờ. Id lượt kích hoạt tình cờ có mười chữ số ở thời điểm này; đó không phải cam kết, và độ dài của nó cũng vậy.
- Rẽ nhánh theo mã lỗi, đừng rẽ theo thông báo. Mã ổn định trong một phiên bản; thông báo viết cho con người và sẽ bị viết lại.
- Hãy đăng ký sms.received và kiểm tra chữ ký — HMAC-SHA256 trên phần thân thô, với cửa sổ chống phát lại năm phút — thay vì hỏi liên tục về một trạng thái mà bạn có thể được báo.
- Hãy tính toán trên các trường xu kiểu số nguyên. Chuỗi đã định dạng bên cạnh chỉ để hiển thị và phụ thuộc vào ngôn ngữ vùng.
Tài liệu tham chiếu đầy đủ
Sáu endpoint, bảng lỗi, payload webhook, danh sách scope và bảng ánh xạ token của bản cũ.
Câu hỏi thường gặp
Trung vị dưới chín giây tính từ lúc dịch vụ gửi đi. Long poll tồn tại vì phần đuôi rất dài: lượt kích hoạt còn mở trong 20 phút, rồi hết hạn thành một khoản hoàn tiền nếu không có gì về.
Không có gì bạn phải xử lý. Cửa sổ đóng lại, số dư được cộng về tự động, và lượt kích hoạt kết thúc ở trạng thái expired mà bạn đọc được từ API.
Có, và nó không tốn gì. Khóa mang scope cố định, một danh sách IP cho phép tùy chọn và hạn dùng chọn lúc tạo, nên một khóa staging bị lộ không mua được số trên production.
Có vài lớp bọc mỏng, không phụ thuộc thư viện nào, nhưng API chỉ gồm sáu endpoint trên JSON — fetch, requests hay curl thật sự là đủ cho luồng ba lệnh gọi.
Trong cùng một lượt kích hoạt thì được: tin bổ sung vẫn về đúng số đó chừng nào nó còn mở. Qua nhiều phiên thì bạn cần thuê số, vốn giữ thuê bao từ bốn giờ đến mười hai tháng.
Không. Vẫn cùng kho số với cùng mức giá; chỉ khác cách mã hóa phản hồi.