Bắt đầu
Mọi endpoint nằm dưới địa chỉ gốc:
https://api.dybiweb.com/api/public/v1
- Đăng nhập CMS bằng tài khoản có quyền quản trị cấu hình, vào Cấu hình → Kết nối → API.
- Tạo API key: đặt tên gợi nhớ, chọn quyền cần dùng và thời hạn (30 ngày đến 2 năm).
- Sao chép key ngay khi tạo. Key chỉ hiển thị một lần; hệ thống không lưu bản gốc.
- Gọi thử endpoint kiểm tra key:
curl https://api.dybiweb.com/api/public/v1/me \
-H "X-Api-Key: dybi_live_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
{
"companyId": "5b0c…",
"companyName": "Tên doanh nghiệp",
"keyName": "Công cụ đăng bài",
"scopes": ["articles:read", "articles:write", "files:read", "files:write"],
"expiresUtc": "2027-10-28T04:37:31Z"
}
Xác thực và quyền
Gửi key trong header X-Api-Key ở mọi yêu cầu, chỉ qua HTTPS. Không đặt key trên địa chỉ URL hoặc trong mã chạy trên trình duyệt: yêu cầu có header Origin của trình duyệt sẽ bị từ chối.
Key thuộc về một doanh nghiệp và hoạt động với danh nghĩa người đã tạo key: bài tạo qua API ghi người đó là người tạo. Key chỉ đọc, ghi dữ liệu của doanh nghiệp mình.
| Quyền (scope) | Cho phép |
|---|---|
articles:read | Xem danh mục và bài viết |
articles:write | Thêm và sửa bài viết, sửa nội dung danh mục bài viết |
products:read | Xem danh mục và sản phẩm |
products:write | Thêm và sửa sản phẩm, sửa nội dung danh mục sản phẩm |
media:read | Xem danh mục đa phương tiện |
media:write | Sửa nội dung danh mục đa phương tiện |
files:read | Xem danh sách ảnh trong thư viện |
files:write | Upload ảnh |
Key ngừng hoạt động ngay khi bị thu hồi trong CMS, hết hạn, hoặc khi người tạo bị khóa tài khoản hay không còn quyền quản trị cấu hình. Khi đó hãy tạo key mới. Nếu nghi key bị lộ, thu hồi ngay; lịch sử sử dụng key xem ở tab Lịch sử cùng màn hình.
Key chỉ sửa được bài viết, sản phẩm, danh mục do người tạo key thêm. Muốn sửa nội dung của người khác, người tạo key cần quyền sửa nội dung của người khác trong CMS. Key tạo trước khi có quyền sản phẩm không tự có quyền này; hãy tạo key mới.
Giới hạn
| Mục | Giới hạn |
|---|---|
| Số yêu cầu | 60 yêu cầu/phút cho mỗi key |
| Upload ảnh | 20 ảnh/phút cho mỗi key, tính cả ảnh gửi qua POST /files và ảnh gửi kèm bài viết, sản phẩm |
| Xác thực sai | 30 lần/phút cho mỗi địa chỉ IP, sau đó tạm chặn 1 phút |
| File ảnh | JPG, PNG, WEBP, GIF; tối đa 5 MB; tối đa 8000px mỗi chiều, 25 triệu điểm ảnh, 300 khung hình |
| Bài viết, sản phẩm | Tiêu đề 300 ký tự; mô tả ngắn 2000 ký tự; nội dung 1.000.000 ký tự; tối đa 20 thẻ, mỗi thẻ 100 ký tự |
| Sản phẩm | Mã sản phẩm 30 ký tự; đơn vị tính 30 ký tự; tối đa 20 ảnh phụ, tối đa 5 ảnh phụ mỗi lần gửi |
| Request thêm, sửa | Mỗi request POST/PATCH bài viết, sản phẩm tối đa 30 triệu byte (khoảng 28 MB), tính cả ảnh base64 |
| Phân trang | pageSize tối đa 100 |
Vượt giới hạn tần suất nhận mã 429 kèm header Retry-After (số giây cần chờ). Hãy chờ đúng thời gian đó rồi gửi lại.
Đăng bài có ảnh
- Upload từng ảnh chèn trong nội dung bằng
POST /files. Kết quả cóurl(ảnh gốc) vàwebpUrl(bản WebP do hệ thống tạo). - Chèn
urlvào nội dung bài, ví dụ<img src="…" alt="Mô tả ảnh">. - Lấy
iddanh mục bằngGET /categories. - Tạo bài bằng
POST /articles, gửi kèm ảnh đại diện trong trườngimage(xem ảnh đại diện và ảnh phụ). Bài mới mặc định là nháp. - Kiểm tra trong CMS, rồi đăng bằng
PATCH /articles/{id}với"isPublished": true(hoặc gửi luôn khi tạo bài).
Sản phẩm làm tương tự: POST /products nhận ảnh đại diện trong image và ảnh phụ trong gallery. Ảnh đại diện bài viết, ảnh đại diện và ảnh phụ sản phẩm được lưu thẳng vào thư mục riêng giống khi chọn ảnh trong CMS; thư viện ảnh của POST /files chỉ dành cho ảnh chèn trong nội dung.
Danh sách endpoint
| Method | Đường dẫn | Quyền | Mô tả |
|---|---|---|---|
| GET | /me | bất kỳ | Thông tin key và doanh nghiệp |
| GET | /categories | articles:read, products:read hoặc media:read | Danh sách danh mục; lọc theo loại bằng type=article, type=product hoặc type=media |
| GET | /categories/{id} | articles:read, products:read hoặc media:read theo loại danh mục | Chi tiết danh mục |
| PATCH | /categories/{id} | articles:write, products:write hoặc media:write theo loại danh mục | Sửa nội dung danh mục |
| GET | /articles | articles:read | Danh sách bài viết |
| GET | /articles/{id} | articles:read | Chi tiết bài viết |
| POST | /articles | articles:write | Thêm bài viết |
| PATCH | /articles/{id} | articles:write | Sửa bài viết |
| GET | /products | products:read | Danh sách sản phẩm |
| GET | /products/{id} | products:read | Chi tiết sản phẩm |
| POST | /products | products:write | Thêm sản phẩm |
| PATCH | /products/{id} | products:write | Sửa sản phẩm |
| POST | /files | files:write | Upload ảnh chèn trong nội dung |
| GET | /files | files:read | Danh sách ảnh, kèm link |
Danh mục
API lấy danh sách, xem và sửa nội dung danh mục bài viết, sản phẩm, đa phương tiện đã có. Thêm, xóa danh mục, đổi loại, danh mục cha, thứ tự và trạng thái hiển thị vẫn làm trong CMS. Quyền cần có theo loại của danh mục: articles:* cho danh mục bài viết, products:* cho danh mục sản phẩm, media:* cho danh mục đa phương tiện.
GET /categories
Tham số tùy chọn: language (mặc định vi) để lấy tên danh mục theo ngôn ngữ; type là article (danh mục bài viết, cần articles:read), product (danh mục sản phẩm, cần products:read) hoặc media (danh mục đa phương tiện, cần media:read). Không gửi type thì trả tất cả danh mục thuộc các loại key được đọc: danh mục bài viết trước, rồi danh mục sản phẩm, cuối cùng là danh mục đa phương tiện, mỗi nhóm theo thứ tự trong CMS. Mỗi danh mục có type cho biết loại.
[
{ "id": "8f0e…", "type": "article", "parentId": null, "title": "Tin tức", "isPublished": true, "order": 1 },
{ "id": "51c9…", "type": "product", "parentId": null, "title": "Gọng kính", "isPublished": true, "order": 1 },
{ "id": "a7d2…", "type": "media", "parentId": null, "title": "Thư viện ảnh", "isPublished": true, "order": 1 }
]
GET /categories/{id}
Tham số tùy chọn language. Trả về type (article, product hoặc media), parentId, title, brief, content, isPublished, order, imageUrl, path/url trên website, seo và các ngôn ngữ đã có. Danh mục chưa có bản ngôn ngữ được yêu cầu trả 404.
PATCH /categories/{id}
Chỉ gửi những trường cần đổi; trường không gửi hoặc null giữ nguyên. Các trường khác như parentId, order, isPublished nếu gửi sẽ bị bỏ qua.
| Trường | Ghi chú |
|---|---|
language | Bản ngôn ngữ cần sửa, mặc định vi; gửi ngôn ngữ danh mục chưa có để thêm bản dịch, khi đó cần title |
title | Tên danh mục, văn bản thuần, tối đa 300 ký tự |
brief | Mô tả ngắn, văn bản thuần |
content | Nội dung HTML, làm sạch theo quy tắc nội dung |
image | Thay ảnh danh mục; định dạng như ảnh đại diện |
seo | Đường dẫn SEO và các thẻ meta; xem SEO. Danh mục đang tắt "SEO danh mục" trong CMS trả 422 khi gửi trường này |
curl -X PATCH https://api.dybiweb.com/api/public/v1/categories/51c9… \
-H "X-Api-Key: $DYBI_API_KEY" -H "Content-Type: application/json" \
-d '{
"brief": "Gọng kính chính hãng, bảo hành 12 tháng.",
"content": "<h2>Chọn gọng kính</h2><p>…</p>",
"seo": { "title": "Gọng kính chính hãng [year]", "metaDescription": "Gọng kính nhiều mẫu, giao nhanh." }
}'
Chỉ sửa được danh mục do người tạo key thêm, trừ khi người đó có quyền sửa nội dung của người khác. Sau khi sửa, website tự làm mới để nội dung mới hiển thị ngay.
Bài viết
GET /articles
Tham số tùy chọn: categoryId, q (tìm theo tiêu đề, gõ có dấu hoặc không dấu), language, page (mặc định 1), pageSize (mặc định 20). Bài mới nhất theo ngày hiển thị đứng trước.
{
"items": [{
"id": "3c1d…", "categoryId": "8f0e…", "title": "Bài viết đầu tiên", "type": "NewsArticle",
"isPublished": false, "displayDate": "2026-10-28T10:00:00", "order": 50,
"coverUrl": "https://api.dybiweb.com/Files/…/Article/bai-viet-dau-tien_638….jpg",
"path": "/bai-viet-dau-tien", "url": "https://ten-mien-cua-ban/bai-viet-dau-tien",
"languages": ["vi"]
}],
"total": 1, "page": 1, "pageSize": 20
}
GET /articles/{id}
Tham số tùy chọn language. Trả về tiêu đề, loại bài viết, mô tả ngắn, nội dung HTML, thẻ, ngày hiển thị, trạng thái đăng, ảnh đại diện, đường dẫn trên website, SEO (seo) và các ngôn ngữ đã có. Trả 404 nếu bài chưa có bản ngôn ngữ được yêu cầu.
POST /articles
curl -X POST https://api.dybiweb.com/api/public/v1/articles \
-H "X-Api-Key: $DYBI_API_KEY" -H "Content-Type: application/json" \
-d '{
"categoryId": "8f0e…",
"title": "Bài viết đầu tiên",
"type": "NewsArticle",
"brief": "Tóm tắt ngắn hiển thị ở danh sách bài.",
"content": "<h2>Mở đầu</h2><p>Nội dung…</p>",
"tags": ["website", "seo"],
"isPublished": false,
"image": { "fileName": "anh-bia.jpg", "data": "/9j/4AAQSkZJRg…" },
"seo": { "seoUrl": "/bai-viet-dau-tien", "title": "Bài viết đầu tiên [year]", "metaDescription": "Mô tả hiển thị trên Google." }
}'
| Trường | Bắt buộc | Ghi chú |
|---|---|---|
categoryId | Có | Danh mục bài viết lấy từ GET /categories |
title | Có | Văn bản thuần, tối đa 300 ký tự; dùng để tạo đường dẫn SEO |
brief | Có | Văn bản thuần, thẻ HTML sẽ bị bỏ |
type | Không | Loại bài viết, mặc định Article; xem bảng loại bài viết |
content | Không | HTML, được làm sạch theo quy tắc nội dung |
language | Không | Mặc định vi; phải là ngôn ngữ đã bật cho website |
tags | Không | Danh sách thẻ; thẻ trùng sẽ được gộp |
displayDate | Không | Ngày hiển thị, mặc định là thời điểm tạo |
isPublished | Không | Mặc định false (nháp) |
order | Không | Thứ tự sắp xếp, mặc định 50 |
image | Không | Ảnh đại diện; xem ảnh đại diện và ảnh phụ |
seo | Không | Đường dẫn SEO, Meta Title, Meta Description, Meta Keyword; trường không gửi được tạo tự động; xem SEO |
id | Không | GUID do bạn chọn. Gửi lại cùng id sau khi mất kết nối sẽ nhận 409 thay vì tạo bài trùng |
Thành công trả 201, header Location và nội dung bài như GET /articles/{id}, gồm cả path/url trên website.
Loại (type) | Nội dung phù hợp |
|---|---|
Article | Bài hướng dẫn; bài nghiên cứu hoặc phân tích có bằng chứng, dữ liệu hay nguồn kiểm chứng rõ ràng. |
NewsArticle | Bài tin tức, đưa tin về sự kiện, thông báo hoặc diễn biến có tính thời sự. |
BlogPosting | Bài blog, chia sẻ trải nghiệm hoặc trình bày quan điểm cá nhân. |
Loại bài viết giống lựa chọn "Loại" trong CMS và được website dùng làm kiểu dữ liệu có cấu trúc (schema.org) của trang bài.
PATCH /articles/{id}
Chỉ gửi những trường cần đổi; trường không gửi hoặc null giữ nguyên. Gửi "content": "" để xóa nội dung, "tags": [] để xóa thẻ. Trường language chọn bản ngôn ngữ cần sửa (mặc định vi); gửi một ngôn ngữ bài chưa có để thêm bản dịch, khi đó cần title và brief. Gửi image để thay ảnh đại diện, seo để sửa SEO.
curl -X PATCH https://api.dybiweb.com/api/public/v1/articles/3c1d… \
-H "X-Api-Key: $DYBI_API_KEY" -H "Content-Type: application/json" \
-d '{ "isPublished": true }'
Sản phẩm
Sản phẩm được lưu như khi thêm ở màn hình Sản phẩm trong CMS. Đơn vị quy đổi, thuộc tính, sản phẩm kèm theo, công thức, serial và tồn kho vẫn quản lý trong CMS.
GET /products
Tham số tùy chọn: categoryId, q (tìm theo tên có dấu hoặc không dấu, hoặc đúng mã sản phẩm), code (lọc đúng mã), language, page, pageSize (mặc định 20). Sắp xếp theo thứ tự rồi mới nhất trước.
{
"items": [{
"id": "7a2b…", "categoryId": "51c9…", "code": "8931234567890", "title": "Gấu bông Teddy 40cm",
"type": "HangHoa", "unit": "Cái", "price": 250000, "vat": 8, "priceWithVat": 270000,
"discountType": "percent", "discount": 10, "priceAfterDiscount": 225000,
"isPublished": true, "order": 50,
"imageUrl": "https://api.dybiweb.com/Files/…/Product/gau-bong-teddy-40cm_638….jpg",
"path": "/gau-bong-teddy-40cm", "url": "https://ten-mien-cua-ban/gau-bong-teddy-40cm",
"languages": ["vi"]
}],
"total": 1, "page": 1, "pageSize": 20
}
GET /products/{id}
Tham số tùy chọn language. Trả về các trường như danh sách, thêm brief, content, tags, gallery (ảnh phụ, mỗi ảnh có fileName và url), seo (xem SEO), createdAt, updatedAt.
POST /products
curl -X POST https://api.dybiweb.com/api/public/v1/products \
-H "X-Api-Key: $DYBI_API_KEY" -H "Content-Type: application/json" \
-d '{
"categoryId": "51c9…",
"title": "Gấu bông Teddy 40cm",
"unit": "Cái",
"price": 250000,
"vat": 8,
"discountType": "percent",
"discount": 10,
"content": "<p>Chất liệu, kích thước…</p>",
"isPublished": false,
"image": { "fileName": "teddy.jpg", "data": "/9j/4AAQSkZJRg…" },
"gallery": [
{ "fileName": "teddy-sau.png", "data": "iVBORw0KGgo…" }
]
}'
| Trường | Bắt buộc | Ghi chú |
|---|---|---|
categoryId | Có | Danh mục sản phẩm lấy từ GET /categories?type=product |
title | Có | Tên sản phẩm, văn bản thuần, tối đa 300 ký tự; không trùng tên sản phẩm khác trong cùng danh mục |
unit | Có | Đơn vị tính cơ bản, ví dụ Cái, Hộp, Kg; tối đa 30 ký tự |
price | Không | Giá bán trước thuế, mặc định 0 |
vat | Không | Thuế suất GTGT, mặc định -2; xem bảng VAT |
discountType | Không | none (mặc định), percent (giảm theo %) hoặc amount (giảm số tiền) |
discount | Khi có giảm giá | Phần trăm từ 0 đến 100, hoặc số tiền không lớn hơn price |
code | Không | Mã sản phẩm, tối đa 30 ký tự, không trùng trong doanh nghiệp. Bỏ trống thì hệ thống tạo mã EAN-13 như CMS |
type | Không | Loại sản phẩm, mặc định HangHoa; xem bảng loại sản phẩm |
brief | Không | Mô tả ngắn, văn bản thuần; bỏ trống thì dùng tên sản phẩm |
content | Không | Mô tả chi tiết bằng HTML, làm sạch theo quy tắc nội dung |
image | Không | Ảnh đại diện; xem ảnh đại diện và ảnh phụ |
gallery | Không | Danh sách ảnh phụ, tối đa 5 ảnh phụ mỗi lần gửi |
language, tags, isPublished, order, id, seo | Không | Như bài viết; sản phẩm mới mặc định là nháp |
Thành công trả 201, header Location và nội dung như GET /products/{id}. Kết quả có thêm priceWithVat (giá gồm thuế) và priceAfterDiscount (giá trước thuế sau giảm giá, cách tính như CMS). Trùng mã hoặc trùng tên trong danh mục trả 409.
vat | Ý nghĩa |
|---|---|
-2 | Không kê khai |
-1 | Không chịu thuế |
0, 5, 8, 10 | Thuế suất phần trăm |
Doanh nghiệp tính thuế theo phương pháp trực tiếp chỉ chọn được -2, -1 hoặc 0, giống CMS. Giá trị khác trả 400 kèm danh sách hợp lệ.
Loại (type) | Ý nghĩa |
|---|---|
HangHoa | Hàng hóa |
DichVu | Dịch vụ |
ThanhPham | Thành phẩm |
BanThanhPham | Bán thành phẩm |
CongCuDungCu | Công cụ dụng cụ |
NguyenVatLieu | Nguyên vật liệu |
TaiSanCoDinh | Tài sản cố định |
Sản phẩm có kiểu giảm giá đặt trực tiếp giá bán trong CMS trả "discountType": "price"; khi đó discount là giá bán. API không nhận kiểu này khi thêm, sửa.
PATCH /products/{id}
Chỉ gửi những trường cần đổi, như bài viết; seo sửa SEO. Đổi discountType sang percent hoặc amount cần gửi kèm discount. Ảnh đổi bằng các trường:
| Trường | Ghi chú |
|---|---|
image | Thay ảnh đại diện |
galleryAdd | Thêm ảnh phụ, tối đa 5 ảnh mỗi lần gửi |
galleryRemove | Danh sách fileName ảnh phụ cần xóa, lấy từ trường gallery của sản phẩm |
Sản phẩm có tối đa 20 ảnh phụ, tính sau khi đã xóa các ảnh trong galleryRemove và thêm các ảnh trong galleryAdd.
curl -X PATCH https://api.dybiweb.com/api/public/v1/products/7a2b… \
-H "X-Api-Key: $DYBI_API_KEY" -H "Content-Type: application/json" \
-d '{
"price": 230000,
"galleryAdd": [ { "fileName": "teddy-ben.jpg", "data": "/9j/4AAQSkZJRg…" } ],
"galleryRemove": [ "gau-bong-teddy-40cm-1_638…_a1b2.png" ]
}'
Ảnh đại diện và ảnh phụ
Ảnh gửi kèm trong JSON của POST/PATCH bài viết, sản phẩm, mỗi ảnh là một đối tượng:
| Trường | Ghi chú |
|---|---|
fileName | Tên file gốc; đuôi file phải khớp với nội dung ảnh. Có thể bỏ khi data là data URL |
data | Nội dung file mã hóa base64, hoặc data URL dạng data:image/png;base64,… |
- Quy định ảnh giống
POST /files: JPG, PNG, WEBP, GIF, mỗi ảnh tối đa 5 MB (trước khi mã hóa base64), được kiểm tra nội dung thật và mã hóa lại. - Ảnh được lưu vào thư mục ảnh bài viết, ảnh sản phẩm hoặc ảnh phụ như khi chọn trong CMS, tên file đặt theo tiêu đề.
- Tất cả dữ liệu và ảnh được kiểm tra trước khi lưu: một ảnh lỗi thì cả request bị từ chối và không có gì được lưu. Thông báo lỗi ghi rõ trường, ví dụ
gallery[1]: …. - Ảnh cũ bị thay hoặc bị xóa chỉ bị xóa khỏi kho lưu trữ sau khi lưu thành công.
- Mỗi ảnh tính vào giới hạn 20 ảnh/phút. Base64 làm dữ liệu lớn hơn khoảng 1/3; request vượt giới hạn kích thước thì chia ảnh ra nhiều lần
PATCH.
SEO
Mỗi bản ngôn ngữ của bài viết, sản phẩm, danh mục có một bộ SEO giống ô SEO trong CMS. Gửi đối tượng seo khi POST hoặc PATCH; GET chi tiết trả về giá trị hiện tại. SEO áp dụng cho bản ngôn ngữ trong trường language của request.
| Trường | Ghi chú |
|---|---|
seoUrl | Đường dẫn trên website, ví dụ /kinh-chong-anh-sang-xanh; thiếu dấu / đầu sẽ được thêm. Chỉ gồm chữ không dấu, số và - _ . ~ /, tối đa 200 ký tự, không có khoảng trắng hay //, không trùng đường dẫn khác của website |
title | Meta Title, tối đa 65 ký tự |
metaDescription | Meta Description, tối đa 155 ký tự |
metaKeyword | Meta Keyword, tối đa 500 ký tự |
- Trường không gửi hoặc
null: khi thêm, hệ thống tạo như CMS (đường dẫn và Meta Title, Meta Keyword theo tiêu đề, Meta Description theo mô tả ngắn); khi sửa, giữ nguyên. Đổi tiêu đề không đổi đường dẫn SEO. - Meta Title, Meta Description, Meta Keyword dùng được từ khóa thay thế như
[year], giống CMS; không gửi chuỗi rỗng. Đường dẫn SEO không nhận từ khóa thay thế. - Đường dẫn đã có nội dung, trang hoặc chuyển hướng khác dùng (không phân biệt hoa thường) trả
409. - Đổi
seoUrlcủa bài, sản phẩm đã có thì đường dẫn cũ tự chuyển hướng 301 sang đường dẫn mới, để link đã chia sẻ và kết quả Google không bị lỗi 404. Đổi về đúng đường dẫn cũ thì chuyển hướng đó được bỏ. Chuyển hướng hiện trong mục SEO của CMS và không đưa vào sitemap. - Danh mục chưa gắn trang chi tiết thì nội dung không có đường dẫn SEO; gửi
seokhi đó trả422.
curl -X PATCH https://api.dybiweb.com/api/public/v1/products/7a2b… \
-H "X-Api-Key: $DYBI_API_KEY" -H "Content-Type: application/json" \
-d '{ "seo": { "seoUrl": "/gau-bong-teddy", "metaDescription": "Gấu bông Teddy 40cm mềm mịn, giao nhanh." } }'
File ảnh
POST /files
Gửi multipart/form-data với đúng một file trong trường file. Ảnh được kiểm tra nội dung thật, mã hóa lại và lưu với tên do hệ thống đặt. Khi mã hóa lại, toàn bộ metadata EXIF, IPTC và XMP (gồm vị trí, bản quyền, thông tin nguồn ảnh) và chứng thực C2PA bị bỏ; chỉ giữ hồ sơ màu ICC và độ trong suốt. Ghi công hoặc ghi chú ảnh AI nên đặt trong chú thích, alt của nội dung. Ảnh không bị thu nhỏ, hãy upload đúng kích thước muốn hiển thị.
Endpoint này dành cho ảnh chèn trong nội dung bài viết, sản phẩm: ảnh vào thư viện ảnh của website (cùng thư viện với trình chọn ảnh trong trình soạn thảo CMS), rồi chèn url vào nội dung. Ảnh đại diện và ảnh phụ gửi kèm khi thêm, sửa bài viết, sản phẩm (xem ảnh đại diện và ảnh phụ).
curl -X POST https://api.dybiweb.com/api/public/v1/files \
-H "X-Api-Key: $DYBI_API_KEY" \
-F "[email protected]"
{
"fileName": "20261028103000_a1b2c3d4_anh-bia.jpg",
"url": "https://api.dybiweb.com/Files/…/20261028103000_a1b2c3d4_anh-bia.jpg",
"webpUrl": "https://api.dybiweb.com/Files/…/20261028103000_a1b2c3d4_anh-bia.jpg.webp",
"size": 182344, "contentType": "image/jpeg", "width": 1600, "height": 900,
"modifiedUtc": "2026-10-28T03:30:00Z"
}
File lớn hơn giới hạn nhận 413. Với file lớn, curl tự gửi Expect: 100-continue nên nhận được thông báo lỗi trước khi gửi hết dữ liệu; thư viện khác nên bật tùy chọn tương tự hoặc kiểm tra kích thước trước khi gửi.
GET /files
Danh sách ảnh trong thư viện của website (cùng thư viện với trình chọn ảnh trong CMS), mới nhất trước. Tham số tùy chọn: q (tìm theo tên file), page, pageSize (mặc định 50). Mỗi ảnh có fileName, url, webpUrl, size, modifiedUtc.
HTML được phép trong nội dung
Nội dung được làm sạch về đúng định dạng trình soạn thảo của CMS để có thể tiếp tục sửa trong CMS:
- Giữ: đoạn văn, tiêu đề
h2–h6, in đậm/nghiêng/gạch chân/gạch ngang, chỉ số trên/dưới, danh sách, trích dẫn, khối mã, liên kết, ảnh và video YouTube/Vimeo nhúng. h1được đổi thànhh2vì tiêu đề bài là H1 duy nhất của trang.- Ảnh phải dùng địa chỉ
https://; nên dùngurlnhận từPOST /filesvà luôn cóalt. - Chỉ giữ class căn lề/thụt lề của trình soạn thảo (
ql-align-*,ql-indent-*…) và màu chữ/màu nền. - Bỏ: script, style, form, iframe khác YouTube/Vimeo, thuộc tính sự kiện (
onclick…), liên kếtjavascript:. Thẻ bọc nhưdiv,sectionđược bỏ nhưng giữ chữ bên trong.
Mã lỗi
Lỗi trả về JSON thống nhất; hiển thị hoặc ghi log trường message:
{ "codeResponse": 422, "codeError": 0, "message": "Danh mục bài viết … không tồn tại. Lấy danh sách bằng GET /categories." }
| Mã | Ý nghĩa |
|---|---|
400 | Dữ liệu thiếu hoặc sai định dạng |
401 | Thiếu key, key sai, hết hạn, đã thu hồi, gọi qua HTTP hoặc từ trình duyệt |
403 | Key thiếu quyền cho thao tác, hoặc sửa bài viết, sản phẩm, danh mục của người khác |
404 | Không có bài viết, sản phẩm, danh mục hoặc bản ngôn ngữ (kể cả của doanh nghiệp khác) |
409 | Đã có bài viết, sản phẩm với id gửi lên; trùng mã sản phẩm hoặc trùng tên sản phẩm trong danh mục; seo.seoUrl đã được dùng |
413 | Ảnh vượt quá 5 MB, hoặc request thêm, sửa vượt 30 triệu byte |
415 | Không phải ảnh JPG/PNG/WEBP/GIF hợp lệ, hoặc POST /files không gửi multipart |
422 | Danh mục hoặc ngôn ngữ không hợp lệ; ảnh quá lớn; quá 5 ảnh phụ mỗi lần gửi hoặc quá 20 ảnh phụ mỗi sản phẩm; galleryRemove có ảnh sản phẩm không có; gửi seo cho nội dung thuộc danh mục chưa gắn trang chi tiết, hoặc cho danh mục đang tắt "SEO danh mục" |
429 | Vượt giới hạn tần suất; chờ theo Retry-After |
502 | Không lưu được file vào kho lưu trữ; thử lại sau |
Lịch sử thay đổi
v1.7 (07/11/2026): thêm quyền media:read, media:write; danh mục đa phương tiện cần media:read để có trong GET /categories, xem được bằng GET /categories/{id} và sửa nội dung bằng PATCH /categories/{id} với media:write. Key cũ không tự có hai quyền này; hãy tạo key mới.
v1.6 (07/11/2026): GET /categories không gửi type trả tất cả danh mục thuộc các loại key được đọc (trước đây chỉ trả danh mục bài viết); mỗi danh mục có thêm trường type; danh sách có cả danh mục đa phương tiện (type=media). Mục Danh mục chuyển lên trước Bài viết.
v1.5 (07/11/2026): thêm GET /categories/{id} và PATCH /categories/{id} để xem và sửa nội dung danh mục bài viết, sản phẩm (tên, mô tả, nội dung, ảnh, SEO).
v1.4 (06/11/2026): thêm đối tượng seo (seoUrl, title, metaDescription, metaKeyword) khi thêm, sửa và xem chi tiết bài viết, sản phẩm. Đổi đường dẫn SEO tự tạo chuyển hướng 301 từ đường dẫn cũ.
v1.3 (02/11/2026): ảnh đại diện bài viết, ảnh đại diện và ảnh phụ sản phẩm gửi kèm dạng base64 khi thêm, sửa (image, gallery, galleryAdd, galleryRemove) và lưu thẳng vào thư mục ảnh như CMS. Bỏ trường coverFile của bài viết (trường này không còn tác dụng nếu vẫn gửi). POST /files chỉ dành cho ảnh chèn trong nội dung. Giới hạn upload tính theo số ảnh, gồm cả ảnh gửi kèm bài viết, sản phẩm.
v1.2 (02/11/2026): thêm sản phẩm (danh sách, chi tiết, thêm, sửa) với quyền products:read/products:write, danh mục sản phẩm qua GET /categories?type=product. Website tự làm mới để đường dẫn bài viết, sản phẩm mới mở được ngay.
v1.1 (30/10/2026): thêm trường type (loại bài viết) khi đọc, thêm và sửa bài viết.
v1 (28/10/2026): phát hành API key theo doanh nghiệp, bài viết (danh mục, danh sách, chi tiết, thêm, sửa) và file ảnh (upload, danh sách). Mô tả máy đọc được: OpenAPI public-v1.