Ứng dụng, API & Webhook

Một trang gom mọi cách mở Deplao ra bên ngoài: cài thêm Ứng dụng chạy ngay trong Deplao; cho website, phần mềm bán hàng, n8n… đọc dữ liệu và gửi tin qua API; nhận và gửi dữ liệu bằng webhook.

• Ở đâu: thanh điều hướng bên trái → Công cụ → Ứng dụng, API & Webhook (hoặc tìm trong bảng Tất cả tính năng). Chỉ có trên máy chủ; máy nhân viên không chạy API.
• Ba thẻ: Ứng dụng (cài, mở, quản lý ứng dụng) · API (server, API key, nhật ký, nâng cao) · Webhook (nhận dữ liệu vào, gửi sự kiện ra ngoài).
• Nút Tài liệu API và Tài liệu phát triển ứng dụng ở đầu trang mở tài liệu trong trình duyệt (API server tự bật nếu đang tắt).

#Public API v1

API là "cửa" để phần mềm khác làm việc với Deplao như một người dùng: đọc hội thoại, gửi tin, cập nhật khách hàng, chạy workflow… Mỗi hệ thống dùng một API key riêng: giống mật khẩu, kèm danh sách quyền (scope) cho biết key được làm gì.

• Gần 300 thao tác: tài khoản, chat Zalo / Facebook / Telegram, nhóm, nhãn, danh bạ, CRM, workflow, tích hợp, ERP, AI, báo cáo, media, nhân viên.
• Chạy ngay trên máy cài Deplao, cổng mặc định 9900 (chung server với kết nối nhân viên). Mặc định tắt cho tới khi bạn bật; mọi lời gọi đều cần API key do bạn tạo.
• Đi đúng luồng của app: tin gửi bằng API vẫn hiện trong khung chat, được lưu và kích hoạt workflow như khi bạn tự gửi.
• Gửi key trong header Authorization: Bearer dpk_… (hoặc X-Api-Key).

#Bật API và tạo API key

1. Bật server: thẻ API → tab Tổng quan → mục API server → Bật server. Máy chạy bot / worker 24/7 thì bật thêm "Tự bật server khi mở app".
2. Tạo API key: tab API key → Tạo API key: đặt tên (vd Website, n8n), chọn Quyền (mẫu nhanh Chỉ đọc · Chat bot · Đồng bộ CRM · Toàn quyền, hoặc tick từng quyền), Tài khoản được dùng, IP được phép (IP hoặc dải CIDR, để trống = mọi IP), Hết hạn (30 ngày, 90 ngày, 1 năm hoặc không hết hạn). Tuỳ chọn: giới hạn request/phút (0 = không giới hạn), vai trò ERP, ghi chú.
3. Sao chép key ngay: key dạng dpk_… chỉ hiện một lần, sao chép và cất ở nơi an toàn. Lỡ mất key thì thu hồi và tạo key mới.
4. Gọi thử: chạy lệnh bên dưới (thay dpk_xxx bằng key của bạn); nhận về danh sách tài khoản là key đã dùng được.
5. Xem tài liệu: bấm Mở tài liệu API, trang http://127.0.0.1:9900/docs có hướng dẫn, danh sách endpoint, nút thử gọi và lệnh curl. File /api/v1/openapi.json nhập thẳng vào Postman / Insomnia hoặc dùng để sinh SDK.

curl -H "Authorization: Bearer dpk_xxx" http://127.0.0.1:9900/api/v1/accounts

#Gọi API từ đâu?

• Trên máy này: http://127.0.0.1:9900/api/v1
• Trong mạng LAN: http://<IP máy chủ>:9900/api/v1, tab Tổng quan hiện sẵn địa chỉ để sao chép.
• Từ Internet (server, n8n, Make… ở ngoài): bật dịch vụ Nhân viên và API ở Cài đặt → Internet & Đám mây → Địa chỉ Internet, rồi gọi <địa chỉ>/api/v1. Mục "Truy cập từ xa" ở tab Tổng quan chỉ hiện địa chỉ này để sao chép; đây cũng là địa chỉ nhân viên làm việc từ xa dùng. Xem Internet & Đám mây.
• Địa chỉ tạm đổi mỗi lần khởi động lại; hệ thống chạy lâu dài nên dùng địa chỉ cố định (Cloudflare tự động).

#Nhật ký, giám sát & sự kiện realtime

