Tài liệu API Email & OTP

Tích hợp Minisoftwares vào tool C#, Python, v.v… để mua mail và lấy OTP tự động.

X-API-KEY theo từng tài khoản
Trừ tiền trực tiếp trên ví
Lưu lịch sử OTP & request
Bạn đang xem ở chế độ khách. Để mua mail và gọi API, vui lòng đăng nhập hoặc đăng ký tài khoản.
Mục lục

1. Tổng quan

API Email & OTP giúp bạn:

  • Mua và quản lý email trực tiếp trên Minisoftwares.
  • Gửi yêu cầu lấy OTP cho từng email đã mua.
  • Nhận OTP qua 2 cách:
    • Flow chuẩn: Tạo request → Poll kết quả.
    • Flow mới: ONE-SHOT từ email + mật khẩu trả về OTP trong 1 call.
Nguyên tắc: Client/tool chỉ cần gửi request đúng định dạng. Tất cả xử lý nội bộ (đọc mail, nhận dạng OTP, lưu log, …) đều được hệ thống xử lý phía server.

2. Xác thực (Authentication)

Header bắt buộc

X-API-KEY: YOUR_API_KEY_HERE

Mọi request đến API đều phải gửi kèm header X-API-KEY. Nếu thiếu hoặc sai, API sẽ trả về JSON lỗi và không xử lý yêu cầu.

Response khi API key không hợp lệ

{ "ok": false, "error": "invalid_api_key" }
Trong C#: httpClient.DefaultRequestHeaders.Add("X-API-KEY", apiKey); Truyền trước khi gọi bất kỳ endpoint nào.

3. Kiểm tra kết nối & API key

GET /system/api_ping.php

Dùng để test nhanh API key & kiểm tra ví còn bao nhiêu tiền.

Ví dụ gọi

GET https://minisoftwares.net/system/api_ping.php Header: X-API-KEY: YOUR_API_KEY

Response thành công

{ "ok": true, "time": "2025-12-18T06:12:50+07:00", "user": { "username": "demo_user", "wallet_balance": 9090000 } }

4. Tạo yêu cầu OTP (flow chuẩn dùng mailbox đã thuộc tài khoản)

POST /system/api_otp_request.php

Tạo một yêu cầu OTP mới cho email đã mua (hoặc đã gán cho tài khoản). Sau khi tạo, bạn sẽ nhận được request_id để dùng khi poll OTP.

Tham số (JSON body)

Tên Kiểu Mô tả
mailbox_id required int ID của mailbox (email) thuộc tài khoản hoặc khách con của bạn.
rule_key required string Tên dịch vụ: "facebook", "tiktok", "gmail", … (dùng để áp rule lọc OTP).
note string Ghi chú nội bộ, không bắt buộc.

Ví dụ request

POST https://minisoftwares.net/system/api_otp_request.php Header: X-API-KEY: YOUR_API_KEY Body (JSON): { "mailbox_id": 12, "rule_key": "tiktok", "note": "dang ky tai khoan moi" }

Response mẫu

{ "ok": true, "request_id": 12345, "status": "pending", "message": "OTP request created" }
request_id là ID duy nhất cho phiên OTP này. Tool của bạn chỉ cần lưu lại và dùng ở bước poll.

5. Poll kết quả OTP (flow chuẩn)

POST /system/api_otp_poll.php

Sau khi tạo yêu cầu, gọi endpoint này để kiểm tra OTP đã về hay chưa. Server sẽ tự đọc email và trích mã OTP dựa trên cấu hình nội bộ, client chỉ cần gửi đúng request_id để nhận kết quả.

Tham số (JSON body)

Tên Kiểu Mô tả
request_id required int ID được trả về từ api_otp_request.php.
wait_seconds int (Tuỳ chọn) Số giây server cho phép chờ mail mới. 0 = không chờ, 30 = chờ tối đa 30 giây trước khi trả về.

Ví dụ request

POST https://minisoftwares.net/system/api_otp_poll.php Header: X-API-KEY: YOUR_API_KEY Body (JSON): { "request_id": 12345, "wait_seconds": 30 }

