Lấy danh sách tin tức
API này giúp bạn truy xuất danh sách các bài viết tin tức đã được tạo trong gian hàng của mình, có hỗ trợ phân trang và tìm kiếm theo tiêu đề.
Endpoint
http GET https://staging-manage.api.miniai.vn/api/external/news
http GET https://manage-api.miniap.vn/api/external/news
API tin tức nằm trực tiếp dưới /api/external/news, không có tiền tố /v1 như API sản phẩm hay đơn hàng.
Xác thực (Authentication)
Mọi request phải gửi kèm API key của bạn trong header:
| Header | Giá trị | Yêu cầu |
|---|---|---|
x-api-key | miniai-partner <API_KEY_CỦA_BẠN> | Bắt buộc |
Hệ thống tự động xác định gian hàng (shopId) từ API key của bạn và gán vào request.
Vì vậy bạn không cần gửi shopId trong query. Nếu bạn có gửi, giá trị đó sẽ bị ghi đè
bằng gian hàng tương ứng với API key — kết quả trả về luôn là tin tức của gian hàng của bạn.
Tham số truy vấn (Query Parameters)
Tất cả tham số đều là tùy chọn.
| Tham số | Kiểu | Yêu cầu | Mặc định | Mô tả |
|---|---|---|---|---|
page | number | Tùy chọn | 1 | Trang cần lấy, số nguyên ≥ 1. |
limit | number | Tùy chọn | 10 | Số bài viết mỗi trang, từ 1 đến tối đa 50. |
search | string | Tùy chọn | — | Tìm kiếm theo tiêu đề — khớp một phần, không phân biệt hoa thường. |
sortBy | string | Tùy chọn | — | Được chấp nhận nhưng bỏ qua (xem lưu ý bên dưới). |
sortType | string | Tùy chọn | — | asc hoặc desc. Được chấp nhận nhưng bỏ qua. |
filters | string | Tùy chọn | — | Được chấp nhận nhưng bỏ qua. |
Danh sách luôn được sắp xếp theo thời điểm tạo, mới nhất trước (createdAt giảm dần).
Các tham số sortBy, sortType, filters hiện được chấp nhận để tương thích nhưng
không ảnh hưởng đến kết quả.
Query của API này không nhận categoryId. Gửi kèm sẽ nhận lỗi 400
(vd: "categoryId" is not allowed).
Ví dụ Request
- cURL (Staging)
- cURL (Production)
- URL đầy đủ
curl -X GET 'https://staging-manage.api.miniai.vn/api/external/news?page=1&limit=10&search=khuy%E1%BA%BFn%20m%C3%A3i' \
-H 'x-api-key: miniai-partner <API_KEY_CỦA_BẠN>'
curl -X GET 'https://manage-api.miniap.vn/api/external/news?page=1&limit=10&search=khuy%E1%BA%BFn%20m%C3%A3i' \
-H 'x-api-key: miniai-partner <API_KEY_CỦA_BẠN>'
GET /api/external/news?page=1&limit=10&search=khuyến mãi
Host: staging-manage.api.miniai.vn
x-api-key: miniai-partner <API_KEY_CỦA_BẠN>
Phản hồi (Response)
Thành công trả về mã 200. Danh sách bài viết nằm trong data.news, thông tin phân trang nằm trong data.meta.
- Response
{
"success": true,
"data": {
"news": [
{
"_id": "68c93dba802d36826bc45c9c",
"type": "news",
"title": "Khuyến mãi tháng 10",
"slug": "khuyen-mai-thang-10",
"shortContent": "Giảm giá 50% toàn bộ sản phẩm từ ngày 01/10 đến 31/10.",
"content": "<p>Giảm giá <strong>50%</strong> toàn bộ sản phẩm từ ngày 01/10 đến 31/10.</p>",
"status": "active",
"shopId": "64204a17a5a97a86f12e1f0a",
"images": [
"https://dmcl0k8mc5oht.cloudfront.net/64204a17a5a97a86f12e1f0a/e888246f-2647-42f1-9d89-53eacdb7bf64.webp"
],
"cta": [
{
"name": "Mua ngay",
"url": "https://zalo.me/s/1234567890/products"
}
],
"itemIds": [
"68c93dba802d36826bc45d01"
],
"items": [
{
"_id": "68c93dba802d36826bc45d01",
"name": "Tên sản phẩm",
"price": 20000,
"images": [
"https://dmcl0k8mc5oht.cloudfront.net/64204a17a5a97a86f12e1f0a/e888246f-2647-42f1-9d89-53eacdb7bf64.webp"
],
"slug": "ten-san-pham",
"id": "68c93dba802d36826bc45d01"
}
],
"createdAt": "2025-09-16T10:36:42.809Z",
"updatedAt": "2025-09-16T10:36:42.809Z",
"__v": 0,
"id": "68c93dba802d36826bc45c9c"
}
],
"meta": {
"page": 1,
"limit": 10,
"total": 1
}
}
}
Các trường trong data.news[]
| Trường | Kiểu | Mô tả |
|---|---|---|
id / _id | string | ID của tin tức — dùng cho các API cập nhật, xóa, gắn sản ph ẩm |
type | string | Luôn là news |
title | string | Tiêu đề bài viết |
slug | string | Đường dẫn thân thiện, duy nhất trong gian hàng |
shortContent | string | Tóm tắt tự sinh từ nội dung |
content | string | Nội dung HTML đầy đủ |
status | string | active hoặc inactive |
shopId | string | ID gian hàng |
images | string[] | Danh sách URL ảnh |
cta | object[] | Danh sách nút hành động (name, url) |
itemIds | string[] | Danh sách ID sản phẩm liên quan |
items | object[] | Sản phẩm liên quan đã kèm thông tin: name, price, images, slug |
createdAt | string | Thời điểm tạo (ISO 8601) |
updatedAt | string | Thời điểm cập nhật gần nhất (ISO 8601) |
Các trường trong data.meta
| Trường | Kiểu | Mô tả |
|---|---|---|
page | number | Trang hiện tại |
limit | number | Số bài viết mỗi trang |
total | number | Tổng số bài viết khớp điều kiện (mọi trang) |
Tổng số trang = Math.ceil(meta.total / meta.limit). Lặp qua page từ 1 đến giá trị này để lấy toàn bộ tin tức.
Lỗi thường gặp
| Mã | Nguyên nhân |
|---|---|
400 | Tham số sai kiểu (page/limit không phải số), limit vượt quá 50, sortType không phải asc/desc, hoặc gửi tham số không được phép (vd: categoryId) |
401 | Thiếu header x-api-key, sai tiền tố miniai-partner , hoặc API key không hợp lệ |
429 | Vượt giới hạn số request (xem mục Giới hạn bên dưới) |
500 | Lỗi hệ thống |
- Lỗi 400 - Validation
- Lỗi 429 - Quá giới hạn
{
"statusCode": 400,
"error": "Bad Request",
"message": "Validation failed",
"validation": {
"query": {
"source": "query",
"keys": ["limit"],
"message": "\"limit\" must be less than or equal to 50"
}
}
}
{
"error": "Too many requests, limit to 100 requests per minute"
}
Giới hạn (Rate limit)
Mỗi gian hàng được gọi tối đa 100 request mỗi phút trên toàn bộ External API.
Vượt quá giới hạn sẽ nhận mã 429.
Các bước tiếp theo
Với id của từng bài viết trong danh sách, bạn có thể:
- Khởi tạo tin tức — tạo bài viết mới
- Cập nhật tin tức — chỉnh sửa nội dung,
slug,metaDescriptionhoặcstatus - Xóa tin tức — xóa bài viết khỏi hệ thống
- Thêm sản phẩm liên quan vào tin tức — gắn sản phẩm vào bài viết