• Nhật ký: 200 request gần nhất, lọc theo key, ai gọi (key, nhân viên hay ứng dụng), endpoint, kết quả, thời gian xử lý, IP. Không lưu nội dung request; mặc định giữ 7 ngày.
• Thống kê 24h cho từng key ở tab API key; tab Tổng quan có mục Giám sát 5 phút gần nhất (request/phút, lỗi, kết nối realtime, IP bị tạm chặn).
• Sự kiện realtime (tin nhắn mới, kết bạn, thanh toán…) cho key có quyền nhận sự kiện: Socket.IO cho app / worker giữ kết nối lâu, SSE cho script và server, polling cho cron, serverless, Google Apps Script. Chi tiết: Sự kiện.
• Hệ thống mất kết nối vẫn lấy bù được sự kiện: mặc định giữ 7 ngày, tối đa 50.000 sự kiện.
• Tab Nâng cao: giới hạn do bạn tự đặt (mặc định không giới hạn request), dung lượng body / file tối đa, số thao tác chạy song song, thời gian giữ nhật ký và sự kiện, các tuỳ chọn bảo mật.

#Webhook: nhận dữ liệu vào, gửi sự kiện ra

#Nhận dữ liệu vào: hệ thống khác → Deplao

Casso, SePay gửi giao dịch chuyển khoản, KiotViet / Haravan / Sapo / Nhanh.vn / Pancake POS gửi đơn hàng (xác thực bằng khoá webhook đặt ở trang tích hợp) vào <địa chỉ>/webhook/<loại>; website, Zapier, Make… kích hoạt workflow có trigger "Webhook bên ngoài" qua <địa chỉ>/api/workflow/webhook/<token>. Cần bật địa chỉ "Thanh toán, tích hợp" / "Webhook workflow" ở Cài đặt → Internet & Đám mây; chỉ dùng trong LAN thì không cần. Xem thêm Tích hợp POS và Tích hợp thanh toán.

#Gửi sự kiện ra ngoài: Deplao → URL của bạn