Response khi CHƯA có OTP

{ "ok": true, "done": false, "status": "pending", "message": "OTP not found yet" }

Response khi ĐÃ có OTP

{ "ok": true, "done": true, "status": "success", "otp_code": "583921", "full_text": "Your TikTok verification code is 583921", "received_at": "2025-12-18T06:25:30+07:00" }

6. Mã lỗi thường gặp

error Mô tả
invalid_api_key API key không hợp lệ hoặc đã bị khoá.
db_prepare_failed_auth Lỗi hệ thống. Nếu gặp nhiều lần, vui lòng liên hệ hỗ trợ.
request_not_found request_id không tồn tại hoặc không thuộc tài khoản của bạn.
otp_timeout Hết thời gian chờ OTP theo cấu hình hệ thống.
mailbox_not_found Không tìm thấy email trong hệ thống.
mailbox_owned_by_other_customer Mailbox/email này thuộc một khách hàng khác, bạn không có quyền lấy OTP.
invalid_mail_credentials Mật khẩu mail gửi lên không khớp với dữ liệu hệ thống (tuỳ cấu hình).

7. Gợi ý flow trong C#

  1. Đăng nhập web, nạp tiền vào ví.
  2. Mua email trong menu Email & OTP → Mua Email.
  3. Lấy X-API-KEY trong phần tài khoản.
  4. Trong tool C#, nếu dùng flow chuẩn:
    • Gọi api_ping.php để test API key & số dư.
    • Gọi api_otp_request.php → nhận request_id.
    • Loop gọi api_otp_poll.php (mỗi 3–5 giây) cho đến khi done = true hoặc timeout.
  5. Nếu muốn đơn giản theo email + mật khẩu, dùng trực tiếp:
    • api_otp_by_mail.php (mapping → mailbox_id)
    • hoặc api_otp_by_mail_oneshot.php (one-shot OTP)
Nếu anh muốn, mình có thể viết thêm 1 file C# client mẫu (class MiniOtpClient) để khách chỉ cần copy vào project và dùng các hàm: PingAsync(), RequestOtpAsync(), PollOtpAsync(), GetOtpByMailAsync(), GetOtpByMailOneShotAsync().

8. Khách con (Sub-client) & API key riêng

Khách con (sub-client) dùng cho đại lý muốn tách API key & tài khoản cho từng khách/quản lý riêng, nhưng vẫn quản lý chung trên Minisoftwares.

8.1. Khái niệm

  • Mỗi khách con là một tài khoản web riêng (username + password đăng nhập).
  • Mỗi khách con có API key riêng (X-API-KEY) để gọi API.
  • Trong DB:
    • Bảng user: tạo thêm 1 dòng user mới.
    • Bảng customers: tạo 1 customer mới, có parent_customer_id = customer gốc của đại lý.

8.2. Cách tạo khách con trên web

Sau khi đăng nhập bằng tài khoản đại lý:

  1. Vào menu Đại lý → Khách con (hoặc đường dẫn /partner/clients).
  2. Dùng form Tạo khách con mới:
    • Nhập Username khách con.
    • (Tuỳ chọn) Nhập Email khách con.
    • (Tuỳ chọn) Ghi chú: khách VIP / khách test / …
  3. Hệ thống sẽ:
    • Tự tạo user + mật khẩu đăng nhập cho khách con.
    • Tự sinh 1 API key riêng.
    • Gắn khách con vào customer gốc của đại lý.
Sau khi tạo xong, hệ thống sẽ hiển thị:
  • Username khách con.
  • Mật khẩu đăng nhập (hiển thị 1 lần, cần copy lại ngay).
  • API KEY của khách con (X-API-KEY).
Đại lý nên copy & gửi cho khách con qua kênh riêng (Telegram, Zalo, …).

8.3. Dùng API với khách con

Khách con sau khi có API KEY của riêng mình có thể gọi tất cả API giống như tài khoản chính:

  • api_ping.php
  • api_otp_request.php
  • api_otp_poll.php
  • api_otp_by_mail.php
  • api_otp_by_mail_oneshot.php

Chỉ cần thay header:

