Khởi tạo tin tức

API này giúp bạn tạo một bài viết tin tức mới trong hệ thống. Bạn cần cung cấp tiêu đề và nội dung bài viết; ngoài ra có thể đính kèm ảnh và các nút hành động (CTA) dẫn tới Zalo Mini App.

Endpoint

🔗Endpoint Staging

http POST https://staging-manage.api.miniai.vn/api/external/news

🔗Endpoint Production

http POST https://manage-api.miniap.vn/api/external/news

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. Nếu bạn có gửi, giá trị đó sẽ bị ghi đè bằng gian hàng tương ứng với API key — bạn không thể tạo tin tức cho gian hàng khác.

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

Tham số (Parameters)

Chỉ type, title và content là bắt buộc. Các trường còn lại là tùy chọn.

Trường	Kiểu	Yêu cầu	Mặc định	Mô tả
`type`	`string`	Bắt buộc	—	Bắt buộc có mặt. Hệ thống luôn lưu là `news` — nên gửi `"news"`.
`title`	`string`	Bắt buộc	—	Tiêu đề bài viết. Dùng để sinh đường dẫn (`slug`).
`content`	`string`	Bắt buộc	—	Nội dung bài viết, hỗ trợ HTML.
`images`	`string[]`	Tùy chọn	—	Danh sách URL ảnh của bài viết.
`cta`	`object[]`	Tùy chọn	—	Danh sách nút hành động (xem bảng bên dưới).
`shortContent`	`string`	Tùy chọn	—	Được chấp nhận nhưng bỏ qua — hệ thống tự sinh từ `content`.
`status`	`string`	Tùy chọn	`active`	Được chấp nhận nhưng bỏ qua — tin tức luôn được tạo `active`.

Mỗi phần tử trong `cta[]`

Trường	Kiểu	Yêu cầu	Mô tả
`name`	`string`	Bắt buộc	Nhãn hiển thị của nút (vd: "Mua ngay")
`url`	`string`	Bắt buộc	Đường dẫn của nút. Bắt buộc khớp `https://zalo.me/s/...`

Ràng buộc đường dẫn CTA

cta[].url chỉ chấp nhận link Zalo Mini App theo định dạng https://zalo.me/s/<app-id>/<đường-dẫn>. Mọi đường dẫn khác (kể cả website https:// thông thường) sẽ bị từ chối với lỗi 400.

Các trường được xử lý tự động

Hệ thống tự sinh các giá trị sau

slug — sinh tự động từ title, đã bỏ dấu tiếng Việt và nối bằng dấu -. Slug là duy nhất trong mỗi gian hàng: nếu trùng, hệ thống tự thêm hậu tố -2, -3, ... (vd: khuyen-mai-thang-10 → khuyen-mai-thang-10-2).
shortContent — sinh tự động bằng cách loại bỏ thẻ HTML khỏi content và lấy 100 ký tự đầu tiên.
status — luôn là active khi tạo mới.
shopId — lấy từ API key.

Các trường KHÔNG được chấp nhận khi tạo mới

Body của API này không nhận slug, metaDescription và categoryId. Gửi kèm sẽ nhận lỗi 400 (vd: "slug" is not allowed). Nếu cần đặt slug hoặc metaDescription theo ý muốn, hãy tạo tin tức trước rồi gọi Cập nhật tin tức.

Request Body
cURL (Staging)
cURL (Production)

{
    "type": "news",
    "title": "Khuyến mãi tháng 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>",
    "images": [
        "https://dmcl0k8mc5oht.cloudfront.net/64204a17a5a97a86f12e1f0a/e888246f-2647-42f1-9d89-53eacdb7bf64.webp"
    ],
    "cta": [
        {
            "name": "Mua ngay",
            "url": "https://zalo.me/s/1234567890/products"
        }
    ]
}

curl -X POST 'https://staging-manage.api.miniai.vn/api/external/news' \
  -H 'x-api-key: miniai-partner <API_KEY_CỦA_BẠN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "news",
    "title": "Khuyến mãi tháng 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>",
    "images": [
      "https://dmcl0k8mc5oht.cloudfront.net/64204a17a5a97a86f12e1f0a/e888246f-2647-42f1-9d89-53eacdb7bf64.webp"
    ],
    "cta": [
      { "name": "Mua ngay", "url": "https://zalo.me/s/1234567890/products" }
    ]
  }'

curl -X POST 'https://manage-api.miniap.vn/api/external/news' \
  -H 'x-api-key: miniai-partner <API_KEY_CỦA_BẠN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "news",
    "title": "Khuyến mãi tháng 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>",
    "images": [
      "https://dmcl0k8mc5oht.cloudfront.net/64204a17a5a97a86f12e1f0a/e888246f-2647-42f1-9d89-53eacdb7bf64.webp"
    ],
    "cta": [
      { "name": "Mua ngay", "url": "https://zalo.me/s/1234567890/products" }
    ]
  }'

Phản hồi (Response)

Thành công trả về mã 200 kèm toàn bộ bản ghi tin tức vừa tạo trong data.

Response

{
    "success": true,
    "data": {
        "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": [],
        "_id": "68c93dba802d36826bc45c9c",
        "createdAt": "2025-09-16T10:36:42.809Z",
        "updatedAt": "2025-09-16T10:36:42.809Z",
        "__v": 0,
        "id": "68c93dba802d36826bc45c9c"
    }
}

Các trường trong `data`

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 (100 ký tự đầu của nội dung thuần)
`content`	`string`	Nội dung HTML đầy đủ
`status`	`string`	`active` hoặc `inactive`
`shopId`	`string`	ID gian hàng, lấy từ API key
`images`	`string[]`	Danh sách URL ảnh
`cta`	`object[]`	Danh sách nút hành động
`itemIds`	`string[]`	Danh sách ID sản phẩm liên quan (mặc định rỗng)
`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)

Lỗi thường gặp

Mã	Nguyên nhân
`400`	Thiếu trường bắt buộc, sai kiểu dữ liệu, `cta[].url` không đúng định dạng Zalo, hoặc gửi trường không được phép (`slug`, `metaDescription`, `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": {
        "body": {
            "source": "body",
            "keys": ["title"],
            "message": "\"title\" is required"
        }
    }
}

{
    "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

Sau khi tạo tin tức thành công, hãy lưu lại data.id để sử dụng cho:

Cập nhật tin tức — chỉnh sửa nội dung, đặt slug, metaDescription hoặc đổi status
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
Lấy danh sách tin tức — kiểm tra lại bài viết vừa tạo

Endpoint​

Xác thực (Authentication)​

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

Tham số (Parameters)​

Mỗi phần tử trong cta[]​

Các trường được xử lý tự động​

Phản hồi (Response)​

Các trường trong data​

Lỗi thường gặp​

Giới hạn (Rate limit)​

Các bước tiếp theo​