Thêm sản phẩm liên quan vào tin tức

API này giúp bạn gắn một hoặc nhiều sản phẩm liên quan vào một bài viết tin tức. Các sản phẩm đã gắn sẽ xuất hiện trong trường items khi lấy danh sách tin tức, giúp Mini App hiển thị sản phẩm kèm theo bài viết.

---

Endpoint

🔗Endpoint Staging

http POST https://staging-manage.api.miniai.vn/api/external/news/{id}/items

🔗Endpoint Production

http POST https://manage-api.miniap.vn/api/external/news/{id}/items

Lưu ý về đường dẫn

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
Content-Type	application/json	Bắt buộc

Không cần gửi shopId

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

Tham số đường dẫn (Path Parameters)

Tham số	Kiểu	Yêu cầu	Mô tả
id	string	Bắt buộc	ID của tin tức cần gắn sản phẩm (ObjectId 24 ký tự hex)

Dữ liệu yêu cầu (Request Body)

Tham số (Parameters)

Trường	Kiểu	Yêu cầu	Mô tả
newsIds	string[]	Bắt buộc	Danh sách ID sản phẩm cần gắn vào bài viết (xem lưu ý bên dưới)

Tên trường newsIds thực chất là danh sách ID SẢN PHẨM

Dù có tên là newsIds, trường này nhận ID của sản phẩm, không phải ID tin tức. Bạn có thể lấy ID sản phẩm từ API Lấy danh sách sản phẩm.

Không lo trùng lặp

Sản phẩm đã gắn trước đó sẽ không bị thêm trùng — gọi lại API với cùng ID sản phẩm là an toàn (idempotent), danh sách sản phẩm liên quan vẫn chỉ chứa mỗi sản phẩm một lần.

Hệ thống không kiểm tra sản phẩm tồn tại

API chỉ kiểm tra tin tức có tồn tại hay không. ID sản phẩm sai (nhưng đúng định dạng ObjectId) vẫn được ghi nhận thành công — sản phẩm không tồn tại sẽ không hiển thị trong items khi truy xuất. Hãy đảm bảo dùng đúng ID từ API sản phẩm.

Request Body

{
    "newsIds": [
        "68c93dba802d36826bc45d01",
        "68c93dba802d36826bc45d02"
    ]
}

cURL (Staging)

curl -X POST 'https://staging-manage.api.miniai.vn/api/external/news/68c93dba802d36826bc45c9c/items' \
  -H 'x-api-key: miniai-partner <API_KEY_CỦA_BẠN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "newsIds": [
      "68c93dba802d36826bc45d01",
      "68c93dba802d36826bc45d02"
    ]
  }'

cURL (Production)

curl -X POST 'https://manage-api.miniap.vn/api/external/news/68c93dba802d36826bc45c9c/items' \
  -H 'x-api-key: miniai-partner <API_KEY_CỦA_BẠN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "newsIds": [
      "68c93dba802d36826bc45d01",
      "68c93dba802d36826bc45d02"
    ]
  }'

Phản hồi (Response)

Thành công trả về mã 200. Phản hồi chỉ gồm cờ success, không kèm dữ liệu bài viết. Để xem danh sách sản phẩm sau khi gắn, hãy gọi Lấy danh sách tin tức và kiểm tra trường items của bài viết.

Response

{
    "success": true
}

Lỗi thường gặp

Mã	Nguyên nhân
400	Thiếu newsIds, hoặc newsIds không phải mảng chuỗi
404	Không tìm thấy tin tức với id đã cho
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	id hoặc phần tử trong newsIds không đúng định dạng ObjectId, hoặc lỗi hệ thống

Lỗi 400 - Validation

{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "Validation failed",
    "validation": {
        "body": {
            "source": "body",
            "keys": ["newsIds"],
            "message": "\"newsIds\" is required"
        }
    }
}

Lỗi 404 - Không tìm thấy

{
    "error": "Resource not found",
    "message": "không tìm thấy tin tức"
}

Lỗi 429 - Quá giới hạn

{
    "error": "Too many requests, limit to 100 requests per minute"
}

Giới hạn (Rate limit)

100 request / phút

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

• Lấy danh sách tin tức — kiểm tra trường items của bài viết sau khi gắn
• Gỡ sản phẩm liên quan khỏi tin tức — bỏ sản phẩm đã gắn
• Lấy danh sách sản phẩm — tra cứu ID sản phẩm cần gắn