Tài liệu API

Mọi thứ làm được trên giao diện đều gọi được bằng API. Mọi ví dụ dưới đây chạy được ngay bằng cách dán vào terminal.

Tổng quan

curl -s https://apitoolhub.tiengvang.com/api/v1/tools/dns.checker/exec \
  -H 'Content-Type: application/json' \
  -d '{"domain":"example.com"}'

Xác thực

Hai cách, dùng cách nào cũng được:

1. Bearer token (dành cho ứng dụng có người đăng nhập)

# Đăng nhập → nhận access_token (hạn 15 phút) và refresh_token
curl -s -X POST https://apitoolhub.tiengvang.com/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"ban@example.com","password":"mat-khau"}'

# Tài khoản bật xác thực hai bước thì gửi kèm mã 6 số:
#   {"email":"…","password":"…","code":"123456"}
# Chưa gửi mã sẽ nhận 401 kèm error = "mfa_required".

# Hết hạn thì làm mới, KHÔNG cần đăng nhập lại:
curl -s -X POST https://apitoolhub.tiengvang.com/api/v1/auth/refresh \
  -H 'Content-Type: application/json' \
  -d '{"refresh_token":"…"}'

Gửi kèm mọi request: Authorization: Bearer <access_token>

2. API key (dành cho máy chủ, script, cron)

Tạo trong ứng dụng tại Gói, tài khoản & API. Cần gói có quyền api_access (từ Plus trở lên).

curl -s https://apitoolhub.tiengvang.com/api/v1/tools/dns.checker/exec \
  -H 'X-API-Key: pat_abc123.secret…' \
  -H 'Content-Type: application/json' \
  -d '{"domain":"example.com"}'

Hạn mức theo gói

Hạn mức là dữ liệu động, đọc số hiện hành bằng GET /plans hoặc GET /me/entitlements.

Mỗi công cụ có một gói tối thiểu riêng (min_plan). Gọi công cụ ngoài gói trả về 403 plan_required kèm gói cần có.

Danh mục công cụ

GET /tools — danh sách công cụ đang bật, kèm min_plan và mode.

curl -s https://apitoolhub.tiengvang.com/api/v1/tools | head -40

GET /tools/{toolId} — chi tiết một công cụ.

Trường mode quyết định cách chạy: sync dùng /exec, async dùng /run.

Chạy nhanh — công cụ sync

POST /tools/{toolId}/exec — trả kết quả ngay trong response.

curl -s -X POST https://apitoolhub.tiengvang.com/api/v1/tools/ssl.expiry/exec \
  -H 'Content-Type: application/json' \
  -d '{"host":"example.com"}'

{
  "tool": "ssl.expiry",
  "output": { "host": "example.com", "con_lai_ngay": 85, "muc_do": "tot", "ket_luan": "Còn 85 ngày, chưa cần lo." },
  "elapsed_ms": 96
}

Gửi header Idempotency-Key nếu muốn gọi lại an toàn khi mất mạng giữa chừng — lần gọi lại cùng khoá trả đúng kết quả cũ, không tính thêm lượt.

Chạy nền — công cụ async

Việc nặng (ví dụ tra WHOIS hàng loạt) trả về mã tác vụ, chạy nền, lấy kết quả sau.

# 1. Tạo tác vụ → 202
curl -s -X POST https://apitoolhub.tiengvang.com/api/v1/tools/domain.bulk/run \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"domains":"example.com\nexample.net\nexample.org"}'
# → {"job_id":"a6d7…","status":"queued"}

# 2. Theo dõi trạng thái
curl -s https://apitoolhub.tiengvang.com/api/v1/jobs/a6d7… -H "Authorization: Bearer $TOKEN"
# → {"status":"running","progress":66}

# 3. Lấy kết quả khi status = done
curl -s https://apitoolhub.tiengvang.com/api/v1/jobs/a6d7…/result -H "Authorization: Bearer $TOKEN"

Theo dõi tiến trình thời gian thực (SSE)

Trình duyệt không gửi được header xác thực trên EventSource, nên xin một vé ngắn hạn trước:

curl -s -X POST https://apitoolhub.tiengvang.com/api/v1/jobs/{jobId}/sse-ticket \
  -H "Authorization: Bearer $TOKEN"
# → {"ticket":"…","expires_in":120}

const es = new EventSource(BASE + '/jobs/' + jobId + '/events?ticket=' + ticket);
es.onmessage = e => console.log(JSON.parse(e.data).progress);

Vé sống 120 giây và chỉ mở đúng tác vụ đã xin — không dùng được cho tác vụ khác.

Thông tin tài khoản & hạn mức

Quản lý API key

Mã lỗi

Lỗi luôn có dạng {"error":"…","detail":"…"}; detail viết bằng tiếng Việt, đưa thẳng cho người dùng cuối được.

Giới hạn kỹ thuật

• Kích thước body tối đa 64 KB cho hầu hết endpoint; công cụ nhận tệp nhận tối đa 8 MB dạng Base64.
• WHOIS hàng loạt: tối đa 200 tên miền mỗi lần chạy; vượt thì phần dư được báo rõ trong kết quả chứ không âm thầm cắt.
• Công cụ gọi ra Internet đều đi qua bộ chặn SSRF: không truy cập được địa chỉ nội bộ, loopback, link-local hay dải CGNAT — kể cả khi tên miền cố tình trỏ vào đó.
• Tra cứu có bộ nhớ đệm ngắn theo từng công cụ; kết quả tra cứu trùng trong thời gian đệm không tính thêm lượt.