Chọn cách tích hợp

Cả bốn cách dùng chung một bản Docker; khác nhau ở chỗ tệp nằm đâu và ai nói chuyện với máy chủ soạn thảo. Bạn có thể kết hợp nhiều cách trên cùng một máy chủ.

Nextcloud#

Nextcloud nói chuyện với máy chủ soạn thảo qua ứng dụng richdocuments bằng giao thức WOPI. Người dùng mở tệp ngay trong Files, cùng sửa với đồng nghiệp; tệp luôn nằm trong Nextcloud.

• Cài richdocuments, chạy richdocuments:activate-config với -w là địa chỉ nội bộ của máy chủ soạn thảo và -c là địa chỉ máy chủ soạn thảo gọi ngược về Nextcloud. Thiếu -c thì wopi_callback_url bị đặt lại về rỗng.
• Khai gốc URL WOPI của Nextcloud trong O3O_ONLINE_ALIASGROUP2 (nhóm 1 luôn dành cho o3o-gate).
• Nextcloud phải tin cậy tên máy nội bộ o3o-nextcloud (O3O_NC_TRUSTED_DOMAINS).
• Muốn o3o-gate cho phiên chỉ đọc đi qua khi đã chạm trần, khai O3O_WOPI_ALLOWED_HOSTS.
• public_wopi_url do richdocuments tự suy từ discovery; không đặt tay. Sai thì sửa O3O_ONLINE_SERVER_NAME rồi chạy lại activate-config với đủ -w và -c.

WOPI host tự viết#

Hệ lưu trữ của bạn đóng vai WOPI host: máy chủ soạn thảo gọi ngược về để đọc thông tin tệp, tải nội dung và ghi bản đã sửa. Bạn giữ toàn quyền phân quyền và lưu phiên bản.

1. Đọc /hosting/discovery để lấy urlsrc của trang soạn thảo theo đuôi tệp.
2. Sinh access_token cho người dùng, dựng iframe và gửi form tới urlsrc kèm WOPISrc trỏ về API tệp của bạn.
3. Trả lời GET /wopi/files/{id} (CheckFileInfo), GET /wopi/files/{id}/contents (GetFile) và POST /wopi/files/{id}/contents (PutFile).
4. Khai gốc URL WOPI host của bạn trong O3O_ONLINE_ALIASGROUP2 để máy chủ soạn thảo chấp nhận.

{
  "BaseFileName": "hop-dong.docx",
  "Size": 48213,
  "Version": "7",
  "OwnerId": "u-1001",
  "UserId": "u-1001",
  "UserFriendlyName": "Nguyễn Văn A",
  "UserCanWrite": true,
  "SupportsUpdate": true,
  "SupportsLocks": false,
  "LastModifiedTime": "2026-09-21T10:00:00.0000000Z"
}

Lớp nhúng O3O.Editor#

Không cần Nextcloud hay WOPI: o3o-gate tự làm WOPI host. Trang của bạn chỉ đưa ra URL tải tệp gốc và (nếu muốn nhận bản đã sửa) một URL nhận callback. Cấu hình được máy chủ của bạn ký bằng JWT HS256.

<script src="http://localhost:8080/o3o/api.js"></script>
<div id="editor" style="height:720px"></div>
<script>
  // JWT do MÁY CHỦ của bạn ký bằng O3O_EMBED_JWT_SECRET; payload chứa document, editor, ui và exp
  const editor = new O3O.Editor("editor", {
    document: { url: "https://files.example.com/contract.docx", title: "Hợp đồng.docx", fileType: "docx", key: "contract-42-v7" },
    editor: { mode: "edit", lang: "vi", user: { id: "u-1001", name: "Nguyễn Văn A" },
              callbackUrl: "https://app.example.com/o3o/callback" },
    token: signedConfigJwt,
    events: { onSaved: (e) => console.log("đã lưu phiên bản", e.version) }
  });
</script>

• Sự kiện: onReady, onDocumentLoaded, onModified, onSaved, onError, onClose, onLimitReached.
• Phương thức: save(), close(), destroy(), setReadOnly(), getInfo().
• Callback lưu ký X-O3O-Signature bằng HMAC SHA-256; o3o-gate thử lại tối đa 3 lần.
• Chạm trần: trình soạn thảo vẫn mở nhưng ở chế độ chỉ đọc, kèm sự kiện onLimitReached.

Chỉ dùng DocBuilder#

Khi không cần người sửa trực tiếp, hệ thống của bạn gọi API REST /v1/* để chuyển đổi, dựng tài liệu từ kịch bản o3oscript hoặc điền mẫu. Việc của DocBuilder không tính vào số kết nối, nhưng chịu hạn mức tần suất và cỡ tệp của gói.

Ví dụ dưới dựng một biên bản PDF: lưu kịch bản ở tab JSON thành tệp bien-ban.json rồi gửi bằng lệnh ở tab cURL.

curl -s -X POST http://localhost:8080/v1/build \
  -H "Authorization: Bearer $O3O_DEMO_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @bien-ban.json \
  -o bien-ban.pdf

{
  "o3oscript": 1,
  "type": "text",
  "body": [
    {
      "type": "heading",
      "level": 1,
      "text": "Biên bản họp"
    },
    {
      "type": "paragraph",
      "text": "Nội dung được dựng bằng O3O DocBuilder."
    }
  ],
  "save": [
    {
      "format": "pdf",
      "filename": "bien-ban.pdf"
    }
  ]
}

Chọn nhanh#

1. Đã có Nextcloud?

   Dùng Nextcloud: không phải viết mã, người dùng mở tệp ngay trong Files.

2. Có kho tệp riêng và tệp không được rời kho?

   Tự viết WOPI host: máy chủ soạn thảo đọc và ghi thẳng vào kho của bạn.

3. Ứng dụng web chỉ cần mở một tệp theo URL?

   Dùng O3O.Editor: o3o-gate giữ bản làm việc và gửi bản đã sửa về qua callback.

4. Không cần người sửa trực tiếp?

   Chỉ dùng DocBuilder: chuyển đổi và sinh tài liệu qua REST, không tính kết nối.