📘 Tài liệu kết nối API

Trang này công khai để đối tác, website vệ tinh hoặc website cùng hệ sinh thái có thể đọc hướng dẫn tích hợp. API dùng API Key riêng của từng user để lấy sản phẩm, xem số dư, tạo đơn hàng và lấy dữ liệu giao hàng.

Đăng nhập để lấy API Key Mở file PHP mẫu Xem hướng dẫn nhanh

Mục lục nhanh

Xác thực Endpoint Sản phẩm Tạo đơn Giao hàng File ZIP Trạng thái code Website cùng hệ sinh thái Mã lỗi Bảo mật

1. Hướng dẫn nhanh

Lấy API Key

User đăng nhập vào tài khoản, mở trang API và copy API Key. Admin cũng có thể xem/đổi/bật/tắt API Key của user.

Gọi API sản phẩm

Website kết nối gọi /api/v1/products bằng header Authorization: Bearer API_KEY.

Tạo đơn

Khi user mua hàng trên website kết nối, gửi product_id, quantity và request_id lên API tạo đơn.

Lấy giao hàng

Dùng mã đơn để lấy code, trạng thái code hoặc link tải file ZIP qua website đang kết nối.

2. Xác thực API

Base URL	`https://taphoatele1.com`
Header khuyến nghị	`Authorization: Bearer YOUR_API_KEY`
Header tương thích	`X-Api-Key: YOUR_API_KEY`
Định dạng	JSON UTF-8. API tạo đơn chỉ nhận `POST application/json`.
Retry an toàn	Dùng lại cùng `request_id` khi retry để tránh tạo trùng đơn.

Không truyền API Key trong URL. Không gọi API trực tiếp từ JavaScript frontend công khai, vì người dùng có thể xem được API Key.

3. Danh sách endpoint

Method	Endpoint	Mục đích	Ghi chú
GET	`/api/v1/categories`	Lấy danh mục	Trả danh mục local và danh mục API đã được website trung gian xử lý hiển thị.
GET	`/api/v1/products?page=1&limit=100`	Lấy danh sách sản phẩm	Có phân trang, cache, rate-limit.
GET	`/api/v1/product?id=PRODUCT_ID`	Lấy chi tiết sản phẩm	Trả mô tả 1/2, min/max, tồn kho, giá bán.
GET	`/api/v1/balance`	Xem số dư	Số dư của user sở hữu API Key.
POST	`/api/v1/order/create`	Tạo đơn hàng	Bắt buộc JSON, nên có `request_id`.
GET	`/api/v1/order/status?order_code=CODE`	Xem trạng thái đơn	Chỉ xem được đơn thuộc API Key đó.
GET	`/api/v1/order/delivery?order_code=CODE`	Lấy giao hàng	Trả code, trạng thái code hoặc download URL.
GET	`/api/v1/order-download?order_code=CODE`	Tải file ZIP	Website trung gian proxy file, không lộ link nguồn.
POST	`/api/v1/integration/otp-callback`	Đăng ký callback OTP	Xác minh callback HTTPS bằng challenge trước khi kích hoạt.
POST	`/api/v1/order/otp/request`	Lấy SĐT	Website kết nối yêu cầu website nguồn mở luồng OTP cho code trong đơn.
POST	`/api/v1/order/otp/latest-code`	Lấy OTP	Yêu cầu kiểm tra tin nhắn mới nhất; cooldown do website nguồn quản lý.
GET	`/api/v1/order/otp/status`	Trạng thái OTP	Fallback khi callback bị chậm/mất; callback vẫn là kênh chính.
GET	`/api/v1/orders`	Lịch sử đơn	Lấy các đơn gần nhất của API Key.

4. API sản phẩm

Endpoint danh sách sản phẩm:

GET https://taphoatele1.com/api/v1/products?page=1&limit=100
Authorization: Bearer YOUR_API_KEY

Các tham số thường dùng:

Tham số	Ý nghĩa
`page`	Trang dữ liệu, mặc định 1.
`limit`	Số sản phẩm mỗi trang. Admin có thể giới hạn tối đa trong Bảo mật API.
`category_id`	Lọc theo danh mục nếu website hỗ trợ.
`q`	Tìm theo từ khóa ngắn.

Ví dụ dữ liệu sản phẩm rút gọn:

