Lấy OTP (Flow chuẩn)

Tạo request_id → poll đến khi có OTP hoặc timeout (khuyến nghị cho tool/bot).
request_id poll rule_key
Document API
Hướng dẫn tích hợp mua Email / lấy OTP / mua Social.
Tổng quanAuth & PingMua EmailLấy OTP (chuẩn)OTP One-shotMua Social
Mục lục
1. Luồng chuẩn2. Tạo OTP request3. Poll OTP4. Lỗi thường gặp

1. Luồng chuẩn

  1. Gọi API Start (email + rule_key) → nhận request_id.
  2. Loop gọi API Poll theo request_id cho tới khi status=done hoặc status=timeout.
Multi-app: Refresh token có thể thuộc app khác (B/C/D) miễn mailbox lưu đúng tenant + client_id (và client_secret nếu là confidential client).
Ưu điểm: Tool bạn kiểm soát nhịp poll, timeout, retry rất mượt.

2. Tạo OTP request

POST/system/api_otp_by_mail_start.php
TênKiểuMô tả
email requiredstringEmail cần lấy OTP (phải tồn tại trong hệ thống).
passwordstringMật khẩu email (nếu bạn bật kiểm tra).
rule_key requiredstringRule lọc OTP (ví dụ tiktok, facebook...).
timeout_secondsintThời gian chờ tối đa (10–180). Mặc định 60.
poll_intervalintGợi ý nhịp poll (1–10). Mặc định 3.
POST https://minisoftwares.net/system/api_otp_by_mail_start.php
Header: X-API-KEY: YOUR_API_KEY
Body (JSON):
{
  "email": "testmail01@outlook.com",
  "password": "123456",
  "rule_key": "tiktok",
  "timeout_seconds": 60,
  "poll_interval": 3
}

Response mẫu

{
  "ok": true,
  "status": "waiting",
  "request_id": "<hex>",
  "mailbox_id": 12,
  "rule_key": "tiktok",
  "expire_at": "2025-12-30 06:05:00",
  "poll_interval": 3
}
Tip: Nếu bạn không muốn truyền header, có thể gửi api_key trong JSON body (server sẽ tự inject).

3. Poll OTP

POST/system/api_otp_by_mail_poll.php
TênKiểuMô tả
request_id requiredstringID (hex) nhận từ api_otp_by_mail_start.php.
outputstringTuỳ chọn dữ liệu trả về: otp (mặc định), full, both.

Ví dụ request

POST https://minisoftwares.net/system/api_otp_by_mail_poll.php
Header: X-API-KEY: YOUR_API_KEY
Body (JSON):
{
  "request_id": "<hex>",
  "output": "both"
}

Response khi CHƯA có OTP

{
  "ok": false,
  "status": "waiting",
  "request_id": "<hex>",
  "mailbox_id": 12
}

Response khi ĐÃ có OTP

{
  "ok": true,
  "status": "done",
  "request_id": "<hex>",
  "mailbox_id": 12,
  "otp": "583921",
  "full_text": "Your TikTok verification code is 583921"
}

Response timeout

{
  "ok": false,
  "status": "timeout",
  "error": "timeout_waiting_otp",
  "request_id": "<hex>"
}
Quan trọng: Đừng chỉ nhìn ok. Hãy dựa vào status:
  • status=done → đã có OTP
  • status=waiting → chưa có, tiếp tục poll
  • status=timeout → hết hạn
  • status=error → lỗi token/graph/ownership… xem error_code

4. Lỗi thường gặp

- invalid_api_key
- missing_email / missing_rule_key
- email_not_in_system
- invalid_mail_password
- email_belongs_to_other_user
- request_not_found
- timeout_waiting_otp
- missing_refresh_token
- invalid_grant (refresh token die)
- graph_http_status / graph_unauthorized
Tip: Nếu bạn cần “1 phát ra OTP” thì xem trang OTP One-shot.
Copyright © 2026 Minisoftwares.Net. Design with
by Nguyen Van Sinh All rights reserved.