{ "openapi": "3.1.0", "info": { "title": "Deplao Public API", "version": "26.10.3", "description": "API mở của Deplao cho app, plugin, worker và nền tảng ngoài (n8n, Make, Zapier, server riêng).\nMọi thao tác đi qua **cùng logic với giao diện app** (cùng handler IPC), nên kết quả gửi tin, gán nhãn, chạy workflow giống hệt khi bấm trên app.\n\n- Base URL trên máy: `http://127.0.0.1:9900/api/v1`\n- Từ xa: `https://<địa-chỉ-của-bạn>/api/v1` (cấu hình ở Cài đặt → Internet & Đám mây, dịch vụ \"Nhân viên và API\")\n- Xác thực: `Authorization: Bearer dpk_...` hoặc `X-Api-Key: dpk_...`\n- Tài liệu máy đọc được: `/api/v1/openapi.json` (import vào Postman, Insomnia, sinh SDK)" }, "servers": [ { "url": "http://127.0.0.1:9900/api" } ], "security": [ { "BearerApiKey": [] }, { "HeaderApiKey": [] } ], "tags": [ { "name": "Hệ thống", "description": "Kiểm tra sống, thông tin key, thông tin máy chủ." }, { "name": "Tài khoản", "description": "Tài khoản Zalo, Facebook, Telegram trên máy: danh sách, trạng thái, kết nối, proxy." }, { "name": "Chat", "description": "Hội thoại và tin nhắn mọi kênh: đọc, tìm, gửi, thu hồi, reaction, ghim, đã đọc." }, { "name": "Media", "description": "Upload file để gửi, tải file đính kèm, thư viện media." }, { "name": "Nhãn & tin nhanh", "description": "Nhãn hội thoại (local), tin nhắn nhanh, sticker." }, { "name": "Nhóm", "description": "Nhóm chat: thông tin, thành viên, đổi tên, link mời." }, { "name": "Danh bạ", "description": "Bạn bè, lời mời kết bạn, tra cứu người dùng." }, { "name": "Danh mục sản phẩm" }, { "name": "CRM", "description": "Khách hàng, tag CRM, ghi chú, chiến dịch gửi tin." }, { "name": "Chiến dịch" }, { "name": "Workflow", "description": "Workflow tự động hoá: đọc, sửa, bật/tắt, chạy, sự kiện trigger.api." }, { "name": "Tích hợp", "description": "Kết nối POS, vận chuyển, thanh toán: gọi action của adapter." }, { "name": "ERP", "description": "Công việc, dự án, lịch, ghi chú, chấm công, nghỉ phép, thông báo." }, { "name": "AI", "description": "Trợ lý AI: chat, gợi ý trả lời, thống kê sử dụng." }, { "name": "Báo cáo", "description": "Báo cáo tổng quan, lượng tin, giờ cao điểm, chiến dịch, workflow." }, { "name": "Nhân viên", "description": "Quản lý nhân viên, quyền module, phân tài khoản." }, { "name": "Sự kiện", "description": "Nhận sự kiện realtime: Socket.IO, SSE, polling." }, { "name": "Webhook", "description": "Đăng ký webhook outbound có chữ ký HMAC." }, { "name": "Plugin", "description": "Route do plugin đăng ký và thông tin plugin." } ], "paths": { "/v1/health": { "get": { "operationId": "health", "summary": "Kiểm tra API còn sống", "description": "Không cần key. Dùng cho uptime monitor.\n\n**Không cần API key.**", "tags": [ "Hệ thống" ], "parameters": [], "x-scope": null, "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "status": { "type": "string" }, "version": { "type": "string" }, "uptime_ms": { "type": "integer" }, "time": { "type": "integer" } }, "required": [ "status", "version", "uptime_ms", "time" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [] } }, "/v1/me": { "get": { "operationId": "getMe", "summary": "Thông tin key đang dùng (scope, tài khoản được phép)", "description": "**Cần API key** (scope bất kỳ).", "tags": [ "Hệ thống" ], "parameters": [], "x-scope": "any", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "account_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "rate_limit_per_min": { "type": "integer" }, "erp_role": { "type": "string" }, "allowed_ips": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "kind", "id", "name", "scopes", "account_ids", "rate_limit_per_min", "erp_role", "allowed_ips" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } }, "example": { "success": true, "data": { "kind": "apikey", "id": "6f1c…", "name": "Bot CSKH", "scopes": [ "chat:read", "chat:send" ], "account_ids": [ "0501234567" ], "rate_limit_per_min": 0, "erp_role": "manager", "allowed_ips": null }, "request_id": "3f0c0b6e-6d0a-4b8e-9d1a-1d2f3a4b5c6d" } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/system/info": { "get": { "operationId": "getSystemInfo", "summary": "Phiên bản, chế độ, workspace, trạng thái server/tunnel", "description": "**Scope:** `settings:read`", "tags": [ "Hệ thống" ], "parameters": [], "x-scope": "settings:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/scopes": { "get": { "operationId": "listScopes", "summary": "Danh mục scope và preset", "description": "**Không cần API key.**", "tags": [ "Hệ thống" ], "parameters": [], "x-scope": null, "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [] } }, "/v1/accounts": { "get": { "operationId": "listAccounts", "summary": "Danh sách tài khoản (Zalo, Facebook, Telegram) mà key được phép", "description": "**Scope:** `accounts:read`", "tags": [ "Tài khoản" ], "parameters": [ { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "zalo", "facebook", "telegram_user", "telegram_bot" ] }, "description": "Lọc theo kênh" }, { "name": "online", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Chỉ tài khoản đang online" } ], "x-scope": "accounts:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "channel": { "type": "string" }, "display_name": { "type": "string" }, "avatar_url": { "type": "string" }, "phone": { "type": "string" }, "online": { "type": "boolean" }, "is_business": { "type": "boolean" }, "listener_active": { "type": "boolean" }, "created_at": { "anyOf": [ {}, { "type": "null" } ] }, "last_seen": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "id", "channel", "display_name", "avatar_url", "phone", "online", "is_business", "listener_active", "created_at", "last_seen" ], "additionalProperties": false } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}": { "get": { "operationId": "getAccount", "summary": "Thông tin một tài khoản", "description": "**Scope:** `accounts:read`", "tags": [ "Tài khoản" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "accounts:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "channel": { "type": "string" }, "display_name": { "type": "string" }, "avatar_url": { "type": "string" }, "phone": { "type": "string" }, "online": { "type": "boolean" }, "is_business": { "type": "boolean" }, "listener_active": { "type": "boolean" }, "created_at": { "anyOf": [ {}, { "type": "null" } ] }, "last_seen": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "id", "channel", "display_name", "avatar_url", "phone", "online", "is_business", "listener_active", "created_at", "last_seen" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/status": { "get": { "operationId": "getAccountStatus", "summary": "Trạng thái kết nối/listener chi tiết và proxy đang dùng", "description": "**Scope:** `accounts:read`", "tags": [ "Tài khoản" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "accounts:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/connect": { "post": { "operationId": "connectAccount", "summary": "Kết nối lại tài khoản bằng phiên đã lưu", "description": "Dùng phiên đăng nhập đã lưu trên máy (không nhận cookie từ client). Zalo: login:connect; Facebook: fb:connect; Telegram: telegramUser:startListener.\n\n**Scope:** `accounts:manage`", "tags": [ "Tài khoản" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "accounts:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/disconnect": { "post": { "operationId": "disconnectAccount", "summary": "Ngắt kết nối tài khoản (giữ dữ liệu)", "description": "**Scope:** `accounts:manage`", "tags": [ "Tài khoản" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "accounts:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/proxy": { "get": { "operationId": "getAccountProxy", "summary": "Proxy đang gán cho tài khoản (không trả mật khẩu)", "description": "**Scope:** `accounts:manage`", "tags": [ "Tài khoản" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "accounts:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "put": { "operationId": "setAccountProxy", "summary": "Gán proxy (id trong danh sách proxy) hoặc bỏ proxy (null)", "description": "**Scope:** `accounts:manage`", "tags": [ "Tài khoản" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "accounts:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "proxy_id": { "type": [ "integer", "null" ], "description": "ID proxy từ GET /proxies; null = bỏ proxy" } }, "required": [ "proxy_id" ], "additionalProperties": false } } } } } }, "/v1/proxies": { "get": { "operationId": "listProxies", "summary": "Danh sách proxy đã cấu hình (không trả mật khẩu)", "description": "**Scope:** `accounts:manage`", "tags": [ "Tài khoản" ], "parameters": [], "x-scope": "accounts:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/conversations": { "get": { "operationId": "listConversations", "summary": "Danh sách hội thoại, mới nhất trước", "description": "**Scope:** `chat:read`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Số bản ghi tối đa (1–200)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Bỏ qua N bản ghi đầu" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Tìm theo tên/số điện thoại" }, { "name": "unread_only", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "folder", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "main", "others" ], "default": "all" }, "description": "Zalo: hộp thư chính / khác" } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "thread_id": { "type": "string" }, "account_id": { "type": "string" }, "channel": { "type": "string" }, "type": { "type": "string" }, "display_name": { "type": "string" }, "alias": { "type": "string" }, "avatar_url": { "type": "string" }, "phone": { "type": "string" }, "is_friend": { "type": "boolean" }, "unread_count": { "type": "integer" }, "last_message": { "type": "string" }, "last_message_time": { "type": "integer" }, "is_muted": { "type": "boolean" }, "mute_until": { "type": "integer" }, "is_in_others": { "type": "boolean" }, "has_mention": { "type": "boolean" } }, "required": [ "thread_id", "account_id", "channel", "type", "display_name", "alias", "avatar_url", "phone", "is_friend", "unread_count", "last_message", "last_message_time", "is_muted", "mute_until", "is_in_others", "has_mention" ], "additionalProperties": false } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}": { "get": { "operationId": "getConversation", "summary": "Một hội thoại kèm nhãn và trạng thái ghim", "description": "**Scope:** `chat:read`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "updateConversation", "summary": "Ghim, tắt thông báo, đặt biệt danh (trên Deplao)", "description": "Các cờ lưu trên Deplao như UI: ghim cục bộ (db:setLocalPinnedConversation), tắt thông báo (db:setContactFlags), biệt danh (db:setContactAlias).\n\n**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pinned": { "type": "boolean" }, "muted": { "type": "boolean" }, "mute_until": { "type": "integer", "minimum": 0, "description": "Epoch ms; 0 = vô thời hạn" }, "alias": { "type": "string", "maxLength": 100 } }, "additionalProperties": false } } } } }, "delete": { "operationId": "deleteConversation", "summary": "Xoá hội thoại (toàn bộ tin trong Deplao; Zalo xoá cả trên server)", "description": "Không thể hoàn tác — bắt buộc `?confirm=true`. Như menu \"Xóa hội thoại\": Zalo gọi `zalo:deleteChat` theo tin cuối rồi xoá khỏi DB.\n\n**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" }, { "name": "confirm", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Phải là true" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/unread-count": { "get": { "operationId": "getUnreadCount", "summary": "Tổng số tin chưa đọc của tài khoản", "description": "**Scope:** `chat:read`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/messages": { "get": { "operationId": "listMessages", "summary": "Tin nhắn của hội thoại, mới → cũ, phân trang bằng `before`", "description": "Trang sau: gọi lại với `before = pagination.next_before`. Tin cùng mốc thời gian có thể lặp ở ranh giới trang — khử trùng theo `msg_id`.\n\n**Scope:** `chat:read`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Chỉ lấy tin có timestamp <= before (epoch ms)" }, { "name": "topic_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Telegram forum topic" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 50 }, "description": "Lọc theo msg_type (vd: photo, file)" } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "msg_id": { "type": "string" }, "cli_msg_id": { "type": [ "string", "null" ] }, "account_id": { "type": "string" }, "channel": { "type": "string" }, "thread_id": { "type": "string" }, "thread_type": { "type": "string" }, "sender_id": { "type": "string" }, "sender_name": { "type": [ "string", "null" ] }, "is_self": { "type": "boolean" }, "msg_type": { "type": "string" }, "content": { "type": "string", "description": "Nội dung gốc (có thể là JSON của kênh)" }, "text": { "type": "string", "description": "Văn bản thuần rút từ content" }, "timestamp": { "type": "integer" }, "status": { "type": [ "string", "null" ] }, "is_recalled": { "type": "boolean" }, "is_edited": { "type": "boolean" }, "topic_id": { "type": [ "string", "null" ] }, "reply_to_id": { "type": [ "string", "null" ] }, "attachments": { "type": "array", "items": {} }, "quote": { "anyOf": [ {}, { "type": "null" } ] }, "reactions": {}, "has_local_media": { "type": "boolean" }, "handled_by_employee": { "type": [ "string", "null" ] } }, "required": [ "msg_id", "cli_msg_id", "account_id", "channel", "thread_id", "thread_type", "sender_id", "sender_name", "is_self", "msg_type", "content", "text", "timestamp", "status", "is_recalled", "is_edited", "topic_id", "reply_to_id", "attachments", "quote", "reactions", "has_local_media", "handled_by_employee" ], "additionalProperties": false } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "sendMessage", "summary": "Gửi tin: văn bản, file/ảnh/video, sticker, link (mọi kênh)", "description": "Gửi đúng như khi bấm gửi trên app (cùng handler IPC, cùng hàng đợi gửi). Thứ tự: attachments → sticker → link → text.\n\nFile đính kèm KHÔNG nhận đường dẫn trên máy: dùng `upload_id` (POST /media/uploads), `library_uuid` hoặc `url` công khai.\nVideo Zalo đi qua chuỗi getVideoMeta → uploadVideoThumb → uploadVideoFile → sendVideo như UI.\nHỗ trợ header `Idempotency-Key` để gửi lại an toàn khi mất kết nối.\n\n**Scope:** `chat:send`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:send", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } }, "example": { "success": true, "data": { "channel": "zalo", "thread_id": "8899001122", "sent": [ { "type": "file", "msg_id": "7712", "cli_msg_id": null }, { "type": "text", "msg_id": "7713", "cli_msg_id": "1760000000123" } ] }, "request_id": "3f0c0b6e-6d0a-4b8e-9d1a-1d2f3a4b5c6d" } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "thread_type": { "type": "string", "enum": [ "user", "group" ], "description": "Bỏ trống = tự tra theo hội thoại" }, "text": { "type": "string", "maxLength": 10000 }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "upload_id": { "type": "string", "description": "ID từ POST /media/uploads" }, "library_uuid": { "type": "string", "description": "UUID item trong thư viện media" }, "url": { "type": "string", "format": "uri", "description": "Link http/https công khai, server tự tải về (≤ giới hạn upload)" }, "kind": { "type": "string", "enum": [ "image", "video", "audio", "file" ], "description": "Bỏ trống = tự nhận theo đuôi file" }, "caption": { "type": "string", "maxLength": 2000 } }, "additionalProperties": false }, "maxItems": 10 }, "sticker_id": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "link": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "text": { "type": "string", "maxLength": 2000 } }, "required": [ "url" ], "additionalProperties": false }, "quote_msg_id": { "type": "string", "description": "Trả lời tin nhắn này" }, "mentions": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "offset": { "type": "integer", "minimum": 0 }, "length": { "type": "integer", "minimum": 1 } }, "required": [ "user_id", "offset", "length" ], "additionalProperties": false }, "maxItems": 50 } }, "additionalProperties": false }, "example": { "text": "Đơn #2291 đã giao, cảm ơn anh!", "attachments": [ { "upload_id": "upl_8f1c..." } ] } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/messages/{msgId}": { "get": { "operationId": "getMessage", "summary": "Một tin nhắn", "description": "**Scope:** `chat:read`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại" }, { "name": "msgId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tin nhắn (msg_id)" } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "msg_id": { "type": "string" }, "cli_msg_id": { "type": [ "string", "null" ] }, "account_id": { "type": "string" }, "channel": { "type": "string" }, "thread_id": { "type": "string" }, "thread_type": { "type": "string" }, "sender_id": { "type": "string" }, "sender_name": { "type": [ "string", "null" ] }, "is_self": { "type": "boolean" }, "msg_type": { "type": "string" }, "content": { "type": "string", "description": "Nội dung gốc (có thể là JSON của kênh)" }, "text": { "type": "string", "description": "Văn bản thuần rút từ content" }, "timestamp": { "type": "integer" }, "status": { "type": [ "string", "null" ] }, "is_recalled": { "type": "boolean" }, "is_edited": { "type": "boolean" }, "topic_id": { "type": [ "string", "null" ] }, "reply_to_id": { "type": [ "string", "null" ] }, "attachments": { "type": "array", "items": {} }, "quote": { "anyOf": [ {}, { "type": "null" } ] }, "reactions": {}, "has_local_media": { "type": "boolean" }, "handled_by_employee": { "type": [ "string", "null" ] } }, "required": [ "msg_id", "cli_msg_id", "account_id", "channel", "thread_id", "thread_type", "sender_id", "sender_name", "is_self", "msg_type", "content", "text", "timestamp", "status", "is_recalled", "is_edited", "topic_id", "reply_to_id", "attachments", "quote", "reactions", "has_local_media", "handled_by_employee" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "editMessage", "summary": "Sửa nội dung tin đã gửi (Facebook, Telegram)", "description": "**Scope:** `chat:send`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại" }, { "name": "msgId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tin nhắn (msg_id)" } ], "x-scope": "chat:send", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "text" ], "additionalProperties": false } } } } }, "delete": { "operationId": "deleteMessageForMe", "summary": "Xoá tin phía mình", "description": "Zalo: zalo:deleteMessage (onlyMe) rồi đánh dấu trong DB như UI. Kênh khác: chỉ xoá khỏi DB của Deplao.\n\n**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại" }, { "name": "msgId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tin nhắn (msg_id)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/messages/{msgId}/around": { "get": { "operationId": "getMessagesAround", "summary": "Các tin xung quanh một tin (để mở lại ngữ cảnh)", "description": "**Scope:** `chat:read`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại" }, { "name": "msgId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tin nhắn (msg_id)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/messages/search": { "get": { "operationId": "searchMessages", "summary": "Tìm tin nhắn theo nội dung (full-text)", "description": "**Scope:** `chat:read`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Từ khoá" }, { "name": "thread_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Chỉ trong một hội thoại" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/media": { "get": { "operationId": "listConversationMedia", "summary": "Ảnh/video, file hoặc link đã chia sẻ trong hội thoại", "description": "**Scope:** `chat:read`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "media", "file", "link" ], "default": "media" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Số bản ghi tối đa (1–200)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Bỏ qua N bản ghi đầu" } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/messages/{msgId}/forward": { "post": { "operationId": "forwardMessage", "summary": "Chuyển tiếp tin sang hội thoại khác (cùng tài khoản)", "description": "Hỗ trợ văn bản, ảnh, video, file (gửi lại từ file local như UI) và forward gốc của Facebook/Telegram. Loại khác trả 422.\n\n**Scope:** `chat:send`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại" }, { "name": "msgId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tin nhắn (msg_id)" } ], "x-scope": "chat:send", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targets": { "type": "array", "items": { "type": "object", "properties": { "thread_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "thread_type": { "type": "string", "enum": [ "user", "group" ], "description": "user = chat 1-1, group = nhóm", "default": "user" } }, "required": [ "thread_id" ], "additionalProperties": false }, "minItems": 1, "maxItems": 20 } }, "required": [ "targets" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/messages/{msgId}/reactions": { "post": { "operationId": "addReaction", "summary": "Thả reaction (emoji hoặc mã Zalo như HEART, LIKE)", "description": "**Scope:** `chat:send`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại" }, { "name": "msgId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tin nhắn (msg_id)" } ], "x-scope": "chat:send", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emoji": { "type": "string", "minLength": 1, "maxLength": 32 } }, "required": [ "emoji" ], "additionalProperties": false } } } } }, "delete": { "operationId": "removeReaction", "summary": "Gỡ reaction của mình", "description": "**Scope:** `chat:send`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại" }, { "name": "msgId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tin nhắn (msg_id)" } ], "x-scope": "chat:send", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/messages/{msgId}/recall": { "post": { "operationId": "recallMessage", "summary": "Thu hồi tin (với mọi người) rồi đánh dấu đã thu hồi trong DB", "description": "**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại" }, { "name": "msgId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tin nhắn (msg_id)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/messages/{msgId}/pin": { "post": { "operationId": "pinMessage", "summary": "Ghim tin trong hội thoại", "description": "**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại" }, { "name": "msgId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tin nhắn (msg_id)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "unpinMessage", "summary": "Bỏ ghim tin", "description": "**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại" }, { "name": "msgId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tin nhắn (msg_id)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/pinned-messages": { "get": { "operationId": "listPinnedMessages", "summary": "Tin đã ghim của hội thoại", "description": "**Scope:** `chat:read`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/read": { "post": { "operationId": "markConversationRead", "summary": "Đánh dấu đã đọc (DB + báo \"đã xem\" lên kênh)", "description": "**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/typing": { "post": { "operationId": "sendTyping", "summary": "Hiện trạng thái \"đang gõ\"", "description": "**Scope:** `chat:send`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:send", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "thread_type": { "type": "string", "enum": [ "user", "group" ], "description": "user = chat 1-1, group = nhóm" } }, "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/draft": { "get": { "operationId": "getDraft", "summary": "Tin nháp đang soạn", "description": "**Scope:** `chat:read`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "put": { "operationId": "saveDraft", "summary": "Lưu tin nháp (hiện trong ô soạn của app)", "description": "**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 10000 } }, "required": [ "content" ], "additionalProperties": false } } } } }, "delete": { "operationId": "deleteDraft", "summary": "Xoá tin nháp", "description": "**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/messages/{msgId}/media": { "get": { "operationId": "downloadMessageMedia", "summary": "Tải file/ảnh/video/ghi âm của một tin (tự tải về máy nếu chưa có)", "description": "**Scope:** `media:read`", "tags": [ "Media" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại" }, { "name": "msgId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tin nhắn (msg_id)" } ], "x-scope": "media:read", "responses": { "200": { "description": "Nội dung file", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/unread": { "post": { "operationId": "markConversationUnread", "summary": "Đánh dấu chưa đọc (đồng bộ lên Zalo)", "description": "Như menu \"Đánh dấu chưa đọc\": Zalo gắn dấu chưa đọc trên server (`zalo:addUnreadMark`). Bỏ dấu bằng `DELETE …/unread`.\n\n**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "clearConversationUnread", "summary": "Bỏ đánh dấu chưa đọc (đã đọc + gỡ dấu trên Zalo)", "description": "Như menu \"Đánh dấu đã đọc\": đánh dấu đã đọc như `POST …/read`, Zalo gỡ thêm dấu chưa đọc trên server (`zalo:removeUnreadMark`).\n\n**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/pin": { "post": { "operationId": "pinConversation", "summary": "Ghim hội thoại (trên kênh nếu kênh hỗ trợ)", "description": "Như menu \"Ghim hội thoại\": Zalo/Telegram ghim trên server (hiện ở mọi thiết bị); kênh không hỗ trợ thì ghim trong Deplao. `where` cho biết đã ghim ở đâu.\n\n**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "unpinConversation", "summary": "Bỏ ghim hội thoại", "description": "Như menu \"Ghim hội thoại\": Zalo/Telegram ghim trên server (hiện ở mọi thiết bị); kênh không hỗ trợ thì ghim trong Deplao. `where` cho biết đã ghim ở đâu.\n\n**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/mute": { "post": { "operationId": "muteConversation", "summary": "Tắt thông báo (lưu trong Deplao + đồng bộ lên Zalo/Telegram)", "description": "`until` = epoch ms hết hạn; bỏ trống hoặc 0 = vô thời hạn. `synced` = đã đồng bộ lên kênh hay chưa (kênh không hỗ trợ / lỗi mạng vẫn tắt trong Deplao).\n\n**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "until": { "type": "integer", "minimum": 0, "default": 0 } }, "additionalProperties": false } } } } }, "delete": { "operationId": "unmuteConversation", "summary": "Bật lại thông báo", "description": "**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/others": { "post": { "operationId": "moveConversationToOthers", "summary": "Chuyển vào \"Khác (lưu trữ)\" (tắt thông báo, Telegram: lưu trữ)", "description": "**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "moveConversationToMain", "summary": "Đưa về danh sách chính (bật thông báo)", "description": "**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/history/sync": { "post": { "operationId": "syncConversationHistory", "summary": "Tải tin cũ từ server của kênh vào Deplao", "description": "Lưu vào DB rồi đọc bằng `GET …/messages`. Telegram: `before_msg_id` = msg_id cũ nhất bạn đang có để lấy trang cũ hơn. Facebook: dùng `next_cursor` của lần trước làm `before_cursor`. Zalo: chỉ nhóm (Zalo không cho tải lịch sử chat 1-1).\n\n**Scope:** `chat:read`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "before_msg_id": { "type": "string", "maxLength": 64 }, "before_cursor": { "type": "string", "maxLength": 500 }, "topic_id": { "type": "string", "maxLength": 64, "description": "Telegram forum topic" } }, "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/drafts": { "get": { "operationId": "listDrafts", "summary": "Mọi tin nháp đang soạn của tài khoản (mới sửa trước)", "description": "**Scope:** `chat:read`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/messages/contact-card": { "post": { "operationId": "sendContactCard", "summary": "Gửi danh thiếp (Zalo: theo user_id; Telegram bot: theo số điện thoại)", "description": "**Scope:** `chat:send`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:send", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Zalo: ID người được giới thiệu" }, "phone": { "type": "string", "maxLength": 30, "description": "Zalo: tuỳ chọn; Telegram bot: bắt buộc" }, "name": { "type": "string", "maxLength": 100, "description": "Telegram bot: tên hiển thị (bắt buộc)" }, "thread_type": { "type": "string", "enum": [ "user", "group" ], "description": "user = chat 1-1, group = nhóm" }, "quote_msg_id": { "type": "string" } }, "additionalProperties": false }, "example": { "user_id": "8412345678901234567", "phone": "0912345678" } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/messages/bank-card": { "post": { "operationId": "sendBankCard", "summary": "Gửi thẻ ngân hàng (Zalo) — thẻ đã lưu hoặc nhập trực tiếp", "description": "Truyền `bank_card_id` (từ GET /accounts/{accountId}/bank-cards) hoặc đủ `bin_bank`, `account_number`, `account_name`.\n\n**Scope:** `chat:send`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:send", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_card_id": { "type": "integer", "minimum": 1 }, "bin_bank": { "type": "integer", "minimum": 100000, "maximum": 999999, "description": "Mã BIN ngân hàng (6 số)" }, "account_number": { "type": "string", "minLength": 4, "maxLength": 40 }, "account_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "thread_type": { "type": "string", "enum": [ "user", "group" ], "description": "user = chat 1-1, group = nhóm" } }, "additionalProperties": false }, "example": { "bin_bank": 970436, "account_number": "0011001234567", "account_name": "NGUYEN VAN A" } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/messages/voice": { "post": { "operationId": "sendVoiceMessage", "summary": "Gửi tin nhắn thoại (Zalo, Telegram bot)", "description": "File âm thanh (m4a/mp3/ogg…) qua `upload_id`, `library_uuid` hoặc `url`. Zalo: upload rồi gửi dạng ghi âm như nút micro trong app. Kênh khác: gửi file âm thanh bằng POST …/messages.\n\n**Scope:** `chat:send`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:send", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "upload_id": { "type": "string", "description": "ID từ POST /media/uploads" }, "library_uuid": { "type": "string", "description": "UUID item trong thư viện media" }, "url": { "type": "string", "format": "uri", "description": "Link http/https công khai, server tự tải về" } }, "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/reminders": { "get": { "operationId": "listReminders", "summary": "Nhắc hẹn trong hội thoại (Zalo)", "description": "**Scope:** `chat:read`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createReminder", "summary": "Tạo nhắc hẹn (Zalo)", "description": "**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "start_time": { "type": "integer", "minimum": 0, "description": "Epoch ms, phải ở tương lai" }, "repeat": { "type": "string", "enum": [ "none", "daily", "weekly", "monthly" ], "default": "none" }, "emoji": { "type": "string", "maxLength": 16, "default": "⏰" } }, "required": [ "title", "start_time" ], "additionalProperties": false }, "example": { "title": "Gọi lại cho khách", "start_time": 1767225600000, "repeat": "none" } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/reminders/{reminderId}": { "patch": { "operationId": "updateReminder", "summary": "Sửa nhắc hẹn (Zalo)", "description": "**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "reminderId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "start_time": { "type": "integer", "minimum": 0 }, "repeat": { "type": "string", "enum": [ "none", "daily", "weekly", "monthly" ], "default": "none" }, "emoji": { "type": "string", "maxLength": 16, "default": "⏰" } }, "required": [ "title", "start_time" ], "additionalProperties": false } } } } }, "delete": { "operationId": "deleteReminder", "summary": "Xoá nhắc hẹn (Zalo)", "description": "**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "reminderId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/labels": { "get": { "operationId": "listLabels", "summary": "Nhãn (local) dùng được ở tài khoản", "description": "**Scope:** `chat:read`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/labels": { "post": { "operationId": "createLabel", "summary": "Tạo nhãn", "description": "**Scope:** `chat:manage`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "color": { "type": "string", "maxLength": 20, "default": "#3B82F6" }, "text_color": { "type": "string", "maxLength": 20, "default": "#FFFFFF" }, "emoji": { "type": "string", "maxLength": 16, "default": "🏷️" }, "account_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 200, "description": "Chỉ hiện ở các tài khoản này; bỏ trống = mọi tài khoản" }, "shortcut": { "type": "string", "maxLength": 20 } }, "required": [ "name" ], "additionalProperties": false } } } } } }, "/v1/labels/{labelId}": { "patch": { "operationId": "updateLabel", "summary": "Sửa nhãn", "description": "**Scope:** `chat:manage`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "labelId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "color": { "type": "string", "maxLength": 20, "default": "#3B82F6" }, "text_color": { "type": "string", "maxLength": 20, "default": "#FFFFFF" }, "emoji": { "type": "string", "maxLength": 16, "default": "🏷️" }, "account_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 200, "description": "Chỉ hiện ở các tài khoản này; bỏ trống = mọi tài khoản" }, "shortcut": { "type": "string", "maxLength": 20 } }, "additionalProperties": false } } } } }, "delete": { "operationId": "deleteLabel", "summary": "Xoá nhãn (gỡ khỏi mọi hội thoại)", "description": "**Scope:** `chat:manage`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "labelId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/labels": { "get": { "operationId": "listConversationLabels", "summary": "Nhãn đang gán cho hội thoại", "description": "**Scope:** `chat:read`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "put": { "operationId": "setConversationLabels", "summary": "Đặt đúng tập nhãn cho hội thoại (gán thiếu, gỡ thừa)", "description": "Mỗi lần gán/gỡ đi qua cùng handler UI dùng nên workflow \"Khi gán hoặc gỡ nhãn\" vẫn chạy.\n\n**Scope:** `chat:manage`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 100 } }, "required": [ "label_ids" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/labels/{labelId}": { "post": { "operationId": "addConversationLabel", "summary": "Gán một nhãn cho hội thoại", "description": "**Scope:** `chat:manage`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "removeConversationLabel", "summary": "Gỡ một nhãn khỏi hội thoại", "description": "**Scope:** `chat:manage`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/zalo-labels": { "get": { "operationId": "listZaloLabels", "summary": "Nhãn trên server Zalo của tài khoản (chỉ Zalo, cần online)", "description": "**Scope:** `chat:read`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/quick-messages": { "get": { "operationId": "listQuickMessages", "summary": "Tin nhắn nhanh (/keyword) của tài khoản", "description": "**Scope:** `chat:read`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "upsertQuickMessage", "summary": "Tạo hoặc cập nhật tin nhắn nhanh (theo keyword)", "description": "**Scope:** `chat:manage`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "keyword": { "type": "string", "minLength": 1, "maxLength": 50 }, "title": { "type": "string", "maxLength": 5000 }, "media": { "description": "Giữ nguyên định dạng media của app (tuỳ chọn)" } }, "required": [ "keyword", "title" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/quick-messages/{id}": { "delete": { "operationId": "deleteQuickMessage", "summary": "Xoá tin nhắn nhanh", "description": "**Scope:** `chat:manage`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/stickers/recent": { "get": { "operationId": "listRecentStickers", "summary": "Sticker dùng gần đây", "description": "**Scope:** `chat:read`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/sticker-packs": { "get": { "operationId": "listStickerPacks", "summary": "Bộ sticker đã lưu", "description": "**Scope:** `chat:read`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/sticker-packs/{catId}/stickers": { "get": { "operationId": "listStickersInPack", "summary": "Sticker trong một bộ", "description": "**Scope:** `chat:read`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "catId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/stickers/search": { "get": { "operationId": "searchStickers", "summary": "ID sticker theo từ khoá (đã cache)", "description": "**Scope:** `chat:read`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "keyword", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 50 } } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/labels/{labelId}/conversations": { "get": { "operationId": "listLabelConversations", "summary": "Hội thoại đang gắn một nhãn", "description": "**Scope:** `chat:read`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/labels/bulk-assign": { "post": { "operationId": "bulkAssignLabels", "summary": "Gán nhiều nhãn cho nhiều hội thoại trong một lần", "description": "Một transaction như thao tác gán hàng loạt trong app. Khác gán từng nhãn: không bắn workflow \"Khi gán nhãn\".\n\n**Scope:** `chat:manage`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "minItems": 1, "maxItems": 50 }, "thread_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 1000 } }, "required": [ "label_ids", "thread_ids" ], "additionalProperties": false } } } } } }, "/v1/labels/order": { "put": { "operationId": "reorderLabels", "summary": "Sắp xếp thứ tự nhãn (theo mảng id)", "description": "**Scope:** `chat:manage`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "minItems": 1, "maxItems": 300 } }, "required": [ "label_ids" ], "additionalProperties": false } } } } } }, "/v1/labels/{labelId}/active": { "put": { "operationId": "setLabelActive", "summary": "Bật / ẩn nhãn", "description": "**Scope:** `chat:manage`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "labelId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean" } }, "required": [ "active" ], "additionalProperties": false } } } } } }, "/v1/labels/clone": { "post": { "operationId": "cloneLabels", "summary": "Sao chép bộ nhãn của tài khoản này sang tài khoản khác", "description": "**Scope:** `chat:manage`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_account_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "to_account_id": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "from_account_id", "to_account_id" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/zalo-labels/{labelId}/conversations/{threadId}": { "post": { "operationId": "assignZaloLabel", "summary": "Gắn nhãn Zalo cho hội thoại (mỗi hội thoại một nhãn)", "description": "Đồng bộ lên Zalo (hiện trên điện thoại). Gắn nhãn mới sẽ gỡ nhãn Zalo cũ của hội thoại như trong app; workflow \"Khi gán hoặc gỡ nhãn\" vẫn chạy.\n\n**Scope:** `chat:manage`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "removeZaloLabel", "summary": "Gỡ nhãn Zalo khỏi hội thoại", "description": "Đồng bộ lên Zalo (hiện trên điện thoại). Gắn nhãn mới sẽ gỡ nhãn Zalo cũ của hội thoại như trong app; workflow \"Khi gán hoặc gỡ nhãn\" vẫn chạy.\n\n**Scope:** `chat:manage`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/quick-messages/order": { "put": { "operationId": "reorderQuickMessages", "summary": "Sắp xếp thứ tự tin nhắn nhanh", "description": "**Scope:** `chat:manage`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "minItems": 1, "maxItems": 300 } }, "required": [ "ids" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/quick-messages/{id}/active": { "put": { "operationId": "setQuickMessageActive", "summary": "Bật / tắt một tin nhắn nhanh", "description": "**Scope:** `chat:manage`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean" } }, "required": [ "active" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/quick-messages/clone": { "post": { "operationId": "cloneQuickMessages", "summary": "Sao chép tin nhắn nhanh sang tài khoản khác", "description": "**Scope:** `chat:manage`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to_account_id": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "to_account_id" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/zalo-quick-messages": { "get": { "operationId": "listZaloQuickMessages", "summary": "Tin nhắn nhanh lưu trên Zalo (dùng được cả trên điện thoại)", "description": "**Scope:** `chat:read`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createZaloQuickMessage", "summary": "Tạo tin nhắn nhanh trên Zalo", "description": "**Scope:** `chat:manage`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "keyword": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^\\S+$" }, "title": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "keyword", "title" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/zalo-quick-messages/{itemId}": { "patch": { "operationId": "updateZaloQuickMessage", "summary": "Sửa tin nhắn nhanh trên Zalo", "description": "**Scope:** `chat:manage`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "keyword": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^\\S+$" }, "title": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "keyword", "title" ], "additionalProperties": false } } } } }, "delete": { "operationId": "deleteZaloQuickMessage", "summary": "Xoá tin nhắn nhanh trên Zalo", "description": "**Scope:** `chat:manage`", "tags": [ "Nhãn & tin nhanh" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/groups": { "get": { "operationId": "listGroups", "summary": "Nhóm của tài khoản (từ DB, mới hoạt động trước)", "description": "**Scope:** `chat:read`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Số bản ghi tối đa (1–200)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Bỏ qua N bản ghi đầu" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createGroup", "summary": "Tạo nhóm Zalo", "description": "**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "member_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 100 } }, "required": [ "name", "member_ids" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}": { "get": { "operationId": "getGroup", "summary": "Thông tin nhóm từ kênh (thành viên, admin, cài đặt)", "description": "**Scope:** `chat:read`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "renameGroup", "summary": "Đổi tên nhóm", "description": "**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "name" ], "additionalProperties": false } } } } }, "delete": { "operationId": "disbandGroup", "summary": "Giải tán nhóm (Zalo, cần là trưởng nhóm)", "description": "Không thể hoàn tác — bắt buộc `?confirm=true`.\n\n**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" }, { "name": "confirm", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/members": { "get": { "operationId": "listGroupMembers", "summary": "Thành viên nhóm (Zalo: danh sách đã lưu; Telegram: lấy từ kênh)", "description": "**Scope:** `chat:read`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 } } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "addGroupMembers", "summary": "Thêm thành viên vào nhóm", "description": "**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 50 } }, "required": [ "user_ids" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/members/{userId}": { "delete": { "operationId": "removeGroupMember", "summary": "Mời một thành viên ra khỏi nhóm", "description": "**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/invite-link": { "get": { "operationId": "getGroupInviteLink", "summary": "Link mời vào nhóm", "description": "**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "enableGroupInviteLink", "summary": "Bật link mời (Zalo)", "description": "**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "disableGroupInviteLink", "summary": "Tắt link mời (Zalo)", "description": "**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/leave": { "post": { "operationId": "leaveGroup", "summary": "Rời nhóm", "description": "**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/friends": { "get": { "operationId": "listFriends", "summary": "Danh sách bạn bè (Zalo). refresh=true tải lại từ Zalo", "description": "**Scope:** `contacts:read`", "tags": [ "Danh bạ" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Số bản ghi tối đa (1–200)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Bỏ qua N bản ghi đầu" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "refresh", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "x-scope": "contacts:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/friend-requests": { "get": { "operationId": "listFriendRequests", "summary": "Lời mời kết bạn đã nhận / đã gửi", "description": "**Scope:** `contacts:read`", "tags": [ "Danh bạ" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "received", "sent" ], "default": "received" } } ], "x-scope": "contacts:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "sendFriendRequest", "summary": "Gửi lời mời kết bạn (Zalo)", "description": "**Scope:** `contacts:write`", "tags": [ "Danh bạ" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "contacts:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "message": { "type": "string", "maxLength": 150, "default": "" } }, "required": [ "user_id" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/friend-requests/{userId}/accept": { "post": { "operationId": "acceptFriendRequest", "summary": "Chấp nhận lời mời kết bạn", "description": "**Scope:** `contacts:write`", "tags": [ "Danh bạ" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID người dùng trên kênh" } ], "x-scope": "contacts:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/friend-requests/{userId}/reject": { "post": { "operationId": "rejectFriendRequest", "summary": "Từ chối lời mời kết bạn", "description": "**Scope:** `contacts:write`", "tags": [ "Danh bạ" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID người dùng trên kênh" } ], "x-scope": "contacts:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/friend-requests/{userId}/cancel": { "post": { "operationId": "cancelFriendRequest", "summary": "Huỷ lời mời đã gửi", "description": "**Scope:** `contacts:write`", "tags": [ "Danh bạ" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID người dùng trên kênh" } ], "x-scope": "contacts:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/friends/{userId}": { "delete": { "operationId": "removeFriend", "summary": "Huỷ kết bạn (Zalo)", "description": "**Scope:** `contacts:write`", "tags": [ "Danh bạ" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID người dùng trên kênh" } ], "x-scope": "contacts:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/users/lookup": { "get": { "operationId": "lookupUserByPhone", "summary": "Tìm người dùng theo số điện thoại (DB trước, rồi Zalo)", "description": "**Scope:** `contacts:read`", "tags": [ "Danh bạ" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." }, { "name": "phone", "in": "query", "required": true, "schema": { "type": "string", "minLength": 6, "maxLength": 20 } } ], "x-scope": "contacts:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/users/{userId}": { "get": { "operationId": "getUserProfile", "summary": "Hồ sơ người dùng từ Zalo", "description": "**Scope:** `contacts:read`", "tags": [ "Danh bạ" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID người dùng trên kênh" } ], "x-scope": "contacts:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/admins": { "post": { "operationId": "addGroupAdmin", "summary": "Cấp quyền quản trị (Zalo: phó nhóm)", "description": "**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "user_id" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/admins/{userId}": { "delete": { "operationId": "removeGroupAdmin", "summary": "Gỡ quyền quản trị", "description": "**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/owner": { "post": { "operationId": "transferGroupOwner", "summary": "Chuyển quyền trưởng nhóm (Zalo)", "description": "Bạn sẽ mất quyền trưởng nhóm — bắt buộc `confirm: true`.\n\n**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "confirm": { "type": "boolean", "default": false } }, "required": [ "user_id" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/avatar": { "put": { "operationId": "setGroupAvatar", "summary": "Đổi ảnh nhóm (Zalo, Telegram)", "description": "**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "upload_id": { "type": "string" }, "library_uuid": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/settings": { "get": { "operationId": "getGroupSettings", "summary": "Cài đặt nhóm Zalo (khoá đổi tên, duyệt thành viên, chỉ admin nhắn…)", "description": "**Scope:** `chat:read`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "updateGroupSettings", "summary": "Sửa cài đặt nhóm (Zalo; Facebook: chỉ join_approval)", "description": "Chỉ gửi trường cần đổi; các cài đặt khác giữ nguyên (đọc cài đặt hiện tại trước, như bật/tắt từng mục trong app).\n\n**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "block_name": { "type": "boolean" }, "sign_admin_msg": { "type": "boolean" }, "set_topic_only": { "type": "boolean" }, "enable_msg_history": { "type": "boolean" }, "join_approval": { "type": "boolean" }, "lock_create_post": { "type": "boolean" }, "lock_create_poll": { "type": "boolean" }, "lock_send_msg": { "type": "boolean" }, "lock_view_member": { "type": "boolean" } }, "additionalProperties": false }, "example": { "join_approval": true, "lock_send_msg": false } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/pending-members": { "get": { "operationId": "listPendingGroupMembers", "summary": "Người xin vào nhóm đang chờ duyệt (Zalo)", "description": "**Scope:** `chat:read`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/pending-members/review": { "post": { "operationId": "reviewPendingGroupMembers", "summary": "Duyệt hoặc từ chối người xin vào nhóm (Zalo, Facebook)", "description": "Xử lý lần lượt từng người như nút \"Duyệt tất cả\" trong app; `results` cho biết từng người thành công hay lỗi.\n\n**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 100 }, "approve": { "type": "boolean" } }, "required": [ "user_ids", "approve" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/blocked-members": { "get": { "operationId": "listBlockedGroupMembers", "summary": "Thành viên bị chặn khỏi nhóm (Zalo)", "description": "**Scope:** `chat:read`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "blockGroupMember", "summary": "Chặn thành viên khỏi nhóm (Zalo; Telegram/Facebook: mời ra)", "description": "**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "user_id" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/blocked-members/{userId}": { "delete": { "operationId": "unblockGroupMember", "summary": "Bỏ chặn thành viên nhóm (Zalo, Telegram bot)", "description": "**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/group-links/info": { "get": { "operationId": "getGroupLinkInfo", "summary": "Xem nhóm từ link mời (Zalo): tên, số thành viên, trang thành viên", "description": "**Scope:** `chat:read`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." }, { "name": "link", "in": "query", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 300 }, "description": "vd https://zalo.me/g/abcxyz" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 1 } } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/group-links/join": { "post": { "operationId": "joinGroupByLink", "summary": "Vào nhóm bằng link mời (Zalo) hoặc username/ID (Telegram)", "description": "**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "link": { "type": "string", "minLength": 3, "maxLength": 300, "description": "Zalo: link zalo.me/g/…; Telegram: @username hoặc ID nhóm công khai" } }, "required": [ "link" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/users/{userId}/invite-to-groups": { "post": { "operationId": "inviteUserToGroups", "summary": "Mời một người vào nhiều nhóm (Zalo)", "description": "**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID người dùng trên kênh" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 50 } }, "required": [ "group_ids" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/users/{userId}/mutual-groups": { "get": { "operationId": "listMutualGroups", "summary": "Nhóm chung với một người (Zalo)", "description": "**Scope:** `contacts:read`", "tags": [ "Danh bạ" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID người dùng trên kênh" } ], "x-scope": "contacts:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/polls": { "post": { "operationId": "createPoll", "summary": "Tạo bình chọn trong nhóm (Zalo, Facebook, Telegram bot)", "description": "Các tuỳ chọn multiple/allow_add_option/hide_vote_preview/anonymous/expires_at chỉ áp dụng cho Zalo.\n\n**Scope:** `chat:send`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" } ], "x-scope": "chat:send", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 300 }, "options": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 2, "maxItems": 20 }, "multiple": { "type": "boolean", "default": false }, "allow_add_option": { "type": "boolean", "default": true }, "hide_vote_preview": { "type": "boolean", "default": false }, "anonymous": { "type": "boolean", "default": false }, "expires_at": { "type": "integer", "minimum": 0, "description": "Epoch ms; bỏ trống = không hết hạn" } }, "required": [ "question", "options" ], "additionalProperties": false }, "example": { "question": "Chốt lịch họp tuần sau?", "options": [ "Thứ 3", "Thứ 5" ], "multiple": false } } } } } }, "/v1/accounts/{accountId}/polls/{pollId}": { "get": { "operationId": "getPoll", "summary": "Chi tiết bình chọn: lựa chọn, số phiếu, người bình chọn (Zalo)", "description": "**Scope:** `chat:read`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "pollId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/polls/{pollId}/votes": { "post": { "operationId": "votePoll", "summary": "Bình chọn (Zalo, Facebook). Mảng rỗng = huỷ bình chọn (Zalo)", "description": "**Scope:** `chat:send`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "pollId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "chat:send", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "option_ids": { "type": "array", "items": { "anyOf": [ { "type": "integer" }, { "type": "string", "maxLength": 64 } ] }, "maxItems": 20 } }, "required": [ "option_ids" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/polls/{pollId}/lock": { "post": { "operationId": "lockPoll", "summary": "Khoá bình chọn (Zalo, người tạo)", "description": "**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "pollId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/polls/{pollId}/options": { "post": { "operationId": "addPollOption", "summary": "Thêm lựa chọn vào bình chọn (Zalo)", "description": "**Scope:** `chat:send`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "pollId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "chat:send", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "option": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "option" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/notes": { "post": { "operationId": "createGroupNote", "summary": "Tạo ghi chú nhóm (Zalo), tuỳ chọn ghim lên đầu", "description": "**Scope:** `chat:send`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" } ], "x-scope": "chat:send", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 2000 }, "pin": { "type": "boolean", "default": false } }, "required": [ "title" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/notes/{noteId}": { "patch": { "operationId": "updateGroupNote", "summary": "Sửa ghi chú nhóm (Zalo)", "description": "**Scope:** `chat:send`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "topicId của ghi chú" } ], "x-scope": "chat:send", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 2000 }, "pin": { "type": "boolean", "default": true } }, "required": [ "title" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/topics": { "get": { "operationId": "listForumTopics", "summary": "Chủ đề (forum topic) của siêu nhóm Telegram", "description": "**Scope:** `chat:read`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createForumTopic", "summary": "Tạo chủ đề (Telegram)", "description": "**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID nhóm (thread_id)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 128 }, "icon_color": { "type": "integer", "minimum": 0, "maximum": 16777215 }, "icon_emoji_id": { "type": "string", "maxLength": 64 } }, "required": [ "title" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/topics/{topicId}": { "patch": { "operationId": "updateForumTopic", "summary": "Sửa / đóng / ghim chủ đề (Telegram)", "description": "**Scope:** `chat:manage`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "topicId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID topic (root message id)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 128 }, "icon_emoji_id": { "type": "string", "maxLength": 64 }, "closed": { "type": "boolean" }, "pinned": { "type": "boolean" } }, "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/topics/{topicId}/messages": { "get": { "operationId": "listForumTopicMessages", "summary": "Tin mới nhất của một chủ đề, lấy trực tiếp từ Telegram", "description": "Tin đã lưu trong Deplao đọc bằng `GET …/conversations/{groupId}/messages?topic_id=`.\n\n**Scope:** `chat:read`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "topicId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID topic (root message id)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "sendForumTopicMessage", "summary": "Gửi tin vào chủ đề (Telegram): chữ hoặc một file", "description": "**Scope:** `chat:send`", "tags": [ "Nhóm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "topicId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID topic (root message id)" } ], "x-scope": "chat:send", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 4096, "description": "Chữ; khi gửi kèm file thì là chú thích" }, "upload_id": { "type": "string" }, "library_uuid": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/users/{userId}/block": { "post": { "operationId": "blockUser", "summary": "Chặn người dùng (Zalo, Facebook, Telegram)", "description": "**Scope:** `contacts:write`", "tags": [ "Danh bạ" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID người dùng trên kênh" } ], "x-scope": "contacts:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "unblockUser", "summary": "Bỏ chặn người dùng", "description": "**Scope:** `contacts:write`", "tags": [ "Danh bạ" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID người dùng trên kênh" } ], "x-scope": "contacts:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/users/{userId}/alias": { "put": { "operationId": "setUserAlias", "summary": "Đặt tên gợi nhớ (Zalo: đồng bộ lên Zalo; kênh khác: lưu trong Deplao)", "description": "**Scope:** `contacts:write`", "tags": [ "Danh bạ" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID người dùng trên kênh" } ], "x-scope": "contacts:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "alias": { "type": "string", "maxLength": 100, "description": "Chuỗi rỗng = xoá tên gợi nhớ" } }, "required": [ "alias" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/friend-aliases": { "get": { "operationId": "listFriendAliases", "summary": "Tên gợi nhớ đã đặt trên Zalo", "description": "**Scope:** `contacts:read`", "tags": [ "Danh bạ" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 } }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 200 } } ], "x-scope": "contacts:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/friend-recommendations": { "get": { "operationId": "listFriendRecommendations", "summary": "Gợi ý kết bạn và lời mời mới từ Zalo", "description": "`kind`: `request` = người ta gửi lời mời cho bạn, `suggestion` = Zalo gợi ý.\n\n**Scope:** `contacts:read`", "tags": [ "Danh bạ" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "contacts:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/users/{userId}/friend-status": { "get": { "operationId": "getFriendStatus", "summary": "Trạng thái bạn bè với một người (Zalo)", "description": "**Scope:** `contacts:read`", "tags": [ "Danh bạ" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID người dùng trên kênh" } ], "x-scope": "contacts:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/contacts/search": { "get": { "operationId": "searchContacts", "summary": "Tìm liên hệ & nhóm đã lưu (không dấu: \"duong\" ra \"Dương\"), xếp theo độ khớp", "description": "**Scope:** `contacts:read`", "tags": [ "Danh bạ" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "default": "" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "user", "group" ], "default": "all" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "x-scope": "contacts:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/usernames/{username}": { "get": { "operationId": "resolveTelegramUsername", "summary": "Tra @username Telegram ra người dùng / nhóm", "description": "**Scope:** `contacts:read`", "tags": [ "Danh bạ" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "username", "in": "path", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 64 }, "description": "Có hoặc không có @" } ], "x-scope": "contacts:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/zalo/settings": { "get": { "operationId": "getZaloPrivacySettings", "summary": "Cài đặt quyền riêng tư của tài khoản Zalo", "description": "Đọc trực tiếp từ Zalo (như Cài đặt → Tài khoản → Quyền riêng tư Zalo). Mỗi mục: key (dùng khi đổi), value hiện tại (null = Zalo không trả), các lựa chọn hợp lệ. two_factor_enabled chỉ đọc.\n\n**Scope:** `accounts:read`", "tags": [ "Tài khoản" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "accounts:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "updateZaloPrivacySetting", "summary": "Đổi một cài đặt quyền riêng tư Zalo", "description": "Mỗi lần một mục, như app Zalo. key theo danh sách của GET; value thuộc lựa chọn của mục đó. Chú ý: receive_message = 2 hoặc accept_stranger_call = 2 (chỉ bạn bè) chặn khách chưa kết bạn nhắn / gọi.\n\n**Scope:** `accounts:manage`", "tags": [ "Tài khoản" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "accounts:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "value": { "type": "integer" } }, "required": [ "key", "value" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/users/{userId}/presence": { "get": { "operationId": "getUserPresence", "summary": "Trạng thái truy cập của một người (Zalo)", "description": "status: online | offline (kèm last_seen_at, ms) | hidden (người đó ẩn trạng thái truy cập) | unknown. Kết quả đệm 60 giây cho mỗi người; refresh=true hỏi lại Zalo ngay.\n\n**Scope:** `contacts:read`", "tags": [ "Danh bạ" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID người dùng Zalo" }, { "name": "refresh", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Bỏ qua đệm 60 giây" } ], "x-scope": "contacts:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "online", "offline", "hidden", "unknown" ] }, "last_seen_at": { "type": [ "integer", "null" ] }, "show_online_status": { "type": "boolean" } }, "required": [ "status", "last_seen_at", "show_online_status" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/zalo/catalogs": { "get": { "operationId": "listZaloCatalogs", "summary": "Danh mục sản phẩm của tài khoản Zalo Business", "description": "Đọc từ Zalo theo trang. url = link catalog.zalo.me để gửi vào hội thoại (route gửi link).\n\n**Scope:** `chat:read`", "tags": [ "Danh mục sản phẩm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createZaloCatalog", "summary": "Tạo danh mục sản phẩm Zalo Business", "description": "**Scope:** `crm:write`", "tags": [ "Danh mục sản phẩm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "name" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/zalo/catalogs/{catalogId}/products": { "get": { "operationId": "listZaloCatalogProducts", "summary": "Sản phẩm trong một danh mục Zalo Business", "description": "Đọc từ Zalo theo trang. Mỗi sản phẩm có url (catalog.zalo.me) để gửi vào hội thoại.\n\n**Scope:** `chat:read`", "tags": [ "Danh mục sản phẩm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "catalogId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID danh mục" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createZaloCatalogProduct", "summary": "Thêm sản phẩm vào danh mục Zalo Business", "description": "Ảnh: photos (link đã có trên Zalo) và / hoặc photo_files (ảnh mới, Deplao tải lên Zalo trước).\n\n**Scope:** `crm:write`", "tags": [ "Danh mục sản phẩm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "catalogId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID danh mục" } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "price": { "type": "string", "minLength": 1, "maxLength": 30, "description": "Giá, chỉ số (VNĐ), vd \"150000\"" }, "description": { "type": "string", "maxLength": 2000 }, "photos": { "type": "array", "items": { "type": "string", "maxLength": 1000 }, "maxItems": 5, "description": "URL ảnh đã có trên Zalo (vd ảnh của sản phẩm khác), giữ đúng thứ tự" }, "photo_files": { "type": "array", "items": { "type": "object", "properties": { "upload_id": { "type": "string", "description": "ID từ POST /media/uploads" }, "library_uuid": { "type": "string", "description": "UUID ảnh trong thư viện media" }, "url": { "type": "string", "format": "uri", "description": "Link ảnh http/https công khai, server tự tải về" } }, "additionalProperties": false }, "maxItems": 5, "description": "Ảnh mới: mỗi mục đúng một trong upload_id, library_uuid, url. Deplao tải lên Zalo trước rồi xếp sau photos. Tổng photos + photo_files tối đa 5" } }, "required": [ "name", "price" ], "additionalProperties": false } } } } }, "delete": { "operationId": "deleteZaloCatalogProducts", "summary": "Xoá sản phẩm khỏi danh mục Zalo Business", "description": "Xoá trên Zalo, không hoàn tác — gửi confirm=true.\n\n**Scope:** `crm:write`", "tags": [ "Danh mục sản phẩm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "catalogId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID danh mục" } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 100 }, "confirm": { "type": "boolean", "default": false } }, "required": [ "product_ids" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/zalo/catalogs/{catalogId}": { "patch": { "operationId": "updateZaloCatalog", "summary": "Đổi tên danh mục sản phẩm Zalo Business", "description": "**Scope:** `crm:write`", "tags": [ "Danh mục sản phẩm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "catalogId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID danh mục" } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "name" ], "additionalProperties": false } } } } }, "delete": { "operationId": "deleteZaloCatalog", "summary": "Xoá danh mục sản phẩm Zalo Business", "description": "Xoá cả sản phẩm trong danh mục trên Zalo, không hoàn tác — gửi confirm=true.\n\n**Scope:** `crm:write`", "tags": [ "Danh mục sản phẩm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "catalogId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID danh mục" }, { "name": "confirm", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Phải là true" } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/zalo/catalogs/{catalogId}/products/{productId}": { "patch": { "operationId": "updateZaloCatalogProduct", "summary": "Sửa sản phẩm trong danh mục Zalo Business", "description": "Gửi đủ tên, giá, mô tả, ảnh (như form sửa của app) và created_at của sản phẩm (từ danh sách sản phẩm). Ảnh giữ lại: photos; ảnh mới: photo_files.\n\n**Scope:** `crm:write`", "tags": [ "Danh mục sản phẩm" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "catalogId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID sản phẩm" } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "price": { "type": "string", "minLength": 1, "maxLength": 30, "description": "Giá, chỉ số (VNĐ), vd \"150000\"" }, "description": { "type": "string", "maxLength": 2000 }, "photos": { "type": "array", "items": { "type": "string", "maxLength": 1000 }, "maxItems": 5, "description": "URL ảnh đã có trên Zalo (vd ảnh của sản phẩm khác), giữ đúng thứ tự" }, "photo_files": { "type": "array", "items": { "type": "object", "properties": { "upload_id": { "type": "string", "description": "ID từ POST /media/uploads" }, "library_uuid": { "type": "string", "description": "UUID ảnh trong thư viện media" }, "url": { "type": "string", "format": "uri", "description": "Link ảnh http/https công khai, server tự tải về" } }, "additionalProperties": false }, "maxItems": 5, "description": "Ảnh mới: mỗi mục đúng một trong upload_id, library_uuid, url. Deplao tải lên Zalo trước rồi xếp sau photos. Tổng photos + photo_files tối đa 5" }, "created_at": { "type": "integer", "minimum": 0, "description": "created_at của sản phẩm (ms)" } }, "required": [ "name", "price", "created_at" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/conversations/{threadId}/auto-delete": { "get": { "operationId": "getConversationAutoDelete", "summary": "Tự xoá tin nhắn của hội thoại trên Zalo", "description": "Đọc lại từ Zalo (Zalo không báo khi đổi trên điện thoại). ttl_ms (ms): 0 = Tắt, 86400000 = 1 ngày, 604800000 = 7 ngày, 1209600000 = 14 ngày. Zalo xoá tin trên các thiết bị Zalo; Deplao vẫn giữ tin đã lưu.\n\n**Scope:** `chat:read`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "thread_id": { "type": "string" }, "ttl_ms": { "type": "integer" }, "enabled": { "type": "boolean" } }, "required": [ "thread_id", "ttl_ms", "enabled" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "put": { "operationId": "setConversationAutoDelete", "summary": "Bật / tắt tự xoá tin nhắn trên Zalo", "description": "Như mục \"Tự xoá tin nhắn\" trong chi tiết hội thoại. ttl_ms (ms): 0 = Tắt, 86400000 = 1 ngày, 604800000 = 7 ngày, 1209600000 = 14 ngày. Zalo xoá tin trên các thiết bị Zalo; Deplao vẫn giữ tin đã lưu. Nhóm có thể chỉ cho trưởng / phó nhóm đổi.\n\n**Scope:** `chat:manage`", "tags": [ "Chat" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID hội thoại (user id hoặc group id của kênh)" } ], "x-scope": "chat:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "thread_id": { "type": "string" }, "ttl_ms": { "type": "integer" }, "enabled": { "type": "boolean" } }, "required": [ "thread_id", "ttl_ms", "enabled" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ttl_ms": { "type": "integer", "minimum": 0, "description": "0 = tắt; 86400000 = 1 ngày; 604800000 = 7 ngày; 1209600000 = 14 ngày" }, "thread_type": { "type": "string", "enum": [ "user", "group" ], "description": "user = chat 1-1, group = nhóm", "default": "user" } }, "required": [ "ttl_ms" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/crm/contacts": { "get": { "operationId": "listCrmContacts", "summary": "Khách hàng (bạn bè, người lạ, nhóm) với bộ lọc như trang CRM", "description": "**Scope:** `crm:read`", "tags": [ "CRM" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Số bản ghi tối đa (1–200)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Bỏ qua N bản ghi đầu" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "friend", "non_friend", "group" ], "default": "all" } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "name", "last_message" ], "default": "last_message" } }, { "name": "sort_dir", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "x-scope": "crm:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/crm/contacts/stats": { "get": { "operationId": "getCrmContactStats", "summary": "Thống kê khách hàng (tổng, bạn bè, ghi chú)", "description": "**Scope:** `crm:read`", "tags": [ "CRM" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "crm:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/crm/contacts/{contactId}": { "get": { "operationId": "getCrmContact", "summary": "Hồ sơ khách: thông tin, nhãn, ghi chú, 5 tin gần nhất", "description": "**Scope:** `crm:read`", "tags": [ "CRM" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "crm:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "updateCrmContact", "summary": "Cập nhật số điện thoại / tên hiển thị / biệt danh (lưu trên Deplao)", "description": "**Scope:** `crm:write`", "tags": [ "CRM" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "maxLength": 30 }, "display_name": { "type": "string", "maxLength": 200 }, "alias": { "type": "string", "maxLength": 100 } }, "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/crm/contacts/{contactId}/notes": { "get": { "operationId": "listCrmNotes", "summary": "Ghi chú của khách", "description": "**Scope:** `crm:read`", "tags": [ "CRM" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "crm:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createCrmNote", "summary": "Thêm ghi chú", "description": "**Scope:** `crm:write`", "tags": [ "CRM" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 10000 }, "topic_id": { "type": "string" } }, "required": [ "content" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/crm/notes/{noteId}": { "patch": { "operationId": "updateCrmNote", "summary": "Sửa ghi chú", "description": "**Scope:** `crm:write`", "tags": [ "CRM" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "content": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "contact_id", "content" ], "additionalProperties": false } } } } }, "delete": { "operationId": "deleteCrmNote", "summary": "Xoá ghi chú", "description": "**Scope:** `crm:write`", "tags": [ "CRM" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/campaigns": { "get": { "operationId": "listCampaigns", "summary": "Chiến dịch của tài khoản", "description": "**Scope:** `crm:read`", "tags": [ "Chiến dịch" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "crm:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createCampaign", "summary": "Tạo chiến dịch (trạng thái draft)", "description": "**Scope:** `crm:write`", "tags": [ "Chiến dịch" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "campaign_type": { "type": "string", "enum": [ "message", "friend_request", "mixed" ], "default": "message" }, "template_message": { "anyOf": [ { "type": "string", "maxLength": 20000 }, { "type": "object" } ], "description": "Nội dung gửi; hỗ trợ biến như UI ({name}...) hoặc JSON blocks của trình soạn", "default": "" }, "friend_request_message": { "type": "string", "maxLength": 500, "default": "" }, "mixed_config": { "anyOf": [ { "type": "string" }, { "type": "object" } ] }, "delay_seconds": { "type": "integer", "minimum": 5, "maximum": 86400, "description": "Giãn cách giữa 2 liên hệ (giây); hàng đợi luôn chờ tối thiểu 30 giây", "default": 60 } }, "required": [ "name" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/campaigns/{campaignId}": { "get": { "operationId": "getCampaign", "summary": "Một chiến dịch", "description": "**Scope:** `crm:read`", "tags": [ "Chiến dịch" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "crm:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "updateCampaign", "summary": "Sửa chiến dịch", "description": "**Scope:** `crm:write`", "tags": [ "Chiến dịch" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "campaign_type": { "type": "string", "enum": [ "message", "friend_request", "mixed" ], "default": "message" }, "template_message": { "anyOf": [ { "type": "string", "maxLength": 20000 }, { "type": "object" } ], "description": "Nội dung gửi; hỗ trợ biến như UI ({name}...) hoặc JSON blocks của trình soạn", "default": "" }, "friend_request_message": { "type": "string", "maxLength": 500, "default": "" }, "mixed_config": { "anyOf": [ { "type": "string" }, { "type": "object" } ] }, "delay_seconds": { "type": "integer", "minimum": 5, "maximum": 86400, "description": "Giãn cách giữa 2 liên hệ (giây); hàng đợi luôn chờ tối thiểu 30 giây", "default": 60 } }, "additionalProperties": false } } } } }, "delete": { "operationId": "deleteCampaign", "summary": "Xoá chiến dịch", "description": "**Scope:** `crm:write`", "tags": [ "Chiến dịch" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/campaigns/{campaignId}/clone": { "post": { "operationId": "cloneCampaign", "summary": "Nhân bản chiến dịch", "description": "**Scope:** `crm:write`", "tags": [ "Chiến dịch" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "include_contacts": { "type": "boolean", "default": false } }, "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/campaigns/{campaignId}/status": { "post": { "operationId": "setCampaignStatus", "summary": "Chạy / tạm dừng / kết thúc chiến dịch", "description": "`active` bắt đầu hàng đợi gửi theo tài khoản (giãn cách như cấu hình), `paused` tạm dừng, `done` kết thúc.\n\n**Scope:** `campaigns:run`", "tags": [ "Chiến dịch" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "campaigns:run", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "active", "paused", "done" ] } }, "required": [ "status" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/campaigns/{campaignId}/contacts": { "get": { "operationId": "listCampaignContacts", "summary": "Người nhận của chiến dịch và trạng thái gửi", "description": "**Scope:** `crm:read`", "tags": [ "Chiến dịch" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "crm:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "addCampaignContacts", "summary": "Thêm người nhận vào chiến dịch", "description": "**Scope:** `crm:write`", "tags": [ "Chiến dịch" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "display_name": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 30 }, "avatar": { "type": "string", "maxLength": 1000 } }, "required": [ "contact_id" ], "additionalProperties": false }, "minItems": 1, "maxItems": 5000 } }, "required": [ "contacts" ], "additionalProperties": false } } } } }, "delete": { "operationId": "removeCampaignContacts", "summary": "Xoá người nhận (theo danh sách hoặc tất cả)", "description": "**Scope:** `crm:write`", "tags": [ "Chiến dịch" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 5000 }, "all": { "type": "boolean", "default": false } }, "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/campaigns/{campaignId}/contacts/from-label": { "post": { "operationId": "addCampaignContactsFromLabel", "summary": "Thêm mọi hội thoại đang gắn một nhãn vào chiến dịch", "description": "**Scope:** `crm:write`", "tags": [ "Chiến dịch" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label_id": { "type": "integer", "minimum": 1 }, "only_users": { "type": "boolean", "description": "Bỏ qua nhóm chat", "default": true } }, "required": [ "label_id" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/campaigns/{campaignId}/contacts/from-group": { "post": { "operationId": "addCampaignContactsFromGroup", "summary": "Thêm thành viên một nhóm (đã quét/lưu) vào chiến dịch", "description": "Như \"Thêm vào chiến dịch\" ở tab Thành viên nhóm. Thành viên lấy từ danh sách đã lưu (quét nhóm trong app trước nếu trống).\n\n**Scope:** `crm:write`", "tags": [ "Chiến dịch" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "exclude_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 5000, "default": [] } }, "required": [ "group_id" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/campaigns/{campaignId}/send-log": { "get": { "operationId": "getCampaignSendLog", "summary": "Nhật ký gửi của chiến dịch", "description": "**Scope:** `crm:read`", "tags": [ "Chiến dịch" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 } } ], "x-scope": "crm:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/campaigns-stats": { "get": { "operationId": "getCampaignStats", "summary": "Thống kê chiến dịch nổi bật", "description": "**Scope:** `crm:read`", "tags": [ "Chiến dịch" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } } ], "x-scope": "crm:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/campaigns-queue": { "get": { "operationId": "getCampaignQueueStatus", "summary": "Trạng thái hàng đợi gửi chiến dịch", "description": "**Scope:** `crm:read`", "tags": [ "Chiến dịch" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "crm:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/crm/activity": { "get": { "operationId": "getCrmActivityStats", "summary": "Hoạt động CRM trong khoảng thời gian", "description": "**Scope:** `crm:read`", "tags": [ "CRM" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." }, { "name": "since", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 0 }, "description": "Epoch ms" }, { "name": "until", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-scope": "crm:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/bank-cards": { "get": { "operationId": "listBankCards", "summary": "Thẻ ngân hàng đã lưu để gửi cho khách", "description": "**Scope:** `crm:read`", "tags": [ "CRM" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "crm:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createBankCard", "summary": "Lưu thẻ ngân hàng (để gửi nhanh cho khách)", "description": "**Scope:** `crm:write`", "tags": [ "CRM" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "bin_bank": { "type": "integer", "minimum": 100000, "maximum": 999999, "description": "Mã BIN ngân hàng (6 số, vd 970436 = Vietcombank)" }, "account_number": { "type": "string", "minLength": 4, "maxLength": 40 }, "account_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "is_default": { "type": "boolean", "default": false } }, "required": [ "bank_name", "bin_bank", "account_number", "account_name" ], "additionalProperties": false }, "example": { "bank_name": "Vietcombank", "bin_bank": 970436, "account_number": "0011001234567", "account_name": "NGUYEN VAN A", "is_default": true } } } } } }, "/v1/accounts/{accountId}/bank-cards/{cardId}": { "patch": { "operationId": "updateBankCard", "summary": "Sửa thẻ ngân hàng", "description": "**Scope:** `crm:write`", "tags": [ "CRM" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "cardId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "bin_bank": { "type": "integer", "minimum": 100000, "maximum": 999999 }, "account_number": { "type": "string", "minLength": 4, "maxLength": 40 }, "account_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "is_default": { "type": "boolean" } }, "additionalProperties": false } } } } }, "delete": { "operationId": "deleteBankCard", "summary": "Xoá thẻ ngân hàng đã lưu", "description": "**Scope:** `crm:write`", "tags": [ "CRM" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "cardId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "crm:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/workflows": { "get": { "operationId": "listWorkflows", "summary": "Danh sách workflow", "description": "**Scope:** `workflow:read`", "tags": [ "Workflow" ], "parameters": [ { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Chỉ workflow áp dụng cho tài khoản này" } ], "x-scope": "workflow:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createWorkflow", "summary": "Tạo workflow", "description": "**Scope:** `workflow:write`", "tags": [ "Workflow" ], "parameters": [], "x-scope": "workflow:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000, "default": "" }, "enabled": { "type": "boolean", "default": false }, "channel": { "type": "string", "enum": [ "zalo", "facebook", "telegram_user", "telegram_bot" ], "default": "zalo" }, "account_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 200, "description": "Tài khoản áp dụng; rỗng = mọi tài khoản", "default": [] }, "nodes": { "type": "array", "items": { "type": "object" }, "maxItems": 500, "description": "Node theo định dạng của trình soạn workflow (xem GET /workflows/node-types)" }, "edges": { "type": "array", "items": { "type": "object" }, "maxItems": 2000 } }, "required": [ "name", "nodes", "edges" ], "additionalProperties": false } } } } } }, "/v1/workflows/node-types": { "get": { "operationId": "listWorkflowNodeTypes", "summary": "Danh mục node (như palette của trình soạn) và cấu hình mặc định", "description": "**Scope:** `workflow:read`", "tags": [ "Workflow" ], "parameters": [], "x-scope": "workflow:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/workflows/{workflowId}": { "get": { "operationId": "getWorkflow", "summary": "Một workflow (kèm nodes, edges)", "description": "**Scope:** `workflow:read`", "tags": [ "Workflow" ], "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "workflow:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "put": { "operationId": "updateWorkflow", "summary": "Ghi đè workflow (giữ id, ngày tạo)", "description": "**Scope:** `workflow:write`", "tags": [ "Workflow" ], "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "workflow:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000, "default": "" }, "enabled": { "type": "boolean", "default": false }, "channel": { "type": "string", "enum": [ "zalo", "facebook", "telegram_user", "telegram_bot" ], "default": "zalo" }, "account_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 200, "description": "Tài khoản áp dụng; rỗng = mọi tài khoản", "default": [] }, "nodes": { "type": "array", "items": { "type": "object" }, "maxItems": 500, "description": "Node theo định dạng của trình soạn workflow (xem GET /workflows/node-types)" }, "edges": { "type": "array", "items": { "type": "object" }, "maxItems": 2000 } }, "required": [ "name", "nodes", "edges" ], "additionalProperties": false } } } } }, "patch": { "operationId": "toggleWorkflow", "summary": "Bật / tắt workflow", "description": "**Scope:** `workflow:write`", "tags": [ "Workflow" ], "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "workflow:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false } } } } }, "delete": { "operationId": "deleteWorkflow", "summary": "Xoá workflow", "description": "**Scope:** `workflow:write`", "tags": [ "Workflow" ], "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "workflow:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/workflows/{workflowId}/clone": { "post": { "operationId": "cloneWorkflow", "summary": "Nhân bản workflow sang tài khoản khác", "description": "**Scope:** `workflow:write`", "tags": [ "Workflow" ], "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "workflow:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target_account_id": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "target_account_id" ], "additionalProperties": false } } } } } }, "/v1/workflows/{workflowId}/run": { "post": { "operationId": "runWorkflow", "summary": "Chạy workflow ngay với dữ liệu kích hoạt tuỳ ý (như nút \"Chạy thử\")", "description": "**Scope:** `workflow:run`", "tags": [ "Workflow" ], "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "workflow:run", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "trigger_data": { "type": "object", "default": {} } }, "additionalProperties": false } } } } } }, "/v1/workflows/{workflowId}/simulate": { "post": { "operationId": "simulateWorkflow", "summary": "Chạy giả lập (không gửi tin thật)", "description": "**Scope:** `workflow:run`", "tags": [ "Workflow" ], "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "workflow:run", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "trigger_data": { "type": "object", "default": {} } }, "additionalProperties": false } } } } } }, "/v1/workflows/events/{eventName}": { "post": { "operationId": "emitWorkflowEvent", "summary": "Bắn sự kiện cho các workflow có node \"Khi API/plugin gọi\" (trigger.api)", "description": "Workflow khớp tên sự kiện sẽ chạy bất đồng bộ (như mọi trigger). Trong workflow dùng `{{ $trigger.payload. }}`.\n\n**Scope:** `workflow:run`", "tags": [ "Workflow" ], "parameters": [ { "name": "eventName", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9_.:-]+$" } } ], "x-scope": "workflow:run", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } }, "example": { "success": true, "data": { "matched": 1, "workflow_ids": [ "8c1f…" ] }, "request_id": "3f0c0b6e-6d0a-4b8e-9d1a-1d2f3a4b5c6d" } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "payload": { "type": "object", "default": {} }, "account_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Chỉ chạy workflow áp dụng cho tài khoản này" } }, "additionalProperties": false }, "example": { "payload": { "order_id": "DH2291", "phone": "0901234567" } } } } } } }, "/v1/workflows/{workflowId}/runs": { "get": { "operationId": "listWorkflowRuns", "summary": "Lịch sử chạy gần đây", "description": "**Scope:** `workflow:read`", "tags": [ "Workflow" ], "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "x-scope": "workflow:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "deleteWorkflowRuns", "summary": "Xoá lịch sử chạy của workflow", "description": "**Scope:** `workflow:write`", "tags": [ "Workflow" ], "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "workflow:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/workflows/{workflowId}/webhook-url": { "get": { "operationId": "getWorkflowWebhookUrl", "summary": "URL webhook công khai của node \"Webhook bên ngoài\"", "description": "**Scope:** `workflow:read`", "tags": [ "Workflow" ], "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "workflow:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/workflows/{workflowId}/webhook-url/regenerate": { "post": { "operationId": "regenerateWorkflowWebhookToken", "summary": "Đổi token webhook (link cũ hết hiệu lực ngay)", "description": "**Scope:** `workflow:write`", "tags": [ "Workflow" ], "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "workflow:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/workflows/clone": { "post": { "operationId": "cloneAccountWorkflows", "summary": "Sao chép mọi workflow của tài khoản này sang tài khoản khác", "description": "Như \"Sao chép workflow sang tài khoản\" trong app: bản sao áp dụng cho tài khoản đích, giữ trạng thái bật/tắt.\n\n**Scope:** `workflow:write`", "tags": [ "Workflow" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "workflow:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to_account_id": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "to_account_id" ], "additionalProperties": false } } } } } }, "/v1/integrations": { "get": { "operationId": "listIntegrations", "summary": "Danh sách tích hợp đã cấu hình", "description": "**Scope:** `integrations:read`", "tags": [ "Tích hợp" ], "parameters": [], "x-scope": "integrations:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createIntegration", "summary": "Thêm tích hợp (credential được mã hoá, không bao giờ trả ra)", "description": "**Scope:** `integrations:manage`", "tags": [ "Tích hợp" ], "parameters": [], "x-scope": "integrations:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "kiotviet", "haravan", "sapo", "nhanh", "pancake", "casso", "sepay", "ghn", "ghtk", "telegram_bot" ], "description": "Xem GET /integrations/types" }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Bỏ trống = tên loại tích hợp" }, "enabled": { "type": "boolean", "default": true }, "credentials": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 4000 }, "description": "Khoá theo GET /integrations/types" }, "settings": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "credentials" ], "additionalProperties": false }, "example": { "type": "ghn", "credentials": { "token": "ghn_xxx", "shopId": "123456" }, "settings": { "environment": "production" } } } } } } }, "/v1/integrations/{integrationId}": { "get": { "operationId": "getIntegration", "summary": "Một tích hợp (không có credential)", "description": "**Scope:** `integrations:read`", "tags": [ "Tích hợp" ], "parameters": [ { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "integrations:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "updateIntegration", "summary": "Sửa tích hợp: tên, cài đặt, credential (bỏ trống = giữ cũ), bật/tắt", "description": "**Scope:** `integrations:manage`", "tags": [ "Tích hợp" ], "parameters": [ { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "integrations:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "enabled": { "type": "boolean" }, "credentials": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 4000 } }, "settings": { "type": "object", "additionalProperties": {} } }, "additionalProperties": false } } } } }, "delete": { "operationId": "deleteIntegration", "summary": "Xoá tích hợp (workflow dùng tích hợp này sẽ báo lỗi khi chạy)", "description": "**Scope:** `integrations:manage`", "tags": [ "Tích hợp" ], "parameters": [ { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "integrations:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/integrations/{integrationId}/actions/{action}": { "post": { "operationId": "executeIntegrationAction", "summary": "Gọi một action của adapter (vd: lookupOrder, createOrder, getTracking)", "description": "Tên action và tham số giống node workflow tương ứng (vd. node `nhanh.lookupOrder` ↔ action `lookupOrder`).\n\n**Scope:** `integrations:execute`", "tags": [ "Tích hợp" ], "parameters": [ { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9_.-]+$" } } ], "x-scope": "integrations:execute", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "params": { "type": "object", "default": {} } }, "additionalProperties": false }, "example": { "params": { "orderId": "DH2291" } } } } } } }, "/v1/integrations/types": { "get": { "operationId": "listIntegrationTypes", "summary": "Loại tích hợp hỗ trợ và các khoá credential / cài đặt cần nhập", "description": "**Scope:** `integrations:read`", "tags": [ "Tích hợp" ], "parameters": [], "x-scope": "integrations:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/integrations/by-type/{type}/actions/{action}": { "post": { "operationId": "executeIntegrationActionByType", "summary": "Gọi action theo loại tích hợp (dùng tích hợp đang bật của loại đó)", "description": "Tiện khi chỉ có một tích hợp mỗi loại, như node workflow (vd. `ghn` + `getTracking`).\n\n**Scope:** `integrations:execute`", "tags": [ "Tích hợp" ], "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "kiotviet", "haravan", "sapo", "nhanh", "pancake", "casso", "sepay", "ghn", "ghtk", "telegram_bot" ] } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9_.-]+$" } } ], "x-scope": "integrations:execute", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "params": { "type": "object", "default": {} } }, "additionalProperties": false } } } } } }, "/v1/integrations/{integrationId}/test": { "post": { "operationId": "testIntegration", "summary": "Kiểm tra kết nối của tích hợp", "description": "**Scope:** `integrations:execute`", "tags": [ "Tích hợp" ], "parameters": [ { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "integrations:execute", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/projects": { "get": { "operationId": "listErpProjects", "summary": "Dự án", "description": "Kênh: `erp:project:list`\n\n**Scope:** `erp:read`", "tags": [ "ERP" ], "parameters": [ { "name": "archived", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "x-scope": "erp:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createErpProject", "summary": "Tạo dự án", "description": "Kênh: `erp:project:create`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 5000 }, "color": { "type": "string", "maxLength": 20 }, "department_id": {} }, "required": [ "name" ], "additionalProperties": false } } } } } }, "/v1/erp/projects/{id}": { "patch": { "operationId": "updateErpProject", "summary": "Sửa dự án", "description": "Kênh: `erp:project:update`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } }, "delete": { "operationId": "deleteErpProject", "summary": "Xoá dự án", "description": "Kênh: `erp:project:delete`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/tasks": { "get": { "operationId": "listErpTasks", "summary": "Công việc (lọc theo dự án, trạng thái, người làm...)", "description": "Query được chuyển nguyên cho bộ lọc của trang Công việc (vd: project_id, status, assignee_id, search).\n\nKênh: `erp:task:list`\n\n**Scope:** `erp:read`", "tags": [ "ERP" ], "parameters": [], "x-scope": "erp:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createErpTask", "summary": "Tạo công việc", "description": "Kênh: `erp:task:create`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "title" ] }, "example": { "title": "Gọi lại khách DH2291", "project_id": "p1", "priority": "high", "status": "todo", "due_date": 1760000000000, "assignees": [ "emp-001" ] } } } } } }, "/v1/erp/tasks/inbox": { "get": { "operationId": "getErpTaskInbox", "summary": "Hộp việc của tôi", "description": "Kênh: `erp:task:listMyInbox`\n\n**Scope:** `erp:read`", "tags": [ "ERP" ], "parameters": [ { "name": "filter", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "today", "week", "overdue", "all" ], "default": "week" } } ], "x-scope": "erp:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/tasks/{id}": { "get": { "operationId": "getErpTask", "summary": "Chi tiết công việc", "description": "Kênh: `erp:task:get`\n\n**Scope:** `erp:read`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "updateErpTask", "summary": "Sửa công việc", "description": "Kênh: `erp:task:update`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } }, "delete": { "operationId": "deleteErpTask", "summary": "Xoá công việc", "description": "Kênh: `erp:task:delete`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/tasks/{id}/status": { "post": { "operationId": "setErpTaskStatus", "summary": "Đổi trạng thái công việc", "description": "Kênh: `erp:task:updateStatus`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "minLength": 1, "maxLength": 30 } }, "required": [ "status" ], "additionalProperties": false } } } } } }, "/v1/erp/tasks/{id}/assign": { "post": { "operationId": "assignErpTask", "summary": "Giao việc cho nhân viên", "description": "Kênh: `erp:task:assign`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "employee_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 100 } }, "required": [ "employee_ids" ], "additionalProperties": false } } } } } }, "/v1/erp/tasks/{id}/checklist": { "post": { "operationId": "addErpChecklistItem", "summary": "Thêm mục checklist", "description": "Kênh: `erp:task:addChecklist`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "content" ], "additionalProperties": false } } } } } }, "/v1/erp/checklist/{id}": { "patch": { "operationId": "toggleErpChecklistItem", "summary": "Đánh dấu xong/chưa xong mục checklist", "description": "Kênh: `erp:task:toggleChecklist`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "done": { "type": "boolean" } }, "required": [ "done" ], "additionalProperties": false } } } } } }, "/v1/erp/tasks/{id}/comments": { "post": { "operationId": "addErpTaskComment", "summary": "Bình luận vào công việc", "description": "Kênh: `erp:task:addComment`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 10000 }, "mentions": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 50, "default": [] } }, "required": [ "content" ], "additionalProperties": false } } } } } }, "/v1/erp/comments/{id}": { "patch": { "operationId": "editErpTaskComment", "summary": "Sửa bình luận", "description": "Kênh: `erp:task:editComment`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "content" ], "additionalProperties": false } } } } }, "delete": { "operationId": "deleteErpTaskComment", "summary": "Xoá bình luận", "description": "Kênh: `erp:task:deleteComment`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/tasks/{id}/watchers": { "post": { "operationId": "addErpTaskWatcher", "summary": "Theo dõi công việc", "description": "Kênh: `erp:task:addWatcher`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "employee_id": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } } } } } }, "/v1/erp/tasks/{id}/watchers/{employeeId}": { "delete": { "operationId": "removeErpTaskWatcher", "summary": "Bỏ theo dõi", "description": "Kênh: `erp:task:removeWatcher`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/tasks/{id}/dependencies": { "post": { "operationId": "addErpTaskDependency", "summary": "Thêm phụ thuộc", "description": "Kênh: `erp:task:addDependency`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "depends_on_id": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "depends_on_id" ], "additionalProperties": false } } } } } }, "/v1/erp/tasks/{id}/dependencies/{dependsOnId}": { "delete": { "operationId": "removeErpTaskDependency", "summary": "Bỏ phụ thuộc", "description": "Kênh: `erp:task:removeDependency`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "dependsOnId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/calendar/events": { "get": { "operationId": "listErpCalendarEvents", "summary": "Sự kiện lịch trong khoảng thời gian", "description": "Kênh: `erp:calendar:listEvents`\n\n**Scope:** `erp:read`", "tags": [ "ERP" ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 0 } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-scope": "erp:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createErpCalendarEvent", "summary": "Tạo sự kiện lịch", "description": "Kênh: `erp:calendar:createEvent`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "start_at": { "type": "integer", "minimum": 0 } }, "required": [ "title", "start_at" ] }, "example": { "title": "Hẹn khách xem nhà", "start_at": 1760000000000, "end_at": 1760003600000, "attendees": [ "emp-001" ] } } } } } }, "/v1/erp/calendar/events/{id}": { "patch": { "operationId": "updateErpCalendarEvent", "summary": "Sửa sự kiện", "description": "Kênh: `erp:calendar:updateEvent`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } }, "delete": { "operationId": "deleteErpCalendarEvent", "summary": "Xoá sự kiện", "description": "Kênh: `erp:calendar:deleteEvent`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/calendar/events/{id}/respond": { "post": { "operationId": "respondErpCalendarEvent", "summary": "Trả lời lời mời (accepted/declined/tentative)", "description": "Kênh: `erp:calendar:respond`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "minLength": 1, "maxLength": 20 } }, "required": [ "status" ], "additionalProperties": false } } } } } }, "/v1/erp/notes": { "get": { "operationId": "listErpNotes", "summary": "Ghi chú", "description": "Kênh: `erp:note:list`\n\n**Scope:** `erp:read`", "tags": [ "ERP" ], "parameters": [], "x-scope": "erp:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createErpNote", "summary": "Tạo ghi chú", "description": "Kênh: `erp:note:create`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 500 } } } } } } } }, "/v1/erp/notes/{id}": { "get": { "operationId": "getErpNote", "summary": "Một ghi chú", "description": "Kênh: `erp:note:get`\n\n**Scope:** `erp:read`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "updateErpNote", "summary": "Sửa ghi chú", "description": "Kênh: `erp:note:update`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } }, "delete": { "operationId": "deleteErpNote", "summary": "Xoá ghi chú", "description": "Kênh: `erp:note:delete`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/notes/{id}/pin": { "post": { "operationId": "pinErpNote", "summary": "Ghim / bỏ ghim ghi chú", "description": "Kênh: `erp:note:pin`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pinned": { "type": "boolean" } }, "required": [ "pinned" ], "additionalProperties": false } } } } } }, "/v1/erp/notes/{id}/versions": { "get": { "operationId": "listErpNoteVersions", "summary": "Lịch sử phiên bản ghi chú", "description": "Kênh: `erp:note:versions`\n\n**Scope:** `erp:read`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/note-folders": { "get": { "operationId": "listErpNoteFolders", "summary": "Thư mục ghi chú", "description": "Kênh: `erp:note:listFolders`\n\n**Scope:** `erp:read`", "tags": [ "ERP" ], "parameters": [], "x-scope": "erp:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/note-tags": { "get": { "operationId": "listErpNoteTags", "summary": "Tag ghi chú", "description": "Kênh: `erp:note:listTags`\n\n**Scope:** `erp:read`", "tags": [ "ERP" ], "parameters": [], "x-scope": "erp:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/notifications": { "get": { "operationId": "listErpNotifications", "summary": "Thông báo ERP", "description": "Kênh: `erp:notify:listInbox`\n\n**Scope:** `erp:read`", "tags": [ "ERP" ], "parameters": [], "x-scope": "erp:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/notifications/unread-count": { "get": { "operationId": "getErpUnreadCount", "summary": "Số thông báo chưa đọc", "description": "Kênh: `erp:notify:unreadCount`\n\n**Scope:** `erp:read`", "tags": [ "ERP" ], "parameters": [], "x-scope": "erp:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/notifications/read": { "post": { "operationId": "markErpNotificationsRead", "summary": "Đánh dấu đã đọc", "description": "Kênh: `erp:notify:markRead`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "maxItems": 1000 } }, "required": [ "ids" ], "additionalProperties": false } } } } } }, "/v1/erp/notifications/read-all": { "post": { "operationId": "markAllErpNotificationsRead", "summary": "Đánh dấu tất cả đã đọc", "description": "Kênh: `erp:notify:markAllRead`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/departments": { "get": { "operationId": "listErpDepartments", "summary": "Phòng ban", "description": "Kênh: `erp:department:list`\n\n**Scope:** `erp:read`", "tags": [ "ERP" ], "parameters": [], "x-scope": "erp:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createErpDepartment", "summary": "Tạo phòng ban", "description": "Kênh: `erp:department:create`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "name" ] } } } } } }, "/v1/erp/departments/{id}": { "patch": { "operationId": "updateErpDepartment", "summary": "Sửa phòng ban", "description": "Kênh: `erp:department:update`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } }, "delete": { "operationId": "deleteErpDepartment", "summary": "Xoá phòng ban", "description": "Kênh: `erp:department:delete`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/positions": { "get": { "operationId": "listErpPositions", "summary": "Chức vụ", "description": "Kênh: `erp:position:list`\n\n**Scope:** `erp:read`", "tags": [ "ERP" ], "parameters": [], "x-scope": "erp:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/profiles": { "get": { "operationId": "listErpProfiles", "summary": "Hồ sơ nhân sự (theo phòng ban)", "description": "Kênh: `erp:employee:listByDepartment`\n\n**Scope:** `erp:read`", "tags": [ "ERP" ], "parameters": [ { "name": "department_id", "in": "query", "required": false, "schema": { "type": "integer" } } ], "x-scope": "erp:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/profiles/{employeeId}": { "get": { "operationId": "getErpProfile", "summary": "Hồ sơ một nhân sự", "description": "Kênh: `erp:employee:getProfile`\n\n**Scope:** `erp:read`", "tags": [ "ERP" ], "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "erp:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/attendance": { "get": { "operationId": "listErpAttendance", "summary": "Bảng chấm công", "description": "Kênh: `erp:attendance:list`\n\n**Scope:** `erp:read`", "tags": [ "ERP" ], "parameters": [], "x-scope": "erp:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/leaves/pending": { "get": { "operationId": "listPendingErpLeaves", "summary": "Đơn nghỉ phép chờ duyệt", "description": "Kênh: `erp:leave:listPending`\n\n**Scope:** `erp:read`", "tags": [ "ERP" ], "parameters": [], "x-scope": "erp:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/erp/leaves/{id}/decide": { "post": { "operationId": "decideErpLeave", "summary": "Duyệt / từ chối đơn nghỉ", "description": "Kênh: `erp:leave:decide`\n\n**Scope:** `erp:write`", "tags": [ "ERP" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "erp:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "approved", "rejected" ] }, "note": { "type": "string", "maxLength": 1000 } }, "required": [ "status" ], "additionalProperties": false } } } } } }, "/v1/ai/assistants": { "get": { "operationId": "listAiAssistants", "summary": "Trợ lý AI (không trả API key)", "description": "**Scope:** `ai:manage`", "tags": [ "AI" ], "parameters": [], "x-scope": "ai:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/ai/assistants/{id}": { "get": { "operationId": "getAiAssistant", "summary": "Một trợ lý", "description": "**Scope:** `ai:manage`", "tags": [ "AI" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "ai:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/ai/assistants/options": { "get": { "operationId": "listAiAssistantOptions", "summary": "Trợ lý để chọn khi gọi /ai/chat (chỉ tên, nền tảng, model — không prompt, không key)", "description": "**Scope:** `ai:use`", "tags": [ "AI" ], "parameters": [], "x-scope": "ai:use", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/ai/default": { "get": { "operationId": "getDefaultAiAssistant", "summary": "Trợ lý mặc định", "description": "**Scope:** `ai:use`", "tags": [ "AI" ], "parameters": [], "x-scope": "ai:use", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/ai/chat": { "post": { "operationId": "aiChat", "summary": "Hỏi trợ lý AI (dùng cấu hình, tri thức và hạn mức của trợ lý)", "description": "**Scope:** `ai:use`", "tags": [ "AI" ], "parameters": [], "x-scope": "ai:use", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assistant_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Bỏ trống = trợ lý mặc định" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "content": { "type": "string", "maxLength": 100000 } }, "required": [ "role", "content" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 8000 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "raw_system": { "type": "boolean", "description": "true = chỉ gửi đúng messages (kể cả system) tới model, không ghép system prompt / tri thức của trợ lý — cho ứng dụng tự lo prompt" } }, "required": [ "messages" ], "additionalProperties": false }, "example": { "messages": [ { "role": "user", "content": "Tóm tắt chính sách đổi trả" } ] } } } } } }, "/v1/ai/suggest": { "post": { "operationId": "aiSuggestReply", "summary": "Gợi ý câu trả lời cho hội thoại (như nút gợi ý trong chat)", "description": "**Scope:** `ai:use`", "tags": [ "AI" ], "parameters": [], "x-scope": "ai:use", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "thread_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "assistant_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Bỏ trống = trợ lý gán cho tài khoản (vai trò gợi ý) hoặc mặc định" }, "history_limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, "required": [ "account_id", "thread_id" ], "additionalProperties": false } } } } } }, "/v1/ai/usage/stats": { "get": { "operationId": "getAiUsageStats", "summary": "Thống kê token theo ngày", "description": "**Scope:** `ai:manage`", "tags": [ "AI" ], "parameters": [ { "name": "assistant_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 365, "default": 30 } } ], "x-scope": "ai:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/ai/usage/logs": { "get": { "operationId": "getAiUsageLogs", "summary": "Nhật ký gọi AI", "description": "**Scope:** `ai:manage`", "tags": [ "AI" ], "parameters": [ { "name": "assistant_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "x-scope": "ai:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/ai-assistant": { "get": { "operationId": "getAccountAiAssistant", "summary": "Trợ lý gán cho tài khoản (gợi ý / panel)", "description": "**Scope:** `ai:use`", "tags": [ "AI" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." }, { "name": "role", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "suggestion", "panel" ], "default": "suggestion" } } ], "x-scope": "ai:use", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/analytics/{report}": { "get": { "operationId": "getAnalyticsReport", "summary": "Báo cáo (dashboard, message-volume, peak-hours, contact-growth, segmentation, campaign-comparison, friend-requests, workflows, ai, response-time, label-usage)", "description": "**Scope:** `analytics:read`", "tags": [ "Báo cáo" ], "parameters": [ { "name": "report", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "dashboard", "message-volume", "peak-hours", "contact-growth", "segmentation", "campaign-comparison", "friend-requests", "workflows", "ai", "response-time", "label-usage" ] } }, { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Bắt buộc với báo cáo theo tài khoản" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Epoch ms (mặc định 30 ngày trước)" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Epoch ms (mặc định bây giờ)" }, { "name": "granularity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "hour", "day" ], "default": "day" } }, { "name": "thread_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "user", "group" ] } } ], "x-scope": "analytics:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/media/uploads": { "post": { "operationId": "uploadMedia", "summary": "Upload file để gửi vào chat (trả upload_id, hết hạn sau 24 giờ)", "description": "Hai cách gửi:\n- Raw body: header `X-Filename: ten-file.pdf` (URL-encode nếu có dấu) + `Content-Type` của file. Ghi thẳng xuống đĩa.\n- `multipart/form-data` với trường `file`.\nupload_id chỉ key đã upload dùng được.\n\n**Scope:** `media:write`", "tags": [ "Media" ], "parameters": [], "x-scope": "media:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "upload_id": { "type": "string" }, "name": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "kind": { "type": "string" }, "expires_at": { "type": "integer" } }, "required": [ "upload_id", "name", "mime", "size", "kind", "expires_at" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "description": "Nội dung file (hoặc multipart/form-data trường file)", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ] } } } } } }, "/v1/media/uploads/{uploadId}": { "delete": { "operationId": "deleteUpload", "summary": "Xoá file đã upload (không đợi hết hạn)", "description": "**Scope:** `media:write`", "tags": [ "Media" ], "parameters": [ { "name": "uploadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "x-scope": "media:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/library/items": { "get": { "operationId": "listLibraryItems", "summary": "Item trong thư viện media của tài khoản", "description": "**Scope:** `media:read`", "tags": [ "Media" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "image", "video", "file", "audio" ], "default": "all" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "folder_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "-1 = chưa có thư mục" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "x-scope": "media:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "addLibraryItem", "summary": "Đưa file đã upload vào thư viện", "description": "**Scope:** `media:write`", "tags": [ "Media" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "media:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "upload_id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "maxLength": 200 }, "tags": { "type": "string", "maxLength": 500, "default": "" }, "folder_id": { "type": [ "integer", "null" ] } }, "required": [ "upload_id" ], "additionalProperties": false } } } } } }, "/v1/library/items/{uuid}": { "patch": { "operationId": "updateLibraryItem", "summary": "Đổi tên, tag, thư mục, yêu thích", "description": "**Scope:** `media:write`", "tags": [ "Media" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "x-scope": "media:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "tags": { "type": "string", "maxLength": 500 }, "folder_id": { "type": [ "integer", "null" ] }, "is_favorite": { "type": "boolean" }, "alt_text": { "type": "string", "maxLength": 500 } }, "additionalProperties": false } } } } }, "delete": { "operationId": "deleteLibraryItem", "summary": "Xoá item khỏi thư viện", "description": "**Scope:** `media:write`", "tags": [ "Media" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "x-scope": "media:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/library/items/{uuid}/file": { "get": { "operationId": "downloadLibraryItem", "summary": "Tải file của item", "description": "**Scope:** `media:read`", "tags": [ "Media" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "x-scope": "media:read", "responses": { "200": { "description": "Nội dung file", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/library/items/{uuid}/thumb": { "get": { "operationId": "downloadLibraryThumb", "summary": "Ảnh thu nhỏ của item", "description": "**Scope:** `media:read`", "tags": [ "Media" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "x-scope": "media:read", "responses": { "200": { "description": "Ảnh thu nhỏ", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/accounts/{accountId}/library/folders": { "get": { "operationId": "listLibraryFolders", "summary": "Thư mục thư viện", "description": "**Scope:** `media:read`", "tags": [ "Media" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 20 } } ], "x-scope": "media:read", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createLibraryFolder", "summary": "Tạo thư mục", "description": "**Scope:** `media:write`", "tags": [ "Media" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "ID tài khoản (accounts.zalo_id). Facebook dùng Facebook ID, Telegram dùng ID tài khoản Telegram." } ], "x-scope": "media:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "color": { "type": "string", "maxLength": 20 } }, "required": [ "name" ], "additionalProperties": false } } } } } }, "/v1/accounts/{accountId}/library/folders/{folderId}": { "patch": { "operationId": "renameLibraryFolder", "summary": "Đổi tên thư mục", "description": "**Scope:** `media:write`", "tags": [ "Media" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "folderId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "media:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "name" ], "additionalProperties": false } } } } }, "delete": { "operationId": "deleteLibraryFolder", "summary": "Xoá thư mục (file bên trong chuyển ra ngoài, không bị xoá)", "description": "**Scope:** `media:write`", "tags": [ "Media" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "folderId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-scope": "media:write", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/employees": { "get": { "operationId": "listEmployees", "summary": "Danh sách nhân viên", "description": "**Scope:** `employees:manage`", "tags": [ "Nhân viên" ], "parameters": [], "x-scope": "employees:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createEmployee", "summary": "Tạo nhân viên", "description": "**Scope:** `employees:manage`", "tags": [ "Nhân viên" ], "parameters": [], "x-scope": "employees:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "minLength": 3, "maxLength": 50, "pattern": "^[A-Za-z0-9_.-]+$" }, "password": { "type": "string", "minLength": 6, "maxLength": 200 }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "role": { "type": "string", "maxLength": 30, "default": "employee" } }, "required": [ "username", "password", "display_name" ], "additionalProperties": false } } } } } }, "/v1/employees/online": { "get": { "operationId": "listOnlineEmployees", "summary": "Nhân viên đang kết nối", "description": "**Scope:** `employees:manage`", "tags": [ "Nhân viên" ], "parameters": [], "x-scope": "employees:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/employees/{employeeId}": { "get": { "operationId": "getEmployee", "summary": "Một nhân viên kèm quyền và tài khoản được giao", "description": "**Scope:** `employees:manage`", "tags": [ "Nhân viên" ], "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "employees:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "updateEmployee", "summary": "Sửa nhân viên (tên, mật khẩu, bật/tắt)", "description": "**Scope:** `employees:manage`", "tags": [ "Nhân viên" ], "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "employees:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "password": { "type": "string", "minLength": 6, "maxLength": 200 }, "is_active": { "type": "boolean" }, "role": { "type": "string", "maxLength": 30 } }, "additionalProperties": false } } } } }, "delete": { "operationId": "deleteEmployee", "summary": "Xoá nhân viên", "description": "**Scope:** `employees:manage`", "tags": [ "Nhân viên" ], "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "employees:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/employees/{employeeId}/permissions": { "get": { "operationId": "getEmployeePermissions", "summary": "Quyền module của nhân viên", "description": "**Scope:** `employees:manage`", "tags": [ "Nhân viên" ], "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "employees:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "put": { "operationId": "setEmployeePermissions", "summary": "Đặt quyền module", "description": "**Scope:** `employees:manage`", "tags": [ "Nhân viên" ], "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "employees:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Module → true/false. Module: chat, friends, crm, workflow, integration, analytics, ai_assistant, settings, erp" } }, "required": [ "permissions" ], "additionalProperties": false } } } } } }, "/v1/employees/{employeeId}/accounts": { "get": { "operationId": "getEmployeeAccounts", "summary": "Tài khoản được giao", "description": "**Scope:** `employees:manage`", "tags": [ "Nhân viên" ], "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "employees:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "put": { "operationId": "setEmployeeAccounts", "summary": "Giao tài khoản cho nhân viên (ghi đè)", "description": "**Scope:** `employees:manage`", "tags": [ "Nhân viên" ], "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "employees:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 500 } }, "required": [ "account_ids" ], "additionalProperties": false } } } } } }, "/v1/employees/{employeeId}/sessions": { "get": { "operationId": "listEmployeeSessions", "summary": "Phiên đăng nhập gần đây", "description": "**Scope:** `employees:manage`", "tags": [ "Nhân viên" ], "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } } ], "x-scope": "employees:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/employees/{employeeId}/stats": { "get": { "operationId": "getEmployeeStats", "summary": "Thống kê làm việc (tin đã xử lý, thời gian online...)", "description": "**Scope:** `employees:manage`", "tags": [ "Nhân viên" ], "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "x-scope": "employees:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/employees/{employeeId}/kick": { "post": { "operationId": "kickEmployee", "summary": "Ngắt kết nối nhân viên đang online", "description": "Đóng phiên đang mở (REST + realtime) và thu hồi token hiện tại — nhân viên phải đăng nhập lại. Vô hiệu hoá, xoá hoặc đổi mật khẩu nhân viên cũng thu hồi phiên ngay.\n\n**Scope:** `employees:manage`", "tags": [ "Nhân viên" ], "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "employees:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/events/types": { "get": { "operationId": "listEventTypes", "summary": "Danh mục loại sự kiện", "description": "**Không cần API key.**", "tags": [ "Sự kiện" ], "parameters": [], "x-scope": null, "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [] } }, "/v1/events": { "get": { "operationId": "pollEvents", "summary": "Lấy sự kiện sau một mốc seq (polling)", "description": "Gọi lặp lại với `since = pagination.next_since`. Sự kiện được giữ 7 ngày / 50.000 bản ghi (đổi trong Cài đặt).\n\n**Scope:** `events:subscribe`", "tags": [ "Sự kiện" ], "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "seq cuối cùng đã nhận" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 } }, { "name": "types", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 50 }, "description": "Lọc loại sự kiện, vd: message.*,friend.request.received" }, { "name": "account_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 200 } } ], "x-scope": "events:subscribe", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/events/stream": { "get": { "operationId": "streamEvents", "summary": "Luồng sự kiện Server-Sent Events", "description": "Mỗi sự kiện: `id: `, `event: `, `data: `. Kết nối lại với header `Last-Event-ID` hoặc `?since=` để nhận phần bị lỡ. Comment `: ping` mỗi 15 giây.\n\n**Scope:** `events:subscribe`", "tags": [ "Sự kiện" ], "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "types", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 50 }, "description": "Lọc loại sự kiện, vd: message.*,friend.request.received" }, { "name": "account_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 200 } } ], "x-scope": "events:subscribe", "responses": { "200": { "description": "Luồng SSE", "content": { "text/event-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/webhooks": { "get": { "operationId": "listWebhooks", "summary": "Webhook của key này", "description": "**Scope:** `webhooks:manage`", "tags": [ "Webhook" ], "parameters": [], "x-scope": "webhooks:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createWebhook", "summary": "Đăng ký webhook (trả secret một lần)", "description": "Deplao POST sự kiện tới `url` kèm chữ ký `X-Deplao-Signature: v1=`. Xem hướng dẫn \"Webhook\".\n\nURL trong mạng nội bộ (localhost, 192.168.x, 10.x) chỉ được phép khi gọi từ chính máy chạy Deplao (không qua tunnel), hoặc khi bật cài đặt `api_allow_private_urls`.\n\n**Scope:** `webhooks:manage`", "tags": [ "Webhook" ], "parameters": [], "x-scope": "webhooks:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100, "default": "" }, "url": { "type": "string", "maxLength": 2000, "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 50, "default": [ "*" ] }, "account_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 200 }, "secret": { "type": "string", "minLength": 16, "maxLength": 200, "description": "Bỏ trống = Deplao tự sinh" } }, "required": [ "url" ], "additionalProperties": false }, "example": { "name": "CRM sync", "url": "https://crm.example.com/deplao", "events": [ "message.received", "friend.request.received" ] } } } } } }, "/v1/webhooks/{id}": { "get": { "operationId": "getWebhook", "summary": "Một webhook", "description": "**Scope:** `webhooks:manage`", "tags": [ "Webhook" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "webhooks:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "updateWebhook", "summary": "Sửa webhook / bật lại sau khi tự tắt", "description": "**Scope:** `webhooks:manage`", "tags": [ "Webhook" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "webhooks:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "url": { "type": "string", "maxLength": 2000, "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 50 }, "account_ids": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 200 }, "active": { "type": "boolean" } }, "additionalProperties": false } } } } }, "delete": { "operationId": "deleteWebhook", "summary": "Xoá webhook", "description": "**Scope:** `webhooks:manage`", "tags": [ "Webhook" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "webhooks:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "summary": "Gửi thử sự kiện \"ping\" ngay", "description": "**Scope:** `webhooks:manage`", "tags": [ "Webhook" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "webhooks:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "Lịch sử gửi gần nhất (mặc định 100, tối đa 500)", "description": "**Scope:** `webhooks:manage`", "tags": [ "Webhook" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "delivered", "failed" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "x-scope": "webhooks:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/webhook-deliveries/{id}/retry": { "post": { "operationId": "retryWebhookDelivery", "summary": "Gửi lại một lần gửi lỗi", "description": "**Scope:** `webhooks:manage`", "tags": [ "Webhook" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-scope": "webhooks:manage", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/plugins/{pluginId}/{path}": { "get": { "operationId": "pluginRouteGet", "summary": "Route do plugin cung cấp (GET)", "description": "Chạy route trong `contributes.routes` của plugin đang bật. Scope cần có theo khai báo của route; body tối đa 1 MB. Kết quả trả về là `body` plugin trả.\n\n**Cần API key** (scope bất kỳ).", "tags": [ "Plugin" ], "parameters": [ { "name": "pluginId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 } }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 1000, "default": "" } } ], "x-scope": "any", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "pluginRoutePost", "summary": "Route do plugin cung cấp (POST)", "description": "Chạy route trong `contributes.routes` của plugin đang bật. Scope cần có theo khai báo của route; body tối đa 1 MB. Kết quả trả về là `body` plugin trả.\n\n**Cần API key** (scope bất kỳ).", "tags": [ "Plugin" ], "parameters": [ { "name": "pluginId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 } }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 1000, "default": "" } } ], "x-scope": "any", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": {} } } } }, "put": { "operationId": "pluginRoutePut", "summary": "Route do plugin cung cấp (PUT)", "description": "Chạy route trong `contributes.routes` của plugin đang bật. Scope cần có theo khai báo của route; body tối đa 1 MB. Kết quả trả về là `body` plugin trả.\n\n**Cần API key** (scope bất kỳ).", "tags": [ "Plugin" ], "parameters": [ { "name": "pluginId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 } }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 1000, "default": "" } } ], "x-scope": "any", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": {} } } } }, "patch": { "operationId": "pluginRoutePatch", "summary": "Route do plugin cung cấp (PATCH)", "description": "Chạy route trong `contributes.routes` của plugin đang bật. Scope cần có theo khai báo của route; body tối đa 1 MB. Kết quả trả về là `body` plugin trả.\n\n**Cần API key** (scope bất kỳ).", "tags": [ "Plugin" ], "parameters": [ { "name": "pluginId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 } }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 1000, "default": "" } } ], "x-scope": "any", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": {} } } } }, "delete": { "operationId": "pluginRouteDelete", "summary": "Route do plugin cung cấp (DELETE)", "description": "Chạy route trong `contributes.routes` của plugin đang bật. Scope cần có theo khai báo của route; body tối đa 1 MB. Kết quả trả về là `body` plugin trả.\n\n**Cần API key** (scope bất kỳ).", "tags": [ "Plugin" ], "parameters": [ { "name": "pluginId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 } }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 1000, "default": "" } } ], "x-scope": "any", "responses": { "200": { "description": "Thành công", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Tham số không hợp lệ (VALIDATION_ERROR, INVALID_JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Thiếu hoặc sai API key (UNAUTHORIZED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Thiếu scope / không được cấp tài khoản / IP bị chặn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Không tìm thấy (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Tài khoản chưa kết nối (ACCOUNT_OFFLINE) hoặc xung đột", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Kênh không hỗ trợ thao tác (CHANNEL_UNSUPPORTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Vượt giới hạn tốc độ bạn đã đặt (RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Zalo/Facebook/Telegram trả lỗi (UPSTREAM_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "API đang tắt hoặc workspace không khả dụng", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "components": { "securitySchemes": { "BearerApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "dpk_…", "description": "Authorization: Bearer dpk_..." }, "HeaderApiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } }, "schemas": { "ErrorEnvelope": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED", "FORBIDDEN_SCOPE", "FORBIDDEN_ACCOUNT", "FORBIDDEN_IP", "FORBIDDEN_ERP", "NOT_FOUND", "METHOD_NOT_ALLOWED", "VALIDATION_ERROR", "INVALID_JSON", "PAYLOAD_TOO_LARGE", "CONFLICT", "ACCOUNT_OFFLINE", "CHANNEL_UNSUPPORTED", "RATE_LIMITED", "AUTH_BLOCKED", "UPSTREAM_ERROR", "NOT_IMPLEMENTED", "API_DISABLED", "TIMEOUT", "PLUGIN_ERROR", "PLUGIN_DISABLED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": {} } }, "request_id": { "type": "string" } } }, "Pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_offset": { "type": [ "integer", "null" ] }, "next_before": { "type": [ "integer", "null" ], "description": "Truyền vào `before` để lấy trang tin cũ hơn" }, "next_since": { "type": [ "integer", "null" ], "description": "Polling sự kiện: truyền vào `since` lần sau" } } } } }, "x-scopes": [ { "id": "accounts:read", "group": "Tài khoản", "label": "Xem danh sách tài khoản và trạng thái" }, { "id": "accounts:manage", "group": "Tài khoản", "label": "Kết nối, ngắt kết nối, đổi proxy" }, { "id": "chat:read", "group": "Chat", "label": "Đọc hội thoại, tin nhắn, nhãn, tin nhanh" }, { "id": "chat:send", "group": "Chat", "label": "Gửi tin, file, sticker, reaction, typing" }, { "id": "chat:manage", "group": "Chat", "label": "Đánh dấu đọc, thu hồi, ghim, gán nhãn, quản lý nhóm" }, { "id": "contacts:read", "group": "Danh bạ", "label": "Xem bạn bè, lời mời, tra cứu người dùng" }, { "id": "contacts:write", "group": "Danh bạ", "label": "Gửi/chấp nhận/từ chối lời mời, xoá bạn" }, { "id": "crm:read", "group": "CRM", "label": "Xem khách hàng, tag, ghi chú, chiến dịch" }, { "id": "crm:write", "group": "CRM", "label": "Sửa khách hàng, tag, ghi chú, chiến dịch" }, { "id": "campaigns:run", "group": "CRM", "label": "Chạy/dừng chiến dịch" }, { "id": "workflow:read", "group": "Workflow", "label": "Xem workflow và lịch sử chạy" }, { "id": "workflow:write", "group": "Workflow", "label": "Tạo, sửa, bật/tắt, xoá workflow" }, { "id": "workflow:run", "group": "Workflow", "label": "Chạy workflow, bắn sự kiện trigger.api" }, { "id": "integrations:read", "group": "Tích hợp", "label": "Xem tích hợp (không lộ credential)" }, { "id": "integrations:execute", "group": "Tích hợp", "label": "Gọi action của tích hợp (POS, vận chuyển...)" }, { "id": "integrations:manage", "group": "Tích hợp", "label": "Thêm, sửa credential, bật/tắt, xoá tích hợp" }, { "id": "erp:read", "group": "ERP", "label": "Xem công việc, dự án, lịch, ghi chú, nhân sự" }, { "id": "erp:write", "group": "ERP", "label": "Tạo/sửa công việc, dự án, lịch, ghi chú" }, { "id": "ai:use", "group": "AI", "label": "Chat với trợ lý AI, gợi ý trả lời" }, { "id": "ai:manage", "group": "AI", "label": "Quản lý trợ lý AI, xem thống kê sử dụng" }, { "id": "media:read", "group": "Media", "label": "Tải file đính kèm, thư viện media" }, { "id": "media:write", "group": "Media", "label": "Upload file, quản lý thư viện media" }, { "id": "analytics:read", "group": "Báo cáo", "label": "Xem báo cáo" }, { "id": "events:subscribe", "group": "Sự kiện", "label": "Nhận sự kiện realtime (Socket.IO, SSE, polling)" }, { "id": "webhooks:manage", "group": "Sự kiện", "label": "Quản lý webhook subscription của key này" }, { "id": "employees:manage", "group": "Quản trị", "label": "Quản lý nhân viên, quyền, phân tài khoản" }, { "id": "settings:read", "group": "Quản trị", "label": "Đọc cài đặt (danh sách cho phép)" }, { "id": "settings:write", "group": "Quản trị", "label": "Ghi cài đặt (danh sách cho phép)" }, { "id": "plugins:manage", "group": "Quản trị", "label": "Quản lý ứng dụng (plugin)" }, { "id": "admin", "group": "Quản trị", "label": "Toàn quyền (mọi scope ở trên)" } ], "x-error-codes": [ { "code": "UNAUTHORIZED", "status": 401, "description": "Thiếu key, key sai, key bị thu hồi hoặc hết hạn" }, { "code": "FORBIDDEN_SCOPE", "status": 403, "description": "Key thiếu scope cần cho endpoint" }, { "code": "FORBIDDEN_ACCOUNT", "status": 403, "description": "Key không được cấp tài khoản này" }, { "code": "FORBIDDEN_IP", "status": 403, "description": "IP gọi không nằm trong danh sách cho phép của key" }, { "code": "FORBIDDEN_ERP", "status": 403, "description": "Vai trò ERP của key không đủ quyền" }, { "code": "NOT_FOUND", "status": 404, "description": "Không tìm thấy endpoint hoặc dữ liệu" }, { "code": "METHOD_NOT_ALLOWED", "status": 405, "description": "Sai HTTP method" }, { "code": "VALIDATION_ERROR", "status": 400, "description": "Tham số không hợp lệ (xem details)" }, { "code": "INVALID_JSON", "status": 400, "description": "Body không phải JSON hợp lệ" }, { "code": "PAYLOAD_TOO_LARGE", "status": 413, "description": "Body vượt giới hạn" }, { "code": "CONFLICT", "status": 409, "description": "Xung đột trạng thái" }, { "code": "ACCOUNT_OFFLINE", "status": 409, "description": "Tài khoản chưa kết nối" }, { "code": "CHANNEL_UNSUPPORTED", "status": 422, "description": "Kênh của tài khoản không hỗ trợ thao tác này" }, { "code": "RATE_LIMITED", "status": 429, "description": "Vượt giới hạn tốc độ do bạn tự đặt cho key" }, { "code": "AUTH_BLOCKED", "status": 429, "description": "IP bị tạm chặn vì gửi quá nhiều key sai" }, { "code": "UPSTREAM_ERROR", "status": 502, "description": "Zalo/Facebook/Telegram hoặc handler nội bộ trả lỗi" }, { "code": "NOT_IMPLEMENTED", "status": 501, "description": "Thiếu kênh IPC tương ứng" }, { "code": "API_DISABLED", "status": 503, "description": "API đang tắt trong Cài đặt" }, { "code": "TIMEOUT", "status": 504, "description": "Xử lý quá thời gian cho phép" }, { "code": "PLUGIN_ERROR", "status": 502, "description": "Route/node của plugin trả lỗi" }, { "code": "PLUGIN_DISABLED", "status": 404, "description": "Plugin chưa cài hoặc đang tắt" }, { "code": "INTERNAL_ERROR", "status": 500, "description": "Lỗi không mong đợi" } ], "x-guides": [ { "id": "quickstart", "title": "Bắt đầu nhanh", "markdown": "## Bắt đầu nhanh (5 phút)\n\n1. Mở Deplao → **Công cụ → Ứng dụng, API & Webhook → API** → bật **API server** (cổng mặc định 9900).\n2. Bấm **Tạo API key**, đặt tên, chọn preset scope (ví dụ \"Chat bot\"), chọn tài khoản được phép. Copy key `dpk_...` — key chỉ hiện **một lần**.\n3. Thử key:\n\n```bash\ncurl -H \"Authorization: Bearer dpk_xxx\" http://127.0.0.1:9900/api/v1/me\n```\n\n4. Lấy danh sách tài khoản và hội thoại:\n\n```bash\ncurl -H \"Authorization: Bearer dpk_xxx\" http://127.0.0.1:9900/api/v1/accounts\ncurl -H \"Authorization: Bearer dpk_xxx\" \"http://127.0.0.1:9900/api/v1/accounts/0501234567/conversations?limit=20\"\n```\n\n5. Gửi một tin nhắn:\n\n```bash\ncurl -X POST -H \"Authorization: Bearer dpk_xxx\" -H \"Content-Type: application/json\" \\\n -d '{\"text\":\"Xin chào từ API\"}' \\\n http://127.0.0.1:9900/api/v1/accounts/0501234567/conversations/8899001122/messages\n```\n\nTin được gửi bằng đúng luồng của app: hiện trong khung chat, lưu DB, kích hoạt workflow và sự kiện như khi bạn tự gửi.\n\n### SDK\n- TypeScript: `npx openapi-typescript http://127.0.0.1:9900/api/v1/openapi.json -o deplao-api.d.ts` rồi dùng `openapi-fetch`.\n- Python: `openapi-python-client generate --url http://127.0.0.1:9900/api/v1/openapi.json`.\n- Postman/Insomnia: Import → Link → dán URL openapi.json." }, { "id": "authentication", "title": "Xác thực & quyền", "markdown": "## Xác thực & quyền\n\n### API key\n- Định dạng `dpk_` + 43 ký tự. Gửi qua `Authorization: Bearer dpk_...` hoặc `X-Api-Key: dpk_...`.\n- Deplao chỉ lưu SHA-256 của key. Mất key → thu hồi và tạo key mới.\n- Mỗi key có: **scope**, **tài khoản được phép** (bỏ trống = tất cả), **IP được phép** (IP hoặc CIDR, tuỳ chọn), **hạn dùng** (tuỳ chọn), **giới hạn tốc độ** (mặc định 0 = không giới hạn, bạn tự đặt nếu muốn), **vai trò ERP** (mặc định manager).\n\n### Scope\nXem danh sách đầy đủ ở `GET /api/v1/scopes`. Thiếu scope → `403 FORBIDDEN_SCOPE`. `admin` = mọi scope.\n\n| Preset | Dùng cho |\n| --- | --- |\n| Chỉ đọc | Báo cáo, đồng bộ dữ liệu sang hệ thống khác |\n| Chat bot | Bot trả lời tự động, nhận event, gửi tin/file |\n| Đồng bộ CRM | Đồng bộ khách hàng, tag, ghi chú |\n| Toàn quyền | Công cụ quản trị nội bộ — hạn chế dùng |\n\n### Tài khoản được phép\nKey bị giới hạn tài khoản sẽ nhận `403 FORBIDDEN_ACCOUNT` khi gọi tài khoản khác; danh sách `GET /accounts` chỉ trả tài khoản được phép; event và webhook cũng được lọc theo tài khoản.\n\n### Nhân viên\nToken đăng nhập của nhân viên (employee mode) cũng gọi được API v1. Quyền module của nhân viên được quy đổi thành scope (chat → chat:read/send/manage, crm → crm:*, ...), tài khoản = tài khoản được giao. Nhân viên không bị giới hạn tốc độ.\n\n### ERP\nCác route ERP chạy qua cùng kiểm tra quyền ERP của app. Key dùng vai trò ERP đã đặt (owner/admin/manager/member/guest); thiếu quyền → `403 FORBIDDEN_ERP`.\n\n### Chống dò key\nKhi bật \"Chống dò key\" (mặc định bật), một IP gửi từ 20 key sai trong 1 phút bị tạm chặn 10 phút (`429 AUTH_BLOCKED`). Request có key hợp lệ không bị ảnh hưởng." }, { "id": "conventions", "title": "Quy ước chung", "markdown": "## Quy ước chung\n\n### Envelope\nThành công:\n```json\n{ \"success\": true, \"data\": { }, \"pagination\": { \"limit\": 50, \"has_more\": true, \"next_before\": 1760000000000 }, \"request_id\": \"...\" }\n```\nLỗi:\n```json\n{ \"success\": false, \"error\": { \"code\": \"VALIDATION_ERROR\", \"message\": \"Tham số body không hợp lệ\", \"details\": [{ \"path\": \"body.text\", \"message\": \"Tối đa 10000 ký tự\" }] }, \"request_id\": \"...\" }\n```\nMỗi response có header `X-Request-Id` — gửi kèm khi báo lỗi.\n\n### Mã lỗi\n| HTTP | code | Ý nghĩa |\n| --- | --- | --- |\n| 400 | VALIDATION_ERROR, INVALID_JSON | Tham số sai |\n| 401 | UNAUTHORIZED | Thiếu/sai/thu hồi/hết hạn key |\n| 403 | FORBIDDEN_SCOPE, FORBIDDEN_ACCOUNT, FORBIDDEN_IP, FORBIDDEN_ERP | Không đủ quyền |\n| 404 | NOT_FOUND | Không có endpoint hoặc dữ liệu |\n| 409 | ACCOUNT_OFFLINE, CONFLICT | Tài khoản chưa kết nối / xung đột |\n| 413 | PAYLOAD_TOO_LARGE | Body/file quá lớn |\n| 422 | CHANNEL_UNSUPPORTED | Kênh không hỗ trợ thao tác |\n| 429 | RATE_LIMITED, AUTH_BLOCKED | Vượt giới hạn bạn đặt / IP bị tạm chặn |\n| 502 | UPSTREAM_ERROR | Zalo/Facebook/Telegram trả lỗi |\n| 503 | API_DISABLED, WORKSPACE_UNAVAILABLE | API tắt / máy đang mở workspace nhân viên |\n| 504 | TIMEOUT | Xử lý quá lâu |\n\n### Phân trang\n- Danh sách thường: `?limit=50&offset=0`, đọc `pagination.next_offset`.\n- Tin nhắn: mới → cũ, `?limit=50&before=`; trang sau dùng `pagination.next_before`. Tin cùng mốc thời gian có thể lặp ở ranh giới → khử trùng theo `msg_id`.\n\n### Dữ liệu\n- Thời gian: epoch **mili giây**.\n- Tên trường: `snake_case` theo cột DB. Cột JSON (attachments, reactions, quote) đã được parse.\n- Không trả cookie, session, mật khẩu, đường dẫn file trên máy.\n- ID tài khoản = `accounts.zalo_id` (Facebook: Facebook ID; Telegram: ID tài khoản Telegram).\n\n### Idempotency\nVới POST, gửi header `Idempotency-Key: `. Gọi lại cùng key trong 24 giờ trả nguyên kết quả cũ (header `Idempotent-Replayed: true`) thay vì gửi tin lần hai. Lỗi tạm thời (409, 429, 5xx) không được lưu để bạn retry.\n\n### Giới hạn\n- Body JSON tối đa 10 MB, file upload tối đa 100 MB (đổi trong Cài đặt).\n- Mặc định **không giới hạn tốc độ**. Bạn có thể đặt giới hạn cho từng key hoặc mặc định toàn cục.\n- Lời gọi được xếp hàng tối đa N việc đồng thời (mặc định 4) để app không bị giật; request không bị từ chối vì hàng đợi.\n- Gửi tin đi qua cùng hàng đợi gửi theo tài khoản như app để tài khoản Zalo không bị khoá do gửi dồn." }, { "id": "sending", "title": "Gửi tin nhắn & file", "markdown": "## Gửi tin nhắn & file\n\n`POST /api/v1/accounts/{accountId}/conversations/{threadId}/messages`\n\n| Trường | Kiểu | Ghi chú |\n| --- | --- | --- |\n| text | string | Văn bản (≤ 10000 ký tự) |\n| attachments | array | Tối đa 10 file, mỗi file một trong: upload_id, library_uuid, url |\n| sticker_id | string/number | Zalo, Telegram |\n| link | {url, text} | Zalo gửi thẻ link; kênh khác gửi văn bản |\n| quote_msg_id | string | Trả lời tin |\n| mentions | [{user_id, offset, length}] | Tag thành viên (Zalo, Telegram) |\n| thread_type | user/group | Bỏ trống = tự tra |\n\nThứ tự gửi: file → sticker → link → văn bản. Response liệt kê từng tin đã gửi kèm `msg_id` nếu kênh trả về.\n\n### Upload file trước\n```bash\n# Raw body (khuyên dùng cho file lớn — ghi thẳng xuống đĩa)\ncurl -X POST -H \"Authorization: Bearer dpk_xxx\" -H \"X-Filename: bao-gia.pdf\" \\\n --data-binary @bao-gia.pdf http://127.0.0.1:9900/api/v1/media/uploads\n\n# multipart/form-data\ncurl -X POST -H \"Authorization: Bearer dpk_xxx\" -F \"file=@anh.jpg\" http://127.0.0.1:9900/api/v1/media/uploads\n```\nKết quả có `upload_id` (hết hạn sau 24 giờ, chỉ key đã upload dùng được).\n\n### Gửi kèm file\n```json\n{ \"text\": \"Báo giá gửi anh\", \"attachments\": [{ \"upload_id\": \"upl_...\" }] }\n```\n- `url`: Deplao tự tải file từ link công khai (chặn link vào mạng nội bộ).\n- `library_uuid`: file trong Thư viện media của tài khoản.\n- Video Zalo được gửi như video xem được ngay (không phải file).\n\n### Lưu ý theo kênh\n| Thao tác | Zalo | Facebook | Telegram |\n| --- | --- | --- | --- |\n| Văn bản, ảnh, file | ✓ | ✓ | ✓ |\n| Video | ✓ (video thật) | ✓ | ✓ |\n| Sticker | ✓ | — | ✓ |\n| Sửa tin | — | ✓ | ✓ |\n| Thu hồi | ✓ | ✓ | ✓ (xoá) |\n| Reaction | ✓ (emoji hoặc mã HEART, LIKE…) | ✓ | ✓ |\n| Chuyển tiếp | văn bản, ảnh, video, file | + forward gốc | + forward gốc |" }, { "id": "remote-access", "title": "Truy cập từ xa & bảo mật", "markdown": "## Truy cập từ xa & bảo mật\n\nAPI chạy trên cổng relay (mặc định 9900). Để server/worker bên ngoài gọi được, cấu hình địa chỉ Internet ở **Cài đặt → Internet & Đám mây** (dịch vụ \"Nhân viên và API\"), chọn một cách tạo địa chỉ:\n\n1. **Cloudflare tự động (khuyên dùng)**: kết nối tài khoản Cloudflare của bạn ở đầu trang → chọn tên miền + \"Tên máy\" → Áp dụng. Deplao tự tạo tunnel và địa chỉ cố định trên tên miền của bạn; địa chỉ hiện ở bảng dịch vụ, gọi API tại `https://<địa-chỉ>/api/v1`.\n2. **ngrok**: dashboard.ngrok.com → Your Authtoken → dán vào ô Authtoken; mục Domains → lấy domain tĩnh miễn phí → dán vào ô Domain tĩnh; bật \"Nhân viên và API\". URL cố định: `https:///api/v1`.\n3. **Cloudflare thủ công** (đã tự cấu hình tunnel): one.dash.cloudflare.com → Networks → Tunnels → tạo tunnel (Cloudflared), sao chép token dán vào ô Tunnel token; thêm Public Hostname trỏ tới `http://localhost:9900`; nhập địa chỉ công khai rồi bật \"Nhân viên và API\". Token được lưu mã hoá.\n4. **Địa chỉ tạm**: không cần tài khoản, nhưng URL đổi mỗi lần khởi động lại — chỉ nên dùng thử.\n\n### Khuyến nghị khi mở ra Internet\n- Tạo key riêng cho từng hệ thống, scope tối thiểu, giới hạn tài khoản.\n- Đặt **IP được phép** nếu server gọi có IP cố định (IP thật được lấy từ header tunnel).\n- Webhook nhận ở phía bạn phải dùng https và kiểm tra chữ ký.\n- Trang `/docs` và `/api/v1/openapi.json` 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: tắt \"Tài liệu công khai\" ở tab Nâng cao.\n- Bật IP restriction / basic auth trên dashboard ngrok hoặc Cloudflare Access cho môi trường production.\n- **Lưu ý:** các endpoint file của chế độ nhân viên (`/api/media/*`, `/api/library/file|thumb/*`) bắt buộc phiên đăng nhập nhân viên (token của app nhân viên, chỉ trả file của tài khoản được giao) và không nhận API key. Hệ thống bên ngoài tải file qua API v1 (vd `GET /api/v1/library/items/{uuid}/file`) bằng key có scope phù hợp.\n\n### Công tắc khẩn cấp\n- Công cụ → Ứng dụng, API & Webhook → API → tắt **API** (trả 503 ngay, không ghi log/event).\n- **Thu hồi tất cả key** một chạm." }, { "id": "events", "title": "Sự kiện realtime", "markdown": "## Sự kiện realtime\n\nCó 4 cách nhận sự kiện, chọn theo nơi chạy code của bạn:\n\n| Cách | Phù hợp | Ghi chú |\n|---|---|---|\n| Socket.IO namespace `/v1` | App, worker giữ kết nối lâu | Nhanh nhất, có cả `conversation.typing` |\n| SSE `GET /api/v1/events/stream` | Script, server không cài được socket.io | Chạy tốt qua tunnel |\n| Polling `GET /api/v1/events?since=` | Cron, serverless, Google Apps Script | Không cần giữ kết nối |\n| Webhook | Server có URL công khai | Deplao chủ động POST, tự thử lại (xem hướng dẫn \"Webhook\") |\n\nKey cần scope `events:subscribe` (webhook cần `webhooks:manage`).\n\n### Cấu trúc một sự kiện\n\n```json\n{\n \"id\": \"evt_6b1f0c2d9a4e4c1b8f3a2d10\",\n \"seq\": 1532,\n \"type\": \"message.received\",\n \"ts\": 1760412345678,\n \"account_id\": \"0501234567\",\n \"channel\": \"zalo\",\n \"data\": {\n \"message\": { \"msg_id\": \"7712345678901\", \"thread_id\": \"8765432109876\", \"thread_type\": \"user\", \"text\": \"Shop ơi còn size M không?\", \"is_self\": false },\n \"conversation\": { \"thread_id\": \"8765432109876\", \"display_name\": \"Lan Nguyễn\" }\n }\n}\n```\n\n- `seq` tăng dần và là \"con trỏ\" để nhận tiếp phần bị lỡ. Hãy lưu `seq` cuối cùng đã xử lý.\n- `data.message` có cùng dạng với `GET .../messages`, nên một hàm xử lý dùng được cho cả hai.\n- `conversation.typing` không được lưu (`seq = 0`) và chỉ có trên Socket.IO và SSE.\n- Danh mục đầy đủ kèm mô tả: `GET /api/v1/events/types` (không cần key).\n\n### Quy tắc\n\n- Key chỉ nhận sự kiện của tài khoản được cấp. Sự kiện toàn hệ thống (`payment.received`, `plugin.*`, `ping`) chỉ gửi cho key không giới hạn tài khoản.\n- Lọc loại: `message.received` (đúng tên), `message.*` (cả nhóm), `*` (tất cả).\n- Deplao chỉ ghi sự kiện khi có nơi nhận: key có scope sự kiện/webhook, kết nối đang mở hoặc webhook đang bật. Sự kiện xảy ra trước khi bạn tạo key đầu tiên sẽ không có.\n- Tin cũ hơn 5 phút (đồng bộ lịch sử, tải tin cũ) không phát `message.received`.\n- Sự kiện được giữ 7 ngày hoặc 50.000 bản ghi gần nhất (đổi trong Công cụ → Ứng dụng, API & Webhook → API → Nâng cao).\n- Giao **ít nhất một lần**: khi kết nối lại có thể nhận trùng. Khử trùng bằng `id` hoặc `seq`.\n\n### Socket.IO (Node.js)\n\n```js\n// npm i socket.io-client@4\nimport { io } from 'socket.io-client';\nimport fs from 'node:fs';\n\nlet lastSeq = Number(fs.existsSync('seq.txt') ? fs.readFileSync('seq.txt', 'utf8') : 0);\nconst socket = io('http://127.0.0.1:9900/v1', {\n auth: { apiKey: process.env.DEPLAO_KEY },\n transports: ['websocket'],\n});\n\nsocket.on('hello', ({ seq_now }) => {\n // Lần đầu bắt đầu từ hiện tại; các lần sau nhận cả phần bị lỡ lúc mất kết nối.\n socket.emit('subscribe', { types: ['message.*'], since: lastSeq || seq_now }, (ack) => console.log('subscribed', ack));\n});\n\nsocket.on('event', (ev) => {\n if (ev.type === 'message.received') {\n console.log(ev.data.conversation.display_name, ':', ev.data.message.text);\n }\n if (ev.seq) {\n lastSeq = ev.seq;\n fs.writeFileSync('seq.txt', String(lastSeq));\n }\n});\n\nsocket.on('connect_error', (err) => console.error('Không kết nối được:', err.message));\n```\n\n- Lỗi kết nối trả qua `connect_error`: `UNAUTHORIZED` (sai key), `FORBIDDEN_SCOPE` (thiếu `events:subscribe`), `FORBIDDEN_IP`, `API_DISABLED`.\n- `subscribe` nhận `{ types, account_ids, since }`. Gọi lại `subscribe` để đổi bộ lọc; `unsubscribe` để dừng.\n- Qua tunnel: `io('https:///v1', ...)` (path mặc định `/socket.io`).\n\n### SSE\n\n```bash\ncurl -N -H \"Authorization: Bearer dpk_xxx\" \"http://127.0.0.1:9900/api/v1/events/stream?types=message.*&since=1500\"\n```\n\n```text\nid: 1532\nevent: message.received\ndata: {\"id\":\"evt_...\",\"seq\":1532,\"type\":\"message.received\",...}\n```\n\n- Kết nối lại với header `Last-Event-ID: ` hoặc `?since=` để nhận phần bị lỡ.\n- Cứ 15 giây có dòng `: ping` để giữ kết nối qua proxy và tunnel.\n- `EventSource` của trình duyệt không gửi được header `Authorization`. Trong trình duyệt hãy dùng Socket.IO.\n\nPython:\n\n```python\nimport json, requests\n\nr = requests.get(\n \"http://127.0.0.1:9900/api/v1/events/stream\",\n params={\"types\": \"message.received\"},\n headers={\"Authorization\": \"Bearer dpk_xxx\"},\n stream=True, timeout=(5, 60),\n)\nfor line in r.iter_lines(decode_unicode=True):\n if line and line.startswith(\"data: \"):\n ev = json.loads(line[6:])\n print(ev[\"seq\"], ev[\"data\"][\"message\"][\"text\"])\n```\n\n### Polling\n\n```bash\ncurl -H \"Authorization: Bearer dpk_xxx\" \"http://127.0.0.1:9900/api/v1/events?since=0&types=message.received&limit=100\"\n```\n\n```json\n{ \"success\": true, \"data\": [ { \"seq\": 1532, \"type\": \"message.received\" } ], \"pagination\": { \"limit\": 100, \"has_more\": false, \"next_since\": 1532 }, \"request_id\": \"...\" }\n```\n\nGọi lại với `since = pagination.next_since`. Khi `has_more = true` gọi tiếp ngay, khi `false` đợi vài giây." }, { "id": "webhooks", "title": "Webhook", "markdown": "## Webhook\n\nDeplao POST sự kiện tới URL của bạn ngay khi có. Bạn không cần giữ kết nối; Deplao tự thử lại khi server của bạn lỗi.\n\n### Đăng ký\n\n```bash\ncurl -X POST http://127.0.0.1:9900/api/v1/webhooks -H \"Authorization: Bearer dpk_xxx\" -H \"Content-Type: application/json\" -d '{\"name\":\"CRM sync\",\"url\":\"https://crm.example.com/deplao\",\"events\":[\"message.received\",\"payment.received\"]}'\n```\n\nKết quả có `secret` dạng `whsec_...`, **chỉ hiện một lần**. Lưu lại để kiểm tra chữ ký. Gửi thử: `POST /api/v1/webhooks/{id}/test`.\n\n### Deplao gửi gì\n\n```http\nPOST /deplao HTTP/1.1\nHost: crm.example.com\nContent-Type: application/json\nUser-Agent: Deplao-Webhook/1\nX-Deplao-Event: message.received\nX-Deplao-Delivery: dlv_3c9e5a0f6d2b4e7a9c1d8f20\nX-Deplao-Timestamp: 1760412345\nX-Deplao-Signature: v1=5d0c7f...e1\n\n{\"id\":\"evt_...\",\"seq\":1532,\"type\":\"message.received\",\"ts\":1760412345678,\"account_id\":\"0501234567\",\"channel\":\"zalo\",\"data\":{...}}\n```\n\n- Thành công là HTTP 2xx trong 10 giây. Hãy trả 200 ngay rồi xử lý sau (đưa vào hàng đợi).\n- Redirect (3xx) không được đi theo và bị tính là lỗi. Hãy đăng ký URL cuối cùng.\n- Thử lại sau 30 giây, 2 phút, 10 phút, 1 giờ, 6 giờ (tổng 6 lần), sau đó chuyển `failed`. Gửi lại tay: `POST /api/v1/webhook-deliveries/{id}/retry`.\n- 100 lần lỗi liên tiếp thì webhook tự tắt. Bật lại bằng `PATCH /api/v1/webhooks/{id}` với `{\"active\": true}`.\n- Có thể nhận trùng và sai thứ tự khi có thử lại. Khử trùng bằng header `X-Deplao-Delivery` hoặc `id`, sắp xếp bằng `seq`.\n- Webhook dùng quyền của key tạo ra nó: chỉ nhận sự kiện của tài khoản key được cấp; key bị thu hồi thì ngừng gửi.\n- URL nội bộ (`localhost`, `192.168.x`, `10.x`) chỉ được dùng khi tạo webhook từ chính máy chạy Deplao (không qua tunnel), hoặc khi bật `api_allow_private_urls`.\n\n### Kiểm tra chữ ký\n\nChữ ký là `v1=` + hex(HMAC-SHA256(secret, timestamp + \".\" + body gốc)). Luôn dùng **body gốc** (chưa parse JSON), so sánh an toàn thời gian, và từ chối timestamp lệch quá 5 phút.\n\nNode.js (Express):\n\n```js\nimport express from 'express';\nimport crypto from 'node:crypto';\n\nconst SECRET = process.env.DEPLAO_WEBHOOK_SECRET;\nconst app = express();\n\napp.post('/deplao', express.raw({ type: 'application/json' }), (req, res) => {\n const ts = req.get('X-Deplao-Timestamp') || '0';\n const sig = req.get('X-Deplao-Signature') || '';\n const expected = 'v1=' + crypto.createHmac('sha256', SECRET).update(ts + '.' + req.body.toString('utf8')).digest('hex');\n const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;\n const valid = sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));\n if (!fresh || !valid) return res.status(401).end();\n\n res.status(200).end(); // trả lời ngay\n const event = JSON.parse(req.body.toString('utf8'));\n console.log(event.type, event.seq); // xử lý sau, ví dụ đưa vào hàng đợi\n});\n\napp.listen(3000);\n```\n\nPython (Flask):\n\n```python\nimport hashlib, hmac, os, time\nfrom flask import Flask, abort, request\n\nSECRET = os.environ[\"DEPLAO_WEBHOOK_SECRET\"].encode()\napp = Flask(__name__)\n\n@app.post(\"/deplao\")\ndef deplao():\n ts = request.headers.get(\"X-Deplao-Timestamp\", \"0\")\n sig = request.headers.get(\"X-Deplao-Signature\", \"\")\n body = request.get_data() # bytes gốc\n expected = \"v1=\" + hmac.new(SECRET, ts.encode() + b\".\" + body, hashlib.sha256).hexdigest()\n if abs(time.time() - int(ts)) > 300 or not hmac.compare_digest(sig, expected):\n abort(401)\n event = request.get_json()\n print(event[\"type\"], event[\"seq\"])\n return \"\", 200\n```\n\nPHP:\n\n```php\n 300 || !hash_equals($expected, $sig)) {\n http_response_code(401);\n exit;\n}\n$event = json_decode($body, true);\nhttp_response_code(200);\n// xử lý $event['type'], $event['data']\n```\n\nCloudflare Worker (Web Crypto):\n\n```js\nexport default {\n async fetch(request, env) {\n const body = await request.text();\n const ts = request.headers.get('X-Deplao-Timestamp') || '0';\n const hex = (request.headers.get('X-Deplao-Signature') || '').replace('v1=', '');\n const enc = new TextEncoder();\n const key = await crypto.subtle.importKey('raw', enc.encode(env.DEPLAO_WEBHOOK_SECRET), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);\n const sig = new Uint8Array((hex.match(/../g) || []).map((h) => parseInt(h, 16)));\n const ok = await crypto.subtle.verify('HMAC', key, sig, enc.encode(ts + '.' + body));\n if (!ok || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return new Response('bad signature', { status: 401 });\n const event = JSON.parse(body);\n // ghi vào Queue / KV / D1 rồi xử lý sau\n return new Response('ok');\n },\n};\n```" }, { "id": "recipes", "title": "Công thức: n8n, Make, Apps Script, Worker", "markdown": "## Công thức tích hợp\n\n### n8n\n\n- **Gọi API:** node *HTTP Request* → Authentication *Generic Credential Type* → *Header Auth*, Name `Authorization`, Value `Bearer dpk_xxx`. URL dạng `https:///api/v1/...`.\n- **Nhận sự kiện:** node *Webhook* (POST), bật Options → *Raw Body*. Copy Production URL rồi đăng ký bằng `POST /api/v1/webhooks`. Kiểm tra chữ ký bằng node *Crypto* (HMAC, SHA256, hex) trên chuỗi `.`.\n- **Ví dụ:** đơn hàng mới (Webhook từ web bán hàng) → *HTTP Request* `POST /api/v1/accounts/{account_id}/conversations/{thread_id}/messages` với body `{\"text\": \"Cảm ơn bạn đã đặt đơn #{{$json.order_id}}\"}`.\n\n### Make (Integromat)\n\n- **Gọi API:** module *HTTP → Make a request*, header `Authorization: Bearer dpk_xxx`, Body type *Raw*, Content type *JSON (application/json)*.\n- **Nhận sự kiện:** *Webhooks → Custom webhook*, copy địa chỉ rồi đăng ký webhook Deplao với `events` cần thiết. Nếu kịch bản không tự kiểm tra chữ ký được, hãy giữ bí mật địa chỉ webhook (Make sinh địa chỉ ngẫu nhiên dài) và chỉ dùng HTTPS.\n\n### Google Apps Script / Google Sheets\n\nApps Script không đọc được header của request gửi đến (không kiểm tra được chữ ký) và trả 302 cho POST, nên **không dùng webhook**. Hãy dùng polling với trình kích hoạt theo thời gian (Triggers → Time-driven → mỗi phút):\n\n```js\nconst BASE = 'https:///api/v1';\n\nfunction pollDeplao() {\n const props = PropertiesService.getScriptProperties();\n const key = props.getProperty('DEPLAO_KEY');\n const since = Number(props.getProperty('since') || 0);\n const res = UrlFetchApp.fetch(BASE + '/events?types=message.received&limit=200&since=' + since, {\n headers: { Authorization: 'Bearer ' + key },\n muteHttpExceptions: true,\n });\n const body = JSON.parse(res.getContentText());\n if (!body.success) throw new Error(body.error.code + ': ' + body.error.message);\n const sheet = SpreadsheetApp.getActive().getSheetByName('Tin nhắn');\n body.data.forEach(function (ev) {\n const conv = ev.data.conversation || {};\n const msg = ev.data.message || {};\n sheet.appendRow([new Date(ev.ts), ev.account_id, conv.display_name, msg.text]);\n });\n props.setProperty('since', String(body.pagination.next_since));\n}\n```\n\n### Worker hoặc server riêng (gọi API)\n\n```js\nconst res = await fetch('https:///api/v1/accounts/0501234567/conversations/8765432109876/messages', {\n method: 'POST',\n headers: {\n Authorization: 'Bearer ' + process.env.DEPLAO_KEY,\n 'Content-Type': 'application/json',\n 'Idempotency-Key': 'order-1001-shipped', // gửi lại cùng key → không tạo tin trùng\n },\n body: JSON.stringify({ text: 'Đơn hàng #1001 đã giao cho shipper', thread_type: 'user' }),\n});\nconst out = await res.json();\nif (!out.success) console.error(out.error.code, out.error.message);\n```\n\n- `Idempotency-Key` được nhớ 24 giờ (cho tới khi app khởi động lại). Gửi lại cùng key trả nguyên kết quả lần đầu.\n- Nhóm chat: `\"thread_type\": \"group\"`.\n\n### Sinh SDK và công cụ\n\n```bash\nnpx @openapitools/openapi-generator-cli generate -i http://127.0.0.1:9900/api/v1/openapi.json -g typescript-fetch -o deplao-sdk\n```\n\n- Postman, Insomnia, Bruno: Import → URL `http://127.0.0.1:9900/api/v1/openapi.json`.\n- `openapi.json` mặc định xem được không cần key. Nếu đã tắt \"Tài liệu công khai\", thêm header `Authorization` khi import từ xa." }, { "id": "plugins", "title": "Ứng dụng (plugin): bắt đầu", "markdown": "## Ứng dụng (plugin): bắt đầu trong 10 phút\n\n> Trong giao diện Deplao, plugin hiển thị là **Ứng dụng** (Công cụ → Ứng dụng, API & Webhook). Tài liệu và mã nguồn giữ chữ *plugin*: file `deplao-plugin.json`, gói `@deplao/plugin-sdk`, lệnh `deplao-plugin`, endpoint `/api/v1/plugins`.\n\nPlugin là ứng dụng bất kỳ chạy ngay trong Deplao — công cụ nội bộ, kết nối hệ thống riêng, nghiệp vụ theo ngành… — với giao diện và công nghệ web tuỳ bạn chọn. Plugin có thể thêm trang riêng, panel trong màn chat, nút trong ô soạn tin, node workflow, route API, lịch chạy. Mọi thứ plugin làm với dữ liệu đều đi qua `deplao.*` — cùng API v1, cùng kiểm tra quyền như app ngoài.\n\n### 1. Tạo plugin\n\n```bash\nnode packages/plugin-cli/bin/deplao-plugin.js create my-shop --runtime web --id vn.acme.myshop --name \"My Shop\"\n```\n\n| Runtime | Khi nào dùng |\n|---|---|\n| `web` | Chỉ giao diện (trang, panel): mọi logic chạy trong iframe |\n| `local` | Có logic nền: node workflow, route, lịch chạy, xử lý sự kiện (chạy trong tiến trình riêng trên máy) |\n| `remote` | Logic nằm trên server của bạn; Deplao gọi qua HTTPS có chữ ký |\n\n### 2. Chạy thử ngay trong app\n\n**Công cụ → Ứng dụng, API & Webhook** (thanh điều hướng) → nút **Phát triển ứng dụng** → **Thêm thư mục đang phát triển** → chọn thư mục → duyệt quyền. Plugin hiện thành một ô trong danh sách **Ứng dụng đã cài**; bấm **Mở** để vào trang của plugin, bấm vào ô để xem chi tiết, cài đặt, nhật ký. Sửa file trong `backend/` thì plugin tự tải lại; sửa UI thì bấm nút tải lại trên đầu trang plugin.\n\n### 3. Gọi Deplao từ UI\n\n```html\n\n\n```\n\n```js\ndeplao.ready(async () => {\n const accounts = await deplao.accounts.listAccounts();\n const convs = await deplao.chat.listConversations({ accountId: accounts[0].id, limit: 10 });\n await deplao.chat.sendMessage({ accountId: accounts[0].id, threadId: convs[0].thread_id, text: 'Xin chào' });\n deplao.events.on('message.received', (ev) => console.log(ev.data.message.text));\n});\n```\n\n- Tên hàm = `operationId` của endpoint (xem danh sách endpoint ở trang này). Tham số phẳng: path + query (GET/DELETE) hoặc body (POST/PUT/PATCH).\n- Script inline bị CSP chặn: đặt code trong file `.js` riêng.\n- Giao diện tự do: CSS thuần, Tailwind, React, Vue, Svelte… build ra file tĩnh trong thư mục UI (script/CSS/font từ CDN bị CSP chặn — đóng gói kèm plugin).\n- Hợp theme sáng/tối của Deplao (tuỳ chọn): đọc `deplao.ui.theme()` / `deplao.ui.onTheme()`, hoặc dùng biến CSS `--dp-bg`, `--dp-surface`, `--dp-text`, `--dp-text-muted`, `--dp-accent`, `--dp-border`… SDK gắn sẵn lên trang.\n\n### 4. Đóng gói và cài\n\n```bash\nnode packages/plugin-cli/bin/deplao-plugin.js validate my-shop\nnode packages/plugin-cli/bin/deplao-plugin.js pack my-shop\n```\n\n**Công cụ → Ứng dụng, API & Webhook** → **Cài ứng dụng** (chọn file .zip). Cập nhật = cài file zip có `version` lớn hơn; quyền mới phải được duyệt lại.\n\nPlugin mẫu: `examples/plugins/hello-world` (web), `spa-booking` (local, gần đủ điểm mở rộng), `order-sync-remote` (remote)." }, { "id": "plugin-reference", "title": "Ứng dụng (plugin): tham chiếu", "markdown": "## Ứng dụng (plugin): tham chiếu\n\n### Manifest (`deplao-plugin.json`)\n\n| Trường | Bắt buộc | Quy tắc |\n|---|---|---|\n| `id` | có | reverse-DNS chữ thường (`vn.acme.spa`); phần cuối (`spa`) là tiền tố node, không trùng node có sẵn (`zalo`, `fb`, `trigger`…) |\n| `name`, `version` | có | `version` theo semver; cập nhật chỉ khi lớn hơn bản đã cài |\n| `apiVersion` | có | `1` |\n| `runtime` | có | `web`, `local` (cần `backend.entry`), `remote` (cần `remote.baseUrl` https) |\n| `permissions` | có | scope API (xem \"Xác thực & quyền\") + quyền plugin bên dưới. Không được xin `admin`, `plugins:manage`, `employees:manage`, `settings:write` |\n| `ui.entry` | khi có UI | file `.html` trong plugin; remote: URL cùng origin với `remote.baseUrl` |\n| `ui.connectSrc` | không | origin https UI được fetch trực tiếp (cần quyền `network`) |\n| `ui.imgSrc` | không | nguồn ảnh ngoài UI được hiển thị, `https://tên-miền` hoặc `https://*.tên-miền` (vd ảnh đại diện Zalo `https://*.zadn.vn`; cần quyền `network`) |\n| `minDeplaoVersion` | không | semver |\n| `contributes` | không | các điểm mở rộng bên dưới |\n\n### Quyền riêng của plugin\n\n| Quyền | Cho phép |\n|---|---|\n| `storage` | `deplao.storage` (tối đa 1 MB/giá trị, 20 MB/plugin) và thư mục dữ liệu riêng |\n| `ui:pages` | trang ở thanh điều hướng |\n| `ui:chat-panel` | panel bên phải màn chat, biết hội thoại đang mở |\n| `ui:composer` | nút trong ô soạn tin, `deplao.ui.insertComposerText` |\n| `ui:microphone` | micro trong giao diện ứng dụng (khung được gắn `allow=\"microphone\"`; thiếu quyền → trình duyệt chặn `getUserMedia`) |\n| `workflow:nodes` | node và trigger workflow, `deplao.workflow.trigger` |\n| `events:emit` | `deplao.events.emit` (tên khai báo trong `contributes.events`) |\n| `network` | `deplao.http.fetch` ở backend, `ui.connectSrc` |\n| `schedules` | `contributes.schedules` (cron) |\n| `cloudflare:workers` | `deplao.cloudflare` ở backend (runtime `local`): tạo / sửa Worker và D1 tên `` hoặc `-…` (tiền tố = phần cuối id) trên Cloudflare đã kết nối trong Deplao; token Cloudflare không đưa cho ứng dụng |\n\n### Điểm mở rộng (`contributes`)\n\n| Điểm | Khai báo | Ghi chú |\n|---|---|---|\n| `pages` | `{ id, title, path }` | `path` là hash route trong `ui.entry` |\n| `chatPanels` | `{ id, title, path, width }` | nhận `deplao.ui.context()` và `onContext` |\n| `composerButtons` | `{ id, title, icon, target: 'ui' \\| 'backend' }` | backend: `commands[id](context)` trả `{ insertText }` hoặc `{ toast }` |\n| `settings.schema` | JSON Schema (string, number, integer, boolean, enum; `x-secret`, `x-multiline`) | form tự sinh ở trang Ứng dụng, API & Webhook (bấm ô ứng dụng → Cài đặt); secret được mã hoá |\n| `workflowNodes` | `{ type: '.', label, configSchema, outputs }` | backend `nodes[type](cfg, run, ctx)`; `x-widget: account\\|thread\\|label\\|assistant` (assistant = chọn trợ lý AI của Deplao, lưu id; có lựa chọn \"Mặc định\" = để trống), `x-template` |\n| `triggers` | `{ type: '.trigger.', label, configSchema }` | bắn bằng `deplao.workflow.trigger(type, payload)`; trường payload dùng như `{{ $trigger. }}` |\n| `routes` | `{ method, path, scope }` | `/api/v1/plugins/`; người gọi cần `scope`; body ≤ 1 MB |\n| `schedules` | `{ id, cron, handler }` | gọi `handlers[handler]`; lượt trước chưa xong thì bỏ lượt sau |\n| `events` | `['booking.created']` | phát thành `plugin..booking.created` |\n\n### SDK `deplao.*`\n\n| Nhóm | Hàm |\n|---|---|\n| API v1 | `deplao..(params)`, `deplao.call(operationId, params)`, `deplao.api.request(method, path, { query, body })`. Hàm trả file (`downloadMessageMedia`, `downloadLibraryItem`, `downloadLibraryThumb`) trả `{ name, mime, size, base64 }` (≤ 25 MB, cần `media:read`; ghi âm Zalo chưa có trên máy thì app tự tải) |\n| `storage` | `get`, `set`, `delete`, `list(prefix)`; backend: `dataDir()` |\n| `settings` | `get()`, `onChange(cb)` |\n| `events` | `on(type, handler)` (cần `events:subscribe`), `emit(name, data)` |\n| `workflow` | `trigger(type, payload)` |\n| `media` | `upload(file)` → `upload_id` dùng trong `attachments` khi gửi tin (≤ 25 MB); các operationId nhóm Media gọi được như nhóm khác |\n| `log` | `debug/info/warn/error` → nhật ký plugin (trang Ứng dụng, API & Webhook → bấm ô ứng dụng → Nhật ký) |\n| `system` | `info()` |\n| `ui` (chỉ UI) | `context`, `onContext`, `theme`, `openConversation`, `insertComposerText`, `toast`, `navigate(pageId)`, `openExternal(url)`, `onCommand` |\n| `backend` (chỉ UI) | `call(name, params)` → `commands[name]` trong backend của chính plugin |\n| `http` (chỉ backend) | `fetch(url, init)` — cần `network`, chặn mạng nội bộ, ≤ 5 MB; trả `text` hoặc `base64` theo Content-Type (thiếu thì xem nội dung), `init.responseType` = `'text'` / `'base64'` để ép |\n| `cloudflare` (chỉ backend) | `status()`, `d1.ensure(name)`, `d1.migrate(name, dir)`, `d1.query(name, sql, params)`, `workers.get(name)`, `workers.deployBundle({ name, bundleDir, bindings, secrets, workersDev })` — cần `cloudflare:workers`; mỗi lời gọi tính vào ngân sách 100 request / 5 phút của app |\n\nLỗi trả về là `Error` có `code` (cùng mã lỗi API: `FORBIDDEN_SCOPE`, `FORBIDDEN_ACCOUNT`, `VALIDATION_ERROR`…) và `status`. `deplao.cloudflare` thêm `PLUGIN_PERMISSION`, `CF_NOT_CONNECTED`, `CF_PERMISSION`, `CF_NAME_FORBIDDEN`, `CF_BUNDLE_INVALID`, `CF_API`.\n\n### Backend (runtime `local`)\n\n```js\nmodule.exports = {\n async activate({ deplao, settings, pluginId, dataDir }) {},\n async deactivate() {}, // tối đa 5 giây\n async onUpgrade(prevVersion) {},\n async onSettingsChanged(settings) {},\n nodes: { 'shop.lookup': async (cfg, run, ctx) => ({ found: true }) }, // 60 giây\n routes: { 'GET /orders/:code': async (req, ctx) => ({ status: 200, body: {} }) }, // 30 giây\n handlers: { remind: async (ctx) => {} }, // lịch chạy, 120 giây\n commands: { book: async (params, ctx) => ({}) }, // UI backend.call, nút soạn tin\n};\n```\n\n- Chạy trong tiến trình riêng (utilityProcess, 256 MB heap), chỉ nhận vài biến môi trường; `require('electron')` và `process.exit` bị chặn; `console.*` vào nhật ký plugin.\n- Crash thì tự khởi động lại sau 2 s, 10 s, 60 s; lần thứ 4 plugin bị tắt (`Tắt do lỗi`). Không trả lời ping 3 lần liên tiếp thì bị khởi động lại.\n- Plugin vẫn là code Node chạy trên máy: Deplao chỉ cấp dữ liệu theo quyền đã duyệt, nhưng không cô lập hệ thống file hay mạng của tiến trình. Chỉ cài plugin từ nguồn tin cậy.\n\n### Runtime `remote`\n\n- Deplao gọi `POST {remote.baseUrl}/rpc` với body `{ id, method, params }` và header `X-Deplao-Plugin`, `X-Deplao-Timestamp`, `X-Deplao-Signature: v1=HMAC-SHA256(secret, timestamp + \".\" + body)`. Trả về `{ result }` hoặc `{ error: { code, message } }`.\n- `method`: `activate`, `deactivate`, `ping`, `node.execute`, `route.handle`, `schedule.run`, `composer.command`, `settings.changed`.\n- Khi cài, Deplao tạo **secret** và **API key** (gắn plugin, thu hồi khi gỡ) và hiện một lần. Server dùng key để gọi API v1, đăng ký webhook nhận sự kiện.\n- `baseUrl` phải là https (http chỉ cho `127.0.0.1` khi phát triển).\n\n### An toàn\n\n- UI plugin chạy ở origin riêng `deplao-plugin://` trong iframe sandbox (không popup, không điều hướng trang app, không đọc được DOM, store hay IPC của app); CSP chặn script ngoài, kết nối ra ngoài trừ `ui.connectSrc` và ảnh ngoài trừ `ui.imgSrc`.\n- Mọi lời gọi dữ liệu đi qua API v1 với principal `plugin:`: đúng scope, đúng tài khoản được cấp lúc cài, ghi nhật ký request như API key.\n- Gói zip được kiểm tra: tối đa 50 MB, giải nén tối đa 200 MB, không đường dẫn tuyệt đối hay `..`, không symlink, CRC khớp.\n- Kênh quản trị plugin (`plugins:*`) không gọi được qua API hay từ plugin. Kênh Cloudflare (`cloudflare:*`) cũng vậy, trừ `cloudflare:workers:*` khi ứng dụng có quyền `cloudflare:workers`: Deplao kiểm quyền + tiền tố tên trước khi gọi." } ] }