1. Xác thực
Mọi request cần header X-API-Key (key được cấp trong khu quản trị, mục B2B API) hoặc header Authorization: Bearer <token> của tài khoản thành viên gói trả phí còn hạn. Thiếu cả hai, hoặc key sai/đã bị tắt, hoặc token hết hạn sẽ bị từ chối với HTTP 401.
2. Kiểm tra IMEI
GET /api/v3/{nhà mạng}/{imei} — trả về tình trạng giới hạn mạng của IMEI trên một nhà mạng Nhật. {nhà mạng} là một trong các mã ở bảng bên dưới; {imei} gồm 15 số, hợp lệ Luhn. Muốn tra nhiều nhà mạng thì gọi lần lượt từng mã. Kết quả: {"message": "<ký hiệu>"}.
3. Tra cứu Samsung
GET /api/v3/samsung/{imei} — trả về thông tin máy Samsung (model, …) theo IMEI.
4. Mã lỗi
HTTP 401 {"message":"Thiếu hoặc sai API key / token"}: chưa xác thực. HTTP 403 (chỉ khi dùng token thành viên): tài khoản bị khoá, bị vô hiệu hoá, chưa kích hoạt, chưa xác minh email, đang dùng gói Free hoặc gói đã hết hạn — trường code cho biết lý do (BLOCKED, DISABLED, INACTIVE, NOT_VERIFIED, NO_PLAN, EXPIRED). HTTP 400 {"message":"IMEI Error"}: IMEI không đủ 15 số hoặc sai Luhn. HTTP 500 {"message":"error"}: không lấy được kết quả từ trang nhà mạng — nên thử lại sau ít phút. Khi dịch vụ đang bảo trì, message có thể kèm nội dung thông báo bảo trì.
5. Giới hạn
Không giới hạn số request theo key. Mỗi request tra trực tiếp trang nhà mạng nên có thể mất vài giây — nên đặt timeout tối thiểu 60 giây và không gọi dồn dập cùng lúc. Mọi request đều được ghi log kèm IP.