Quy Ước REST API

Tài liệu này đặc tả quy ước thiết kế, giao thức và định dạng dữ liệu cho toàn bộ hệ thống StackVid REST API dành cho các lập trình viên, bot tự động hóa và n8n workflows.

1. Base URL & Giao Thức

Mọi yêu cầu gửi đến StackVid API đều sử dụng giao thức bảo mật HTTPS:

http

https://api.stackvid.dev/api

Dữ liệu request và response sử dụng định dạng chuẩn JSON (application/json) với mã hóa UTF-8.
Tất cả thời gian trả về đều tuân thủ định dạng chuẩn quốc tế ISO-8601 UTC (ví dụ: 2026-10-01T12:00:00.000Z).

2. Tiêu Đề Xác Thực (Authentication Header)

Tất cả các endpoint API đều yêu cầu xác thực thông qua API Key được truyền trong HTTP Request Header:

http

X-API-Key: tk_live_YOUR_API_KEY

Lấy API Key

Bạn có thể tạo mới, sao chép và quản lý các khóa API Key trực tiếp trên giao diện Dashboard → Khóa API. Khóa có tiền tố tk_live_... và có hiệu lực ngay lập tức.

3. Mã Trạng Thái HTTP (Status Codes)

Hệ thống trả về các mã trạng thái chuẩn HTTP rõ ràng:

Mã	Trạng thái	Ý nghĩa & Hướng dẫn xử lý
`200`	OK	Yêu cầu thực thi thành công và trả về dữ liệu kết quả.
`201`	Created	Tạo tài nguyên thành công (ví dụ: xin cấp Presigned Upload URL).
`400`	Bad Request	Dữ liệu đầu vào không hợp lệ (ví dụ: `videoUrl` sai định dạng, link trả về mã HTML hoặc thiếu tham số bắt buộc).
`401`	Unauthorized	Thiếu header `X-API-Key` hoặc khóa API Key không hợp lệ / đã bị thu hồi.
`402`	Payment Required	Số dư credit trong ví không đủ để thực hiện tác vụ (kèm thông báo số credit yêu cầu và số credit hiện có).
`429`	Too Many Requests	Bạn đã gọi API vượt quá giới hạn tần suất cho phép (Rate Limit mặc định: 60 requests/phút).
`500`	Internal Server Error	Lỗi xử lý từ hệ thống hoặc gián đoạn mạng từ máy chủ mạng xã hội (tự động hoàn tiền 100% credit).

4. Cấu Trúc Lỗi Chuẩn (Error Format)

Khi xảy ra lỗi (status code >= 400), máy chủ luôn trả về cấu trúc JSON nhất quán:

Lỗi Không Đủ Số Dư (402 Payment Required):

json

{
  "statusCode": 402,
  "message": "Insufficient credit balance. Required: 5, Available: 2",
  "error": "Payment Required"
}

Lỗi Dữ Liệu Đầu Vào (400 Bad Request):

json

{
  "statusCode": 400,
  "message": [
    "videoUrl must be a valid HTTP or HTTPS URL"
  ],
  "error": "Bad Request"
}

Cơ Chế Hoàn Tiền Tự Động (Zero-Risk)

Nếu cuộc gọi API xuất bản video gặp sự cố kỹ thuật hoặc videoUrl của bạn không thể tải về được, cơ chế Two-Phase Commit sẽ tự động hoàn trả 100% credit về ví tài khoản của bạn ngay lập tức.

Quy Ước REST API ​

1. Base URL & Giao Thức ​

2. Tiêu Đề Xác Thực (Authentication Header) ​

3. Mã Trạng Thái HTTP (Status Codes) ​

4. Cấu Trúc Lỗi Chuẩn (Error Format) ​

Lỗi Không Đủ Số Dư (402 Payment Required): ​