API xác minh SMS

1. GET /api/v2/tn101/get-services — danh mục, kèm mã định danh bạn sẽ dùng để đặt và giá hiện tại.
2. POST /api/v2/tn101/request-number — đặt một số. Nhận service_key, cùng state và mã vùng tùy chọn. Trả về mã đơn, số điện thoại và thời điểm hết hạn.
3. GET /api/v2/tn101/get-number-details — gọi kiểm tra với order_id. pin là null cho tới khi mã đến và chứa mã sau đó. Đây là lệnh đọc rẻ nhất trong API và được thiết kế để gọi lặp lại.
4. POST /api/v2/tn101/reject-number — trả lại một số không nhận được gì. Đây cũng là bước hoàn tiền.

Trên luồng này không có gì được đẩy tới bạn, nên bước 3 là gọi kiểm tra định kỳ (polling). Nếu bạn muốn được báo thay vì phải hỏi, tài khoản còn gửi webhook cho các sự kiện đơn hàng, cấu hình trong bảng điều khiển.

Mọi yêu cầu đều mang Authorization: Bearer <token>. Token được tạo trong bảng điều khiển ở mục truy cập API và có thể xoay vòng (rotate) ở đó bất cứ lúc nào — xoay vòng sẽ vô hiệu hóa token cũ ngay lập tức, nên hãy thay nó trong cấu hình của bạn trước.

Yêu cầu không có token hợp lệ nhận 401. Tài khoản bị tạm khóa, hoặc đã tắt quyền truy cập API, nhận 403. Khi API bị tắt trên toàn trang, mọi endpoint đều trả về 503 thay vì giả vờ hoạt động.

Mọi endpoint đều trả về cùng ba trường:

data chứa dữ liệu, success là giá trị boolean để rẽ nhánh, và summery là thông báo dễ đọc. Cách viết đó không phải lỗi chính tả của trang này — đó là tên trường mà API luôn trả về, có mặt trong mọi tích hợp đã viết cho nó, và đổi tên sẽ làm hỏng tất cả chỉ để sửa một ký tự. Hãy đọc summery.

Lỗi kiểm tra dữ liệu trả về 422 với data là một đối tượng ánh xạ tên trường tới thông báo lỗi, để bên gọi có thể báo chính xác tham số nào sai chứ không chỉ biết là có gì đó sai.

API là cách thực tế để chạy thử một luồng đăng ký hoặc đặt lại mật khẩu qua một tuyến nhà mạng thật thay vì giả lập — đặt một số, dùng nó điền biểu mẫu của chính bạn, gọi kiểm tra mã, rồi kiểm chứng ứng dụng của bạn làm gì tiếp theo. Đây là bài kiểm thử chậm hơn so với dùng stub, nhưng bắt được những thứ stub không bắt được: chuẩn hóa số, lọc theo loại đường dây, và độ trễ gửi tin mà người dùng của bạn sẽ thực sự gặp.

API không giới hạn số yêu cầu mỗi giây, nhưng có hai hạn mức đối với việc đặt số, và chúng giống hệt hạn mức mà bảng điều khiển áp dụng:

• Đơn đang mở. Mỗi tài khoản chỉ được giữ một số lượng số nhất định cùng lúc. Hãy gọi kiểm tra và trả số thay vì mở hàng loạt song song.
• Đơn bị hủy và hết hạn mỗi ngày. Vượt quá hạn mức hằng ngày thì việc đặt số sẽ tạm dừng một thời gian, và kéo dài hơn nếu lặp lại. Mỗi lần giữ số đều tiêu tốn nguồn cung thật dù mã có đến hay không, và đó là điều hạn mức này bảo vệ.

Cả hai được mô tả chi tiết hơn trong trang số tạm thời, nơi giải thích một đơn diễn ra thế nào.