Bấm Thêm webhook: tên, URL nhận (https://, hoặc http:// trong mạng nội bộ), chọn sự kiện (hoặc Mọi sự kiện) và tài khoản → Tạo webhook. Secret chỉ hiện một lần: dùng để kiểm tra chữ ký.

• Mỗi lần gửi kèm chữ ký X-Deplao-Signature (HMAC SHA-256 tạo bằng secret) để server của bạn chắc chắn dữ liệu do Deplao gửi; cách kiểm tra xem ở nút Tài liệu webhook hoặc trang Webhook trong tài liệu nhà phát triển.
• Gửi lỗi thì tự thử lại sau 30 giây, 2 phút, 10 phút, 1 giờ, 6 giờ; lỗi 100 lần liên tiếp thì webhook tự tắt: sửa server nhận rồi bật lại.
• Gửi thử, Lịch sử gửi (thành công / thất bại / đang chờ thử lại) và Gửi lại từng lần.
• Webhook gửi ra vẫn chạy khi API server tắt; chỉ dừng khi tắt công tắc "Cho phép gọi API". Webhook do API key hoặc ứng dụng tự đăng ký cũng hiện ở đây để bạn quản lý.

#Ứng dụng: thêm tính năng ngay trong Deplao

Ứng dụng là phần mở rộng do nhà cung cấp hoặc chính bạn làm, cài vào là dùng ngay trong Deplao. (Trong tài liệu kỹ thuật, ứng dụng được gọi là plugin.)

Ứng dụng cũng có thể mở API riêng cho hệ thống ngoài gọi, dạng /api/v1/plugins/<mã ứng dụng>/… (xem trong chi tiết ứng dụng → mục API cho hệ thống ngoài).

Ba loại ứng dụng:

• Chỉ giao diện: chỉ có giao diện chạy trong Deplao, không chạy code nền.
• Chạy trên máy: có phần chạy nền trên máy này, trong tiến trình riêng tách khỏi Deplao.
• Dịch vụ ngoài: phần xử lý chạy trên server của nhà cung cấp; Deplao gọi tới qua HTTPS có chữ ký.

#Cài và quản lý ứng dụng

1. Cài ứng dụng: thẻ Ứng dụng → Cài ứng dụng → chọn file .zip nhà cung cấp gửi. Ứng dụng đang phát triển ở dạng thư mục thì dùng nút Phát triển ứng dụng → Thêm thư mục đang phát triển.
2. Duyệt quyền: màn cài hiện loại ứng dụng, các quyền ứng dụng xin (quyền rủi ro tô đỏ), cảnh báo nếu ứng dụng chạy code trên máy và README. Chọn Tài khoản ứng dụng được dùng (tất cả hoặc vài tài khoản) rồi bấm Cài và bật.
3. Dùng và quản lý: bấm Mở để vào trang của ứng dụng. Bấm vào ô ứng dụng để xem chi tiết: Giới thiệu (có ở đâu trong Deplao, được phép gì, tài khoản nào), Cài đặt, Nhật ký, công tắc bật / tắt, Tải lại, Gỡ ứng dụng.
4. Cập nhật: cài file .zip có phiên bản mới hơn; quyền mới (nhãn "mới") phải duyệt lại.

• Ứng dụng chỉ làm được trong phạm vi quyền đã duyệt và trên các tài khoản được cấp: mọi lời gọi đi qua API v1 với cùng bước kiểm tra quyền, và hiện trong Nhật ký API.
• Ứng dụng loại Dịch vụ ngoài: khi cài, Deplao hiện một lần API key và secret ký request để cấu hình ở server của ứng dụng.
• Ứng dụng lỗi nhiều lần liên tiếp sẽ bị Deplao tự tắt (trạng thái "Tắt do lỗi"): xem tab Nhật ký, sửa xong bật lại.
• Nút bánh răng Giới hạn chung cho ứng dụng: số ứng dụng bật cùng lúc (mặc định 10, ứng dụng chạy nền tốn RAM) và request/phút cho mỗi ứng dụng.
• Gỡ ứng dụng: Deplao hỏi giữ hay xoá dữ liệu riêng của ứng dụng (giữ để cài lại sau). Gỡ ứng dụng dạng thư mục không xoá thư mục code của bạn.

#Tự làm ứng dụng (cho lập trình viên)

Ứng dụng là một web app (HTML/CSS/JS thuần, React, Vue, Svelte…) gọi Deplao qua deplao.*; cần xử lý nền thì thêm backend Node chạy trên máy hoặc để server riêng của bạn xử lý. Nút Phát triển ứng dụng mở ngăn hướng dẫn, tài liệu và bảng tra nhanh SDK.

1. Tạo khung ứng dụng: lệnh create, chọn runtime web (chỉ giao diện), local (chạy nền trên máy) hoặc remote (server riêng).
2. Chạy thử trong Deplao: Thêm thư mục đang phát triển, chọn thư mục có deplao-plugin.json; sửa code xong bấm Tải lại trong chi tiết ứng dụng.
3. Kiểm tra: lệnh validate báo lỗi manifest và liệt kê các quyền ứng dụng xin.
4. Đóng gói: lệnh pack tạo file .zip để khách cài ở thẻ Ứng dụng.

node packages/plugin-cli/bin/deplao-plugin.js create my-app --runtime web
node packages/plugin-cli/bin/deplao-plugin.js validate my-app
node packages/plugin-cli/bin/deplao-plugin.js pack my-app --out my-app.zip

• Bộ công cụ nằm trong thư mục packages/ của mã nguồn Deplao: SDK @deplao/plugin-sdk và CLI deplao-plugin (chạy bằng Node.js). Ứng dụng mẫu ở examples/plugins.
• Ứng dụng gọi Deplao bằng chính API v1: tên hàm trong SDK trùng tên thao tác (operationId) trong tài liệu API.
• Script, CSS, font từ CDN bị chặn để bảo mật: build ra file tĩnh và đóng gói kèm ứng dụng.

Hướng dẫn chi tiết cho lập trình viên: Ứng dụng (plugin) trong tài liệu nhà phát triển.

#An toàn khi mở Deplao ra bên ngoài

• Giữ API key như mật khẩu: không gửi qua chat, không đặt trong website công khai. Mỗi hệ thống một key, chỉ cấp quyền và tài khoản cần thiết, đặt IP được phép nếu server gọi có IP cố định, đặt hạn dùng.
• Quyền admin (Toàn quyền) gồm cả quản lý nhân viên và cài đặt: chỉ cấp cho hệ thống bạn hoàn toàn tin tưởng.
• Thu hồi key không dùng nữa (tab API key → Thu hồi). Nghi lộ key: tab Tổng quan → Khẩn cấp → Thu hồi tất cả API key rồi tạo lại; công tắc Cho phép gọi API chặn toàn bộ API ngay (trả lỗi 503), không ảnh hưởng nhân viên.
• IP thử key sai liên tục (20 lần/phút) bị tạm chặn 10 phút; key đúng không bị ảnh hưởng.
• Giữ kín secret của webhook, luôn kiểm tra chữ ký và dùng URL https.
• Chỉ cài ứng dụng từ nguồn bạn tin cậy và đọc kỹ quyền trước khi bấm Cài: ứng dụng chạy trên máy chạy code trên máy bạn. Tắt hoặc gỡ ứng dụng không dùng nữa.
• Chỉ bật địa chỉ Internet khi cần gọi từ ngoài. Trang tài liệu mặc định ai cũng xem được (chỉ mô tả endpoint, không có dữ liệu); muốn bắt buộc key khi xem từ xa thì tắt "Tài liệu công khai" ở tab Nâng cao.