X-API-KEY: API_KEY_CUA_KHACH_CON

Toàn bộ request/OTP/log sẽ được gắn với customer của khách con, giúp đại lý quản lý rõ khách nào dùng bao nhiêu OTP / mailbox nào thuộc khách nào.

9. API theo Email + Mật khẩu (mapping sang mailbox_id)

Dùng khi bạn chỉ có email + mật khẩu email nhưng vẫn muốn dùng hệ thống OTP, không cần tự lấy mailbox_id thủ công. Endpoint này sẽ:

  • Nhận email + password + api_key.
  • Tìm mailbox tương ứng trong hệ thống.
  • Nếu mailbox chưa gán cho ai → gán về khách hàng của API KEY đang dùng.
  • Trả về mailbox_id để bạn dùng với api_otp_request.php.
POST /system/api_otp_by_mail.php

Tham số (JSON body)

Tên Kiểu Mô tả
email required string Email đã được hệ thống quản lý (đã mua hoặc đã import).
password string Mật khẩu mail (nếu hệ thống có lưu để so sánh, tuỳ cấu hình).
rule_key string Tên dịch vụ (gợi ý) như "tiktok", "facebook", … (tuỳ chọn, dùng để log).
api_key string Có thể truyền trong body hoặc header X-API-KEY.

Ví dụ request

POST https://minisoftwares.net/system/api_otp_by_mail.php Header: X-API-KEY: YOUR_API_KEY Body (JSON): { "email": "testmail01@outlook.com", "password": "123456", "rule_key": "tiktok" }

Response mẫu

{ "ok": true, "mailbox_id": 12, "customer_id": 3, "email": "testmail01@outlook.com", "rule_key_hint": "tiktok", "message": "Use this mailbox_id with api_otp_request.php + api_otp_poll.php to get OTP." }
Sau khi có mailbox_id, bạn dùng nó giống hệt như flow chuẩn tại mục 4 + 5 (api_otp_request.php + api_otp_poll.php).

10. API ONE-SHOT OTP bằng Email + Mật khẩu

Đây là endpoint tối giản nhất cho client/tool: Gửi email + password + rule_key → server:

  • Gán mailbox về khách hàng của API KEY (nếu chưa gán).
  • Tạo một OTP request mới.
  • Tự chờ (poll) trong 1 khoảng thời gian.
  • Trả về OTP trong 1 lần gọi duy nhất.
POST /system/api_otp_by_mail_oneshot.php

Tham số (JSON body)

Tên Kiểu Mô tả
email required string Email cần lấy OTP.
password string Mật khẩu email (nếu hệ thống có lưu & bật check).
rule_key required string Tên dịch vụ áp rule OTP: "tiktok", "facebook", "gmail", …
timeout_seconds int Thời gian tối đa chờ OTP (mặc định ~60s, max 180s).
poll_interval int Khoảng thời gian (giây) giữa mỗi lần server kiểm tra lại xem OTP đã về chưa. Ví dụ 3 = mỗi 3 giây check một lần.
api_key string Có thể truyền trong body hoặc header X-API-KEY.

Ví dụ request

POST https://minisoftwares.net/system/api_otp_by_mail_oneshot.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 khi có OTP (thành công)

{ "ok": true, "mode": "oneshot", "status": "done", "request_id": 1234, "mailbox_id": 12, "customer_id": 3, "rule_key": "tiktok", "otp": "482931", "wait_seconds": 17.234 }

Response khi hết thời gian chờ

{ "ok": false, "mode": "oneshot", "status": "timeout", "request_id": 1234, "mailbox_id": 12, "customer_id": 3, "rule_key": "tiktok", "error": "timeout_waiting_otp", "timeout_sec": 60 }
Lưu ý: - ONE-SHOT giữ kết nối HTTP mở đến khi có OTP hoặc timeout, phù hợp cho tool / server-side. - Nếu anh cần kiểm soát mượt hơn (tự loop, tự delay), hãy dùng flow chuẩn (mục 4 + 5).
Copyright © 2025 Minisoftwares.Net. Design with
by Nguyen Van Sinh All rights reserved.