{
  "ok": true,
  "data": [
    {
      "id": "PRODUCT_ID",
      "name": "Tên sản phẩm",
      "category_id": "CATEGORY_ID",
      "price": 10000,
      "stock": 25,
      "status": "in_stock",
      "min_qty": 1,
      "max_qty": 10,
      "keywords": "từ khóa riêng của sản phẩm",
      "description": "Mô Tả Sản Phẩm giữ nguyên bố cục",
      "description2": "Hướng Dẫn Sử Dụng giữ nguyên bố cục"
    }
  ]
}

Mô Tả Sản Phẩm và Hướng Dẫn Sử Dụng: hệ thống giữ nguyên xuống dòng/HTML an toàn từ website nguồn. Nếu website trung gian tùy chỉnh mô tả local trong admin, API public của website trung gian sẽ trả mô tả đã tùy chỉnh.

5. API tạo đơn hàng

Request:

POST https://taphoatele1.com/api/v1/order/create
Authorization: Bearer YOUR_API_KEYContent-Type: application/json

{
  "product_id": "PRODUCT_ID",
  "quantity": 1,
  "request_id": "your_site_order_123456"
}

request_id nên là mã duy nhất từ website của bạn. Khi mạng lỗi hoặc timeout, hãy retry bằng đúng request_id cũ để tránh tạo nhiều đơn trùng.

Response thành công thường có:

{
  "ok": true,
  "order_code": "DH2026062918575444E9MF",
  "status": "success",
  "total": 10000,
  "message": "Tạo đơn thành công"
}

6. API lấy giao hàng

GET https://taphoatele1.com/api/v1/order/delivery?order_code=DH2026062918575444E9MF
Authorization: Bearer YOUR_API_KEY

Tùy loại sản phẩm, response có thể gồm:

delivery_codes: danh sách code tương thích cũ.
delivery_codes_detail: code kèm trạng thái đã dùng/chưa dùng.
download_path: đường dẫn tải tương đối, website kết nối nên ưu tiên ghép với URL nguồn đã cấu hình.
download_url: link tuyệt đối giữ để tương thích với phiên bản cũ.
product_desc2 hoặc desc2: Hướng Dẫn Sử Dụng để hiển thị trong lịch sử đơn.

7. Sản phẩm loại file ZIP

Với sản phẩm loại file, API trả đồng thời download_path và download_url. Website kết nối ưu tiên download_path, tự ghép endpoint từ URL nguồn đã cấu hình, sau đó dùng API Key nội bộ để proxy file về cho user.

GET https://taphoatele1.com/api/v1/order-download?order_code=DH2026062918575444E9MF
Authorization: Bearer YOUR_API_KEY

Người dùng cuối chỉ bấm nút tải file trên website kết nối, không cần mở URL website nguồn.

8. Sản phẩm loại code và trạng thái sử dụng

Để bảo mật kho hàng, API sản phẩm không xuất toàn bộ kho code. API chỉ trả trạng thái của code đã giao trong đúng đơn hàng.

{
  "delivery_codes": ["ABC-123"],
  "delivery_codes_detail": [
    {
      "code": "ABC-123",
      "used": true,
      "used_at": "29/06/2026 19:22:17",
      "status_label": "29/06/2026 19:22:17"
    }
  ]
}

Website trung gian sẽ tự làm mới trạng thái code từ website nguồn khi user/admin mở đơn hoặc khi API client hỏi lại trạng thái đơn.

9. Website cùng hệ sinh thái mã nguồn

Website con nên cấu hình trong admin:

URL website nguồn.
API Key của user trên website nguồn.
Cron token.
Giới hạn timeout và khoảng cách sync.
Tùy chỉnh giá cộng/trừ, tên, mô tả, ẩn/hiện sản phẩm API.

Cron mỗi phút gọi:

https://taphoatele1.com/cron/api-sync.php?token=CRON_TOKEN

Dữ liệu gốc từ API nguồn được lưu cache riêng. Tùy chỉnh local của admin được lưu ở file override riêng nên không mất khi cron chạy lại.

10. SĐT / OTP qua website nguồn

Đơn text trả về otp_access.enabled=true khi website nguồn hỗ trợ OTP. Website kết nối không gọi VPS trực tiếp; mọi request đi qua website nguồn.

Đăng ký callback

POST https://taphoatele1.com/api/v1/integration/otp-callback
Authorization: Bearer API_KEY
Content-Type: application/json
X-Api-Timestamp: UNIX_TIMESTAMP
X-Api-Nonce: RANDOM_NONCE
X-Api-Signature: sha256=...

