Hotline: 0852 87 45 87
TÀI LIỆU API

Public API DybiCMS

Thêm, sửa bài viết, sản phẩm và upload ảnh vào website từ phần mềm của doanh nghiệp: công cụ đăng bài, hệ thống nội bộ hoặc quy trình tự động.

Phiên bản v1JSON qua HTTPSXác thực bằng API keyTải OpenAPI (JSON)

Bắt đầu

Mọi endpoint nằm dưới địa chỉ gốc:

https://api.dybiweb.com/api/public/v1
  1. Đă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.
  2. 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).
  3. 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.
  4. 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:readXem danh mục và bài viết
articles:writeThêm và sửa bài viết, sửa nội dung danh mục bài viết
products:readXem danh mục và sản phẩm
products:writeThêm và sửa sản phẩm, sửa nội dung danh mục sản phẩm
media:readXem danh mục đa phương tiện
media:writeSửa nội dung danh mục đa phương tiện
files:readXem danh sách ảnh trong thư viện
files:writeUpload ả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ụcGiới hạn
Số yêu cầu60 yêu cầu/phút cho mỗi key
Upload ảnh20 ả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 sai30 lần/phút cho mỗi địa chỉ IP, sau đó tạm chặn 1 phút
File ảnhJPG, 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ẩmTiê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ẩmMã 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ửaMỗ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 trangpageSize 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

  1. 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).
  2. Chèn url vào nội dung bài, ví dụ <img src="…" alt="Mô tả ảnh">.
  3. Lấy id danh mục bằng GET /categories.
  4. Tạo bài bằng POST /articles, gửi kèm ảnh đại diện trong trường image (xem ảnh đại diện và ảnh phụ). Bài mới mặc định là nháp.
  5. 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ẫnQuyềnMô tả
GET/mebất kỳThông tin key và doanh nghiệp
GET/categoriesarticles:read, products:read hoặc media:readDanh 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ụcChi tiết danh mục
PATCH/categories/{id}articles:write, products:write hoặc media:write theo loại danh mụcSửa nội dung danh mục
GET/articlesarticles:readDanh sách bài viết
GET/articles/{id}articles:readChi tiết bài viết
POST/articlesarticles:writeThêm bài viết
PATCH/articles/{id}articles:writeSửa bài viết
GET/productsproducts:readDanh sách sản phẩm
GET/products/{id}products:readChi tiết sản phẩm
POST/productsproducts:writeThêm sản phẩm
PATCH/products/{id}products:writeSửa sản phẩm
POST/filesfiles:writeUpload ảnh chèn trong nội dung
GET/filesfiles:readDanh 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ườngGhi chú
languageBả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
titleTên danh mục, văn bản thuần, tối đa 300 ký tự
briefMô tả ngắn, văn bản thuần
contentNội dung HTML, làm sạch theo quy tắc nội dung
imageThay ả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ườngBắt buộcGhi chú
categoryIdCóDanh mục bài viết lấy từ GET /categories
titleCóVăn bản thuần, tối đa 300 ký tự; dùng để tạo đường dẫn SEO
briefCóVăn bản thuần, thẻ HTML sẽ bị bỏ
typeKhôngLoại bài viết, mặc định Article; xem bảng loại bài viết
contentKhôngHTML, được làm sạch theo quy tắc nội dung
languageKhôngMặc định vi; phải là ngôn ngữ đã bật cho website
tagsKhôngDanh sách thẻ; thẻ trùng sẽ được gộp
displayDateKhôngNgày hiển thị, mặc định là thời điểm tạo
isPublishedKhôngMặc định false (nháp)
orderKhôngThứ tự sắp xếp, mặc định 50
imageKhôngẢnh đại diện; xem ảnh đại diện và ảnh phụ
seoKhôngĐường dẫn SEO, Meta Title, Meta Description, Meta Keyword; trường không gửi được tạo tự động; xem SEO
idKhôngGUID 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
ArticleBà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.
NewsArticleBà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ự.
BlogPostingBà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ườngBắt buộcGhi chú
categoryIdCóDanh mục sản phẩm lấy từ GET /categories?type=product
titleCó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
unitCóĐơn vị tính cơ bản, ví dụ Cái, Hộp, Kg; tối đa 30 ký tự
priceKhôngGiá bán trước thuế, mặc định 0
vatKhôngThuế suất GTGT, mặc định -2; xem bảng VAT
discountTypeKhôngnone (mặc định), percent (giảm theo %) hoặc amount (giảm số tiền)
discountKhi có giảm giáPhần trăm từ 0 đến 100, hoặc số tiền không lớn hơn price
codeKhôngMã 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
typeKhôngLoại sản phẩm, mặc định HangHoa; xem bảng loại sản phẩm
briefKhôngMô tả ngắn, văn bản thuần; bỏ trống thì dùng tên sản phẩm
contentKhôngMô tả chi tiết bằng HTML, làm sạch theo quy tắc nội dung
imageKhôngẢnh đại diện; xem ảnh đại diện và ảnh phụ
galleryKhôngDanh sách ảnh phụ, tối đa 5 ảnh phụ mỗi lần gửi
language, tags, isPublished, order, id, seoKhôngNhư 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
-2Không kê khai
-1Không chịu thuế
0, 5, 8, 10Thuế 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
HangHoaHàng hóa
DichVuDịch vụ
ThanhPhamThành phẩm
BanThanhPhamBán thành phẩm
CongCuDungCuCông cụ dụng cụ
NguyenVatLieuNguyên vật liệu
TaiSanCoDinhTà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ườngGhi chú
imageThay ảnh đại diện
galleryAddThêm ảnh phụ, tối đa 5 ảnh mỗi lần gửi
galleryRemoveDanh 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ườngGhi chú
fileNameTê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
dataNộ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ườngGhi 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
titleMeta Title, tối đa 65 ký tự
metaDescriptionMeta Description, tối đa 155 ký tự
metaKeywordMeta 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 seoUrl củ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 seo khi đó 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ành h2 vì tiêu đề bài là H1 duy nhất của trang.
  • Ảnh phải dùng địa chỉ https://; nên dùng url nhận từ POST /files và 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ết javascript:. 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
400Dữ liệu thiếu hoặc sai định dạng
401Thiếu key, key sai, hết hạn, đã thu hồi, gọi qua HTTP hoặc từ trình duyệt
403Key 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
404Khô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
415Không phải ảnh JPG/PNG/WEBP/GIF hợp lệ, hoặc POST /files không gửi multipart
422Danh 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"
429Vượt giới hạn tần suất; chờ theo Retry-After
502Khô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.

Trao đổi nhu cầu của bạn với Dybi

Website theo yêu cầu, phần mềm POS hoặc một quy trình kết hợp cả hai.

Đăng ký tư vấn