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

1. Hướng dẫn nhanh

2. Xác thực API

3. Danh sách endpoint

4. API sản phẩm

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

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

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

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,
      "description": "Mô tả sản phẩm 1 giữ nguyên bố cục",
      "description2": "Mô tả sản phẩm 2 giữ nguyên bố cục"
    }
  ]
}

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

Request:

POST https://taphoatele.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://taphoatele.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_url: link tải file ZIP qua website đang kết nối API.
• product_desc2 hoặc desc2: mô tả sản phẩm 2 để 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ả download_url thuộc website đang kết nối API. Server website đó sẽ tự gọi nguồn bằng API Key nội bộ rồi stream file lại.

GET https://taphoatele.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://taphoatele.com/api-sync-cron.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. Chữ ký HMAC tùy chọn

Nếu admin bật bắt buộc HMAC cho API tạo đơn, request 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ũ.

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

12. 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.

13. Ví dụ cURL nhanh

Lấy sản phẩm:

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

Tạo đơn:

curl -X POST "https://taphoatele.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"}'