Chuyển tới nội dung chính

Giới thiệu Open API – Mini Gift

Open API cho phép hệ thống của bạn kết nối trực tiếp với Mini Gift để quản lý quà tặng, tra cứu chiến dịch và cấu hình Webhook một cách tự động, không cần thao tác thủ công trên Portal.

API được thiết kế theo chuẩn RESTful, dữ liệu truyền và nhận ở định dạng JSON (UTF-8), xác thực bằng API Key.

Đối tượng sử dụng

Tài liệu này dành cho lập trình viên tích hợp hệ thống bên ngoài (ERP, CRM, POS, website...) với Mini Gift. Người dùng cần có quyền quản trị cửa hàng để tạo API Key.

1. Lấy API Key​

API Key được tạo và quản lý ngay trên Portal Mini Gift. Mỗi cửa hàng chỉ có một API Key duy nhất.

Truy cập Quản lý liên kết

Từ menu bên trái, chọn Quản lý liên kết.

Menu Quản lý liên kết trên Portal Mini Gift

Hình ảnh: Truy cập Quản lý liên kết từ menu bên trái

Chọn tab Api Key

Nhấn vào tab Api Key ở thanh tab phía trên.

Tab Api Key trong màn hình Quản lý liên kết

Hình ảnh: Chọn tab Api Key

Tạo mới API Key

Nhấn nút Tạo mới (góc phải). Một hộp thoại xuất hiện yêu cầu bạn nhập tên cho API Key.

Hộp thoại tạo API Key mới trên Mini Gift

Hình ảnh: Nhập tên và xác nhận tạo API Key

Lưu ý

Nếu đã có API Key cũ, việc tạo mới sẽ ghi đè khóa cũ ngay lập tức — mọi tích hợp đang dùng khóa cũ sẽ bị lỗi 401.

Sao chép API Key

Sau khi xác nhận, hệ thống sinh ra một khóa có dạng sk_ theo sau là 48 ký tự ngẫu nhiên:

sk_9aF3kZ1qWpX7bN2rL8vT0cH5dY4eU6sM1oI2gK3jD7fB0nQ

Nhấn nút Sao chép bên cạnh khóa để copy vào clipboard.

API Key đã tạo thành công với nút sao chép

Hình ảnh: Sao chép API Key vừa tạo

Bảo mật API Key
  • API Key tương đương mật khẩu: cần bảo mật tuyệt đối, chỉ lưu ở phía máy chủ (server-side), không đặt trong mã nguồn client, ứng dụng di động hay biến môi trường công khai. - Nếu nghi ngờ lộ khóa, hãy tạo lại API Key mới để vô hiệu hóa khóa cũ.

2. Xác thực (Authentication)​

Mọi request gửi đến Open API đều bắt buộc gắn API Key vào header x-api-key:

Header bắt buộc
x-api-key: sk_9aF3kZ1qWpX7bN2rL8vT0cH5dY4eU6sM1oI2gK3jD7fB0nQ
Content-Type: application/json

Cửa hàng (shop) được xác định tự động từ API Key, vì vậy bạn không cần truyền shopId trong bất kỳ request nào.

Nếu thiếu hoặc sai API Key, hệ thống trả về lỗi 401 Unauthorized:

⛔Thiếu API Key
{ "statusCode": 401, "message": "Thiếu API key" }
⛔API Key không hợp lệ
{ "statusCode": 401, "message": "API key không hợp lệ" }

3. Base URL & môi trường​

🔗Base URL - Production

GET https://api.minigift.vn/api

Toàn bộ endpoint của Open API dùng chung tiền tố /v1/open. Ví dụ đầy đủ:

https://api.minigift.vn/api/v1/open/gifts
Thành phầnGiá trịÝ nghĩa
Base URLhttps://api.minigift.vn/apiĐịa chỉ máy chủ Mini Gift
Tiền tố Open API/v1/openv1 là phiên bản API
Tài nguyên/gifts, /campaigns, /webhooksNhóm chức năng

4. Định dạng phản hồi (Response format)​

Mọi phản hồi thành công đều được bọc trong một envelope thống nhất với trường success: true:

{
  "data": {},
  "success": true
}

Với các API trả về danh sách, phản hồi kèm thêm thông tin phân trang trong meta:

{
  "data": [],
  "meta": { "total": 100, "page": 1, "limit": 10 },
  "success": true
}
TrườngKiểuMô tả
successbooleanLuôn là true với phản hồi thành công
dataobject | arrayDữ liệu trả về
meta.totalnumberTổng số bản ghi khớp điều kiện
meta.pagenumberTrang hiện tại
meta.limitnumberSố bản ghi mỗi trang
Quy ước dữ liệu trả về của Open API
  • Trường định danh được trả về dưới tên id (thay cho _id nội bộ). - Trường shopId được ẩn khỏi phản hồi (cửa hàng đã xác định qua API Key).
  • Thời gian trả về theo chuẩn ISO 8601 (UTC), ví dụ 2026-07-02T02:00:00.000Z.

5. Phân trang (Pagination)​

Các API danh sách nhận hai tham số truy vấn chung:

Tham sốKiểuMặc địnhGiới hạn
pagenumber1≥ 1
limitnumber101 – 1000

Ví dụ: GET /v1/open/gifts?page=2&limit=50.

6. Giới hạn truy cập (Rate limit)​

Mỗi API Key được phép gọi tối đa 30 request / 60 giây. Khi vượt ngưỡng, hệ thống trả về lỗi 429 Too Many Requests. Hãy triển khai cơ chế retry có độ trễ tăng dần (backoff) ở phía client.

7. Bảng mã trạng thái (HTTP status codes)​

MãÝ nghĩaKhi nào xảy ra
200OKRequest thành công
201CreatedTạo mới thành công
400Bad RequestDữ liệu gửi lên không hợp lệ (thiếu trường, sai định dạng, sai enum)
401UnauthorizedThiếu hoặc sai API Key
404Not FoundKhông tìm thấy tài nguyên (ID không tồn tại)
409ConflictTrùng lặp (ví dụ quà đã tồn tại, webhook đã đăng ký)
429Too Many RequestsVượt giới hạn rate limit
500Internal Server ErrorLỗi phía máy chủ

Cấu trúc phản hồi lỗi:

{
  "statusCode": 400,
  "message": "Mô tả lỗi cụ thể",
  "error": "Bad Request"
}

8. Danh sách API​

NhómMô tảTrang
Quản lý quà tặngTạo, cập nhật, xoá và tra cứu quà tặngQuản lý quà tặng
Chiến dịchLấy danh sách chiến dịch và thống kê khảo sátChiến dịch
WebhookĐăng ký nhận thông báo sự kiện theo thời gian thựcWebhook