Cập nhật tin tức

API này giúp bạn chỉnh sửa một bài viết tin tức đã có theo id của bài viết.

Cập nhật từng phần (partial update)

Bạn chỉ cần gửi những trường muốn thay đổi — các trường không gửi sẽ giữ nguyên giá trị hiện tại. Đây cũng là API dùng để ẩn/hiện bài viết (qua status) và đặt slug, metaDescription — những trường không thể đặt khi Khởi tạo tin tức.

Endpoint

🔗Endpoint Staging

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

🔗Endpoint Production

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

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.

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 cập nhật (ObjectId 24 ký tự hex, vd: `68c93dba802d36826bc45c9c`)

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

Tham số (Parameters)

Tất cả các trường đều tùy chọn — chỉ gửi trường bạn muốn thay đổi.

Trường	Kiểu	Yêu cầu	Mô tả
`title`	`string`	Tùy chọn	Tiêu đề mới của bài viết.
`content`	`string`	Tùy chọn	Nội dung mới, hỗ trợ HTML. Khi thay đổi, `shortContent` sẽ được tự sinh lại.
`status`	`string`	Tùy chọn	`active` (hiển thị) hoặc `inactive` (ẩn khỏi Mini App).
`slug`	`string`	Tùy chọn	Đường dẫn mới (xem quy tắc bên dưới). Cho phép chuỗi rỗng `""`.
`metaDescription`	`string`	Tùy chọn	Mô tả SEO của bài viết. Cho phép chuỗi rỗng `""`.
`images`	`string[]`	Tùy chọn	Danh sách URL ảnh mới — thay thế toàn bộ danh sách ảnh hiện tại.
`cta`	`object[]`	Tùy chọn	Danh sách nút hành động mới — thay thế toàn bộ danh sách hiện tại.
`type`	`string`	Tùy chọn	Được chấp nhận nhưng bỏ qua.
`shortContent`	`string`	Tùy chọn	Được chấp nhận nhưng bỏ qua — luôn tự sinh từ `content`.

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 sẽ bị từ chối với lỗi 400.

Không hỗ trợ categoryId

Body 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).

Quy tắc xử lý `slug`

Bạn gửi	Kết quả
`slug` có giá trị	Slug được chuẩn hóa (bỏ dấu tiếng Việt, nối bằng `-`) và đảm bảo duy nhất trong gian hàng — nếu trùng, tự thêm hậu tố `-2`, `-3`, ...
`slug: ""` (chuỗi rỗng)	Giữ nguyên slug hiện tại. Nếu bài viết chưa có slug, hệ thống sinh mới từ `title`.
Không gửi `slug`	Giữ nguyên slug hiện tại. Nếu bài viết chưa có slug, hệ thống sinh mới từ `title`.

Request Body
cURL (Staging)
cURL (Production)
Ẩn bài viết

{
    "title": "Khuyến mãi tháng 10 - Gia hạn đến 15/11",
    "content": "<p>Chương trình giảm giá <strong>50%</strong> được gia hạn đến ngày 15/11.</p>",
    "status": "active",
    "slug": "khuyen-mai-thang-10-gia-han",
    "metaDescription": "Chương trình khuyến mãi tháng 10 gia hạn đến 15/11, giảm giá 50% toàn bộ sản phẩm."
}

curl -X PUT 'https://staging-manage.api.miniai.vn/api/external/news/68c93dba802d36826bc45c9c' \
  -H 'x-api-key: miniai-partner <API_KEY_CỦA_BẠN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Khuyến mãi tháng 10 - Gia hạn đến 15/11",
    "content": "<p>Chương trình giảm giá <strong>50%</strong> được gia hạn đến ngày 15/11.</p>",
    "status": "active",
    "slug": "khuyen-mai-thang-10-gia-han",
    "metaDescription": "Chương trình khuyến mãi tháng 10 gia hạn đến 15/11, giảm giá 50% toàn bộ sản phẩm."
  }'

curl -X PUT 'https://manage-api.miniap.vn/api/external/news/68c93dba802d36826bc45c9c' \
  -H 'x-api-key: miniai-partner <API_KEY_CỦA_BẠN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Khuyến mãi tháng 10 - Gia hạn đến 15/11",
    "content": "<p>Chương trình giảm giá <strong>50%</strong> được gia hạn đến ngày 15/11.</p>",
    "status": "active",
    "slug": "khuyen-mai-thang-10-gia-han",
    "metaDescription": "Chương trình khuyến mãi tháng 10 gia hạn đến 15/11, giảm giá 50% toàn bộ sản phẩm."
  }'

{
    "status": "inactive"
}

Phản hồi (Response)

Thành công trả về mã 200 kèm bản ghi tin tức sau khi cập nhật trong data.

Response

{
    "success": true,
    "data": {
        "_id": "68c93dba802d36826bc45c9c",
        "type": "news",
        "title": "Khuyến mãi tháng 10 - Gia hạn đến 15/11",
        "slug": "khuyen-mai-thang-10-gia-han",
        "shortContent": "Chương trình giảm giá 50% được gia hạn đến ngày 15/11.",
        "content": "<p>Chương trình giảm giá <strong>50%</strong> được gia hạn đến ngày 15/11.</p>",
        "metaDescription": "Chương trình khuyến mãi tháng 10 gia hạn đến 15/11, giảm giá 50% toàn bộ sản phẩm.",
        "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": [],
        "createdAt": "2025-09-16T10:36:42.809Z",
        "updatedAt": "2025-09-16T11:02:15.331Z",
        "__v": 0,
        "id": "68c93dba802d36826bc45c9c"
    },
    "meta": {}
}

Lỗi thường gặp

Mã	Nguyên nhân
`400`	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 (vd: `categoryId`)
`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` không đúng định dạng ObjectId (24 ký tự hex) hoặc lỗi hệ thống

Lỗi 400 - Validation
Lỗi 404 - Không tìm thấy
Lỗi 429 - Quá giới hạn

{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "Validation failed",
    "validation": {
        "body": {
            "source": "body",
            "keys": ["cta.0.url"],
            "message": "\"cta[0].url\" with value \"https://example.com\" fails to match the required pattern: /^https:\\/\\/zalo\\.me\\/s\\/.+$/"
        }
    }
}

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

{
    "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 lại bài viết sau khi cập nhật
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
Xóa tin tức — xóa vĩnh viễn bài viết khỏi hệ thống

Endpoint​

Xác thực (Authentication)​

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

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

Tham số (Parameters)​

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

Quy tắc xử lý slug​

Phản hồi (Response)​

Lỗi thường gặp​

Giới hạn (Rate limit)​

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