{"client_id":"client_xxx","callback_url":"https://site-b.com/api/remote-order-otp-callback.php"}

Website nguồn gửi event verify kèm challenge tới callback. Chỉ callback HTTPS public, không trỏ IP private/reserved và vượt qua challenge mới được lưu.

Lấy SĐT

POST https://taphoatele1.com/api/v1/order/otp/request
Authorization: Bearer API_KEY
Content-Type: application/json
X-Api-Timestamp: UNIX_TIMESTAMP
X-Api-Nonce: RANDOM_NONCE
X-Api-Signature: sha256=...

{"order_code":"DH_SOURCE","code_index":0,"client_id":"client_xxx","client_request_id":"otp_unique_123"}

client_request_id phải duy nhất và idempotent. Gửi lại cùng ID sẽ trả lại request nguồn cũ thay vì mở thêm VPS job.

Callback kết quả

Website nguồn callback các trạng thái quan trọng như phone_received, listener_ready, number_received, expired và failed. Header callback gồm X-Otp-Client, X-Otp-Timestamp, X-Otp-Nonce, X-Otp-Signature.

Nếu chưa có SĐT trong thời gian chờ của website nguồn (mặc định 3 phút), request chuyển expired và website kết nối có thể tạo request mới. Khi đã có SĐT, luồng tiếp tục chờ OTP theo timeout OTP của website nguồn.

Status fallback

GET https://taphoatele1.com/api/v1/order/otp/status?order_code=DH_SOURCE&client_id=client_xxx&client_request_id=otp_unique_123
Authorization: Bearer API_KEY

11. Chữ ký HMAC

API tạo đơn dùng HMAC khi admin bật bắt buộc. Riêng các POST bảo mật của SĐT/OTP (đăng ký callback, Lấy SĐT, Lấy OTP) luôn yêu cầu HMAC và cần thêm:

X-Api-Timestamp: UNIX_TIMESTAMP
X-Api-Nonce: RANDOM_STRING
X-Api-Signature: sha256=HMAC_SHA256(METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + RAW_BODY, API_KEY)

Timestamp chỉ hợp lệ trong khoảng thời gian admin cấu hình, nonce giúp chống gửi lại request cũ.

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

Mã lỗi	Ý nghĩa	Cách xử lý
`missing_api_key`	Thiếu API Key.	Gửi header `Authorization: Bearer API_KEY`.
`unauthorized`	API Key sai hoặc đã đổi.	Kiểm tra lại API Key trong tài khoản.
`api_disabled`	API của user đang tắt.	Bật API trong tài khoản hoặc liên hệ admin.
`ip_not_allowed`	IP không nằm trong allowlist.	Thêm IP server gọi API vào cấu hình user.
`rate_limited`	Gọi API quá nhanh.	Dừng một thời gian rồi retry, không spam liên tục.
`api_guard`	API đang tạm giới hạn vì lưu lượng bất thường.	Chờ guard hết hạn hoặc admin tắt trong Bảo mật API.
`missing_request_id`	Admin yêu cầu request_id khi tạo đơn.	Gửi request_id duy nhất cho mỗi đơn.
`invalid_signature`	HMAC sai.	Kiểm tra raw body, path, timestamp, nonce và API Key.
`maintenance`	Website đang bảo trì.	Hiển thị thông báo bảo trì và thử lại sau.
`order_failed`	Tạo đơn thất bại.	Hiển thị message sạch cho user, log chi tiết cho admin.

13. Khuyến nghị bảo mật khi đấu API

Chỉ gọi API từ backend/server của website bạn, không gọi trực tiếp từ JavaScript frontend.
Không đưa API Key vào URL, form HTML công khai, mã nguồn frontend hoặc log public.
Luôn đặt timeout khi gọi API, ví dụ connect timeout 5 giây và tổng timeout 15 giây.
Khi nhận HTTP 429, hãy dừng và retry sau; không tạo vòng lặp retry liên tục.
Dùng cùng request_id khi retry để tránh tạo trùng đơn.
Đổi API Key ngay nếu nghi ngờ bị lộ.
Bật allowlist IP nếu website kết nối có IP server cố định.

14. Ví dụ cURL nhanh

Lấy sản phẩm:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://taphoatele1.com/api/v1/products?page=1&limit=20"

Tạo đơn:

curl -X POST "https://taphoatele1.com/api/v1/order/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"PRODUCT_ID","quantity":1,"request_id":"site_order_123"}'