Skip to main content

Create News

This API lets you create a new news article in the system. You must provide a title and content; you can also optionally attach images and call-to-action (CTA) buttons linking to your 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

A note on the path

The news API sits directly under /api/external/news, without the /v1 prefix used by the product and order APIs.

Authentication​

Every request must include your API key in the header:

HeaderValueRequired
x-api-keyminiai-partner <YOUR_API_KEY>Bắt buộc
Content-Typeapplication/jsonBắt buộc
No need to send shopId

The system automatically determines your shop (shopId) from your API key and assigns it to the request. So you don't need to send shopId in the body. If you do send it, that value will be overwritten with the shop matching your API key — you cannot create news for another shop.

Request Body​

Parameters​

Only type, title, and content are required. All other fields are optional.

FieldTypeRequiredDefaultDescription
typestringBắt buộc—Must be present. The system always stores news — send "news".
titlestringBắt buộc—The article title. Used to generate the slug.
contentstringBắt buộc—The article content, HTML supported.
imagesstring[]Tùy chọn—List of image URLs for the article.
ctaobject[]Tùy chọn—List of call-to-action buttons (see table below).
shortContentstringTùy chọn—Accepted but ignored — auto-generated from content.
statusstringTùy chọnactiveAccepted but ignored — news is always created as active.

Each element in cta[]​

FieldTypeRequiredDescription
namestringBắt buộcButton label (e.g. "Buy now")
urlstringBắt buộcButton destination. Must match https://zalo.me/s/...
CTA URL constraint

cta[].url only accepts Zalo Mini App links in the format https://zalo.me/s/<app-id>/<path>. Any other URL (including regular https:// websites) will be rejected with a 400 error.

Fields handled automatically​

The system auto-generates the following values
  • slug — auto-generated from title, with Vietnamese diacritics stripped and joined with -. The slug is unique per shop: if it collides, the system appends a suffix -2, -3, ... (e.g. khuyen-mai-thang-10 → khuyen-mai-thang-10-2).
  • shortContent — auto-generated by stripping HTML tags from content and taking the first 100 characters.
  • status — always active on creation.
  • shopId — taken from the API key.
Fields NOT accepted on creation

This API's body does not accept slug, metaDescription, or categoryId. Sending them returns a 400 error (e.g. "slug" is not allowed). If you need to set a custom slug or metaDescription, create the news article first, then call Update News.

{
    "type": "news",
    "title": "October Promotion",
    "content": "<p>50% off <strong>everything</strong> from 10/01 to 10/31.</p>",
    "images": [
        "https://dmcl0k8mc5oht.cloudfront.net/64204a17a5a97a86f12e1f0a/e888246f-2647-42f1-9d89-53eacdb7bf64.webp"
    ],
    "cta": [
        {
            "name": "Buy now",
            "url": "https://zalo.me/s/1234567890/products"
        }
    ]
}

Response​

Success returns 200 with the full created news record in data.

{
    "success": true,
    "data": {
        "type": "news",
        "title": "October Promotion",
        "slug": "october-promotion",
        "shortContent": "50% off everything from 10/01 to 10/31.",
        "content": "<p>50% off <strong>everything</strong> from 10/01 to 10/31.</p>",
        "status": "active",
        "shopId": "64204a17a5a97a86f12e1f0a",
        "images": [
            "https://dmcl0k8mc5oht.cloudfront.net/64204a17a5a97a86f12e1f0a/e888246f-2647-42f1-9d89-53eacdb7bf64.webp"
        ],
        "cta": [
            {
                "name": "Buy now",
                "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"
    }
}

Fields in data​

FieldTypeDescription
id / _idstringNews article ID — used for update, delete, and product-linking APIs
typestringAlways news
titlestringArticle title
slugstringFriendly URL path, unique per shop
shortContentstringAuto-generated summary (first 100 characters of plain-text content)
contentstringFull HTML content
statusstringactive or inactive
shopIdstringShop ID, taken from the API key
imagesstring[]List of image URLs
ctaobject[]List of call-to-action buttons
itemIdsstring[]List of related product IDs (empty by default)
createdAtstringCreation time (ISO 8601)
updatedAtstringLast update time (ISO 8601)

Common Errors​

CodeCause
400Missing required field, wrong data type, cta[].url not in the Zalo format, or a disallowed field was sent (slug, metaDescription, categoryId)
401Missing x-api-key header, wrong miniai-partner prefix, or invalid API key
429Rate limit exceeded (see the Rate Limit section below)
500System error
{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "Validation failed",
    "validation": {
        "body": {
            "source": "body",
            "keys": ["title"],
            "message": "\"title\" is required"
        }
    }
}

Rate Limit​

100 requests / minute

Each shop can make at most 100 requests per minute across the entire External API. Exceeding this limit returns a 429 status.

Next Steps​

After successfully creating a news article, save data.id to use for: