Giới thiệu
Trong Jodoo, API bao gồm App API, Form & Data API, Docs API, Workflow API và Contact API.
Lưu ý:
Bắt đầu từ phiên bản V2, Jodoo sẽ giới thiệu các tham số đầu vào và đầu ra mới (chưa từng giảm) đồng thời duy trì khả năng tương thích với các phiên bản trước đó. Các nhà phát triển cần lưu ý việc bổ sung tham số mới và đảm bảo tính ổn định của mã nguồn. Ví dụ, trong API bộ phận phiên bản 2, một tham số mới có tên "seq" đã được thêm nhưng không ảnh hưởng đến logic phiên bản 1. Dự kiến trong tương lai sẽ không cần tạo phiên bản mới khi cập nhật tương tự.
Quy định
-
URL truy cập API là https://api.jodoo.com/api. Lưu ý: Đây không phải URL trực tiếp và cần sử dụng kèm các tham số như "appid".
-
Tất cả các yêu cầu API đều phải xác thực và thực hiện qua giao thức HTTPS.
-
Tất cả yêu cầu phải được gửi bằng phương thức POST.
-
Dữ liệu truyền phải mã hóa UTF-8.
-
Nên sử dụng định dạng form_data cho API tải file và JSON cho các trường hợp còn lại.
Giới hạn tốc độ (Rate Limit)
Tốc độ tối đa chấp nhận: 50 yêu cầu/giây toàn hệ thống.
Tốc độ giới hạn theo từng API được ghi rõ trong tài liệu API tương ứng.
Phương thức xác thực
Jodoo sử dụng phương thức xác thực đơn giản dựa trên token. Mặc định, API Key chưa được tạo, cần bấm Tạo API Key để sinh key.
Các bước thực hiện: Nền tảng mở (Open Platform) > API Key > Tạo API Key. Một công ty có thể tạo tối đa 500 API key.
Bạn có thể bật, tắt hoặc xóa các API key đã tạo.
Trên trang Hướng dẫn, nhấp API Docs để truy cập tài liệu API theo nhu cầu.
Sử dụng HTTP Header để đặt giá trị Authorization dạng "Bearer YOUR_APIKEY" cho xác thực bảo mật.
Ví dụ:
Unknown block type: codeTham chiếu lỗi
Tất cả API sử dụng định dạng trả về "code + thông báo lỗi" để chỉ ra lý do lỗi. API trả mã HTTP "2xx" cho yêu cầu thành công. Trường hợp lỗi trả mã HTTP "400" kèm trong nội dung phản hồi mã lỗi ("code") và thông báo lỗi ("msg") chi tiết.
Unknown block type: codeMã trạng thái (Status Code)
Dưới đây là tham chiếu các mã trạng thái:
| Mã trạng thái | Ý nghĩa |
|---|---|
| 2xx | Thành công |
| 400 | Yêu cầu sai |
| 502 | Gateway lỗi |
| 579 | Tải file thất bại |
Mã lỗi (Error Code)
Nếu mã trạng thái là 400, máy chủ trả mã lỗi ("code") và thông báo lỗi ("msg"). Chi tiết mã lỗi như sau:
| Mã lỗi | Thông báo | Mô tả |
|---|---|---|
| 1 | Yêu cầu không hợp lệ | Yêu cầu không hợp lệ. |
| 1005 | Email trùng | Email đã tồn tại. |
| 1010 | Thành viên không tồn tại | Thành viên không tồn tại. |
| 1017 | Tên thành viên không hợp lệ | Tên thành viên có định dạng không hợp lệ. |
| 1018 | Email không hợp lệ | Email có định dạng không hợp lệ. |
| 1019 | Bí danh thành viên không hợp lệ | Bí danh của thành viên không hợp lệ. |
| 1022 | Công ty/Đội không hợp lệ | Công ty hoặc đội không tồn tại. |
| 1024 | Số điện thoại di động không hợp lệ | Số điện thoại di động không hợp lệ, vui lòng nhập lại. |
| 1027 | Số điện thoại trùng | Số điện thoại đã tồn tại. |
| 1058 | Không có quyền | Không có quyền gọi danh sách tác vụ. |
| 1065 | Thành viên trùng | Thành viên đã được thêm vào nhóm. |
| 1082 | Cần số điện thoại hoặc email | Bắt buộc phải cung cấp số điện thoại hoặc email. |
| 1085 | Cần bí danh | Bắt buộc phải cung cấp bí danh thành viên. |
| 1087 | Trùng trường duy nhất | Trùng các trường yêu cầu duy nhất. |
| 1092 | Giới hạn độ dài tên đăng nhập | Độ dài tên đăng nhập vượt quá giới hạn. |
| 1096 | Tham số thành viên không hợp lệ | Tham số thành viên có lỗi. |
| 1201 | Vai trò không hợp lệ | Vai trò không tồn tại. |
| 1203 | Nhóm vai trò/vai trò không hợp lệ | Thông tin nhóm vai trò hoặc vai trò không hợp lệ. |
| 1205 | Cần nhóm vai trò | Bắt buộc phải có nhóm vai trò. |
| 1206 | Nhóm vai trò không hợp lệ | Nhóm vai trò không tồn tại. |
| 1207 | Giới hạn độ dài tên nhóm vai trò | Độ dài tên nhóm vai trò vượt quá giới hạn. |
| 1208 | Nhóm vai trò có thành viên | Không thể xóa nhóm vai trò đang có thành viên. |
| 2004 | Ứng dụng không hợp lệ | Ứng dụng không tồn tại. |
| 3000 | Biểu mẫu không hợp lệ | Biểu mẫu không tồn tại. |
| 3001 | Cần tên | Bắt buộc phải có tên thành viên hoặc bộ phận. |
| 3005 | Tham số không hợp lệ | Tham số yêu cầu không hợp lệ. |
| 3041 | Vượt giới hạn số Serial No. | Số lượng trường Serial No. vượt giới hạn biểu mẫu. |
| 3042 | Alias trường không hợp lệ | Kiểm tra alias trường thất bại. |
| 3083 | Vượt giới hạn widget | Số lượng widget vượt giới hạn biểu mẫu. |
| 3091 | Giới hạn độ dài tên biểu mẫu | Độ dài tên biểu mẫu vượt quá 100 ký tự. |
| 3092 | Giới hạn độ dài tiêu đề | Độ dài tiêu đề vượt quá 100 ký tự. |
| 4000 | Thất bại gửi dữ liệu | Gửi dữ liệu thất bại. |
| 4001 | Dữ liệu không hợp lệ | Dữ liệu không tồn tại. |
| 4007 | Thiếu người phê duyệt | Không có người phê duyệt workflow. |
| 4008 | Workflow đã đóng | Workflow đã được đóng. |
| 4009 | Không có quyền | Không có quyền phê duyệt. |
| 4015 | Người phê duyệt không hợp lệ | Người phê duyệt của node được chuyển giao không hợp lệ. |
| 4016 | Thao tác thất bại | Workflow không thể chuyển giao cho chính mình. |
| 4025 | Không có quyền | Không có quyền với workflow. |
| 4042 | Thất bại xoá dữ liệu | Xoá dữ liệu thất bại. |
| 4402 | Kiểm tra tổng hợp thất bại | Xác thực phép tính tổng hợp thất bại. |
| 4815 | Bộ lọc không hợp lệ | Điều kiện bộ lọc không hợp lệ. |
| 5003 | Node không hợp lệ | Node workflow không tồn tại. |
| 5004 | Thiếu bình luận phê duyệt | Thiếu bình luận phê duyệt. |
| 5009 | Người phê duyệt không hợp lệ | Người phê duyệt node trả không hợp lệ. |
| 5011 | Node không hợp lệ | Node mục tiêu không hợp lệ. |
| 5012 | Thiếu chữ ký | Không có chữ ký phê duyệt. |
| 5034 | Tồn tại workflow/con node con | Node này có workflow con hoặc node plugin con. |
| 5044 | Lỗi workflow con | Workflow con cấu hình sai, ví dụ thiếu người khởi tạo workflow con. |
| 5045 | Vượt giới hạn workflow con | Số lượng workflow con vượt 200. |
| 5049 | Chuyển giao bị vô hiệu hoá | Chức năng Transfer chưa bật tại node này. |
| 5053 | Thao tác thất bại | Bộ phận ban đầu không hợp lệ, không thể flow tới node phê duyệt đa cấp. |
| 6000 | Trùng tên phòng ban con | Tồn tại phòng ban con trùng tên trong cùng cấp. |
| 6001 | Phòng ban cha không hợp lệ | Phòng ban cha không tồn tại. |
| 6002 | Phòng ban không hợp lệ | Phòng ban không tồn tại. |
| 6003 | Phòng ban có phòng ban con | Không thể xóa phòng ban đang có phòng ban con. |
| 6004 | Thất bại cập nhật phòng ban | Cập nhật phòng ban thất bại. |
| 6005 | Thất bại tạo phòng ban | Tạo phòng ban thất bại. |
| 6006 | Phòng ban có thành viên | Không thể xóa phòng ban đang có thành viên. |
| 6010 | ID phòng ban không hợp lệ | ID phòng ban có định dạng không hợp lệ. |
| 6011 | Mối quan hệ vòng phòng ban | Tồn tại vòng quan hệ giữa các phòng ban. |
| 6012 | Tên phòng ban không hợp lệ | Tên phòng ban không hợp lệ. |
| 6013 | Trùng ID phòng ban | ID phòng ban đã tồn tại. |
| 6014 | Không có phòng ban con thuộc phòng ban gốc | Phải có tối thiểu một phòng ban con thuộc phòng ban gốc. |
| 6015 | Phòng ban gốc | Không thể xóa phòng ban gốc. |
| 6017 | Vượt giới hạn số cấp phòng ban | Số cấp phòng ban vượt giới hạn. |
| 6019 | Yêu cầu danh sách thành viên | Danh sách thành viên là bắt buộc. |
| 6020 | Vượt giới hạn số phòng ban nhập khẩu | Số lượng phòng ban trong một lần nhập vượt giới hạn. |
| 6021 | Vượt giới hạn số thành viên nhập khẩu | Số lượng thành viên trong một lần nhập vượt giới hạn. |
| 6064 | Trùng phòng ban cha | Phòng ban cha đã tồn tại. |
| 7103 | Vượt giới hạn hệ thống | Sử dụng hệ thống vượt giới hạn dẫn đến tạm ngưng hệ thống. Vào Quản lý > Chi tiết gói để xem chi tiết và nâng cấp gói dùng. |
| 7212 | Vượt giới hạn dữ liệu tháng | Dữ liệu tháng vượt giới hạn, không thể gửi thêm. Liên hệ chủ doanh nghiệp để nâng cấp gói. |
| 7216 | Vượt giới hạn tải tệp đính kèm | Giới hạn tải tệp đính kèm vượt giới hạn. Liên hệ người tạo liên kết để sửa. |
| 7217 | Vượt giới hạn tải tệp đính kèm | Giới hạn tải tệp đính kèm vượt giới hạn. Liên hệ chủ doanh nghiệp để sửa. |
| 7218 | Vượt giới hạn tải tệp đính kèm | Giới hạn tải tệp đính kèm vượt giới hạn. Liên hệ người tạo liên kết để sửa. |
| 7219 | Vượt giới hạn tải tệp đính kèm | Giới hạn tải tệp đính kèm vượt giới hạn. Liên hệ chủ doanh nghiệp để sửa. |
| 8017 | Công ty/Đội không hợp lệ | Công ty/Đội không tồn tại hoặc đã đóng. |
| 8301 | Xác thực không hợp lệ | Kiểm tra API key xác thực thất bại. |
| 8302 | Không có quyền | Không có quyền gọi API. |
| 8303 | Vượt giới hạn tần suất Công ty/Đội | Tần suất gọi API của công ty/đội vượt giới hạn. |
| 8304 | Vượt giới hạn tần suất | Tần suất gọi API vượt giới hạn. |
| 9004 | Thất bại tạo tác vụ | Tạo tác vụ thất bại. |
| 9007 | Thất bại lấy khóa (Lock) | Lấy khóa thất bại. |
| 17017 | Tham số không hợp lệ | Yêu cầu có tham số không hợp lệ. |
| 17018 | API Key không hợp lệ | API Key không hợp lệ. |
| 17023 | Vượt giới hạn cập nhật hàng loạt | Cập nhật hàng loạt một lần vượt giới hạn. |
| 17024 | Vượt giới hạn tạo hàng loạt | Tạo hàng loạt một lần vượt giới hạn. |
| 17025 | Tham số transaction_id không hợp lệ | Transaction_id có tham số không hợp lệ. |
| 17026 | Trùng transaction_id | Transaction_id đã tồn tại. |
| 17027 | Thất bại tải lên | Tải file API thất bại. |
| 17032 | Loại trường không hợp lệ | Loại trường chưa được hỗ trợ. |
| 17034 | Loại trường con không hợp lệ | Loại trường con chưa được hỗ trợ. |
| 50000 | Node không hợp lệ | Node mục tiêu không tồn tại. |
| 50004 | Tác vụ không hợp lệ | Tác vụ không tồn tại. |
| 50008 | Thao tác thất bại | Lỗi xử lý workflow. |
| 50011 | Tác vụ không hợp lệ | Tác vụ không tồn tại. |
| 50014 | Người phê duyệt không hợp lệ | Không có quyền đóng tác vụ. |
| 50016 | Instance_id không hợp lệ | Instance_id không hợp lệ. |
| 50019 | Hành động không hợp lệ | Hành động không được hỗ trợ. |
| 50021 | Data_id không hợp lệ | Data_id không hợp lệ. |
| 50031 | Data_id không hợp lệ | Data_id không hợp lệ. |
| 50040 | Thất bại trả về | Không thể trả về node này. |
| 50041 | Thất bại trả về | Không thể trả về node hiện tại. |
| 50047 | Workflow đang di chuyển | Workflow đang được di chuyển, thử lại sau. |
| 50049 | Thất bại trả về | Không thể trả về node Bắt đầu khi không có người khởi tạo. |
| 50051 | Yêu cầu trùng | Workflow đã được phê duyệt, chuyển giao hoặc trả về. |
| 50053 | Người phê duyệt không hợp lệ | Không có người phê duyệt để thêm. |
| 50054 | Không cho phép lồng nhau | Không thể thêm phê duyệt lồng nhau. Ví dụ, người phê duyệt A thêm B, B không thể thêm C. |
| 50055 | Thao tác thất bại | Chưa thêm người phê duyệt trước hoặc sau. |
| 50056 | Task cha không hợp lệ | Task cha bị mất, ví dụ A thêm B, sau khi B phê duyệt thì task ban đầu A bị mất. |
| 50057 | Chức năng thêm người phê duyệt bị vô hiệu hoá | Chức năng Add Approver chưa được bật. |
| 50059 | Đã thêm người phê duyệt | Thành viên đã được thêm làm người phê duyệt. |
| 50060 | Người phê duyệt không hợp lệ | Người phê duyệt không hợp lệ. |
| 50061 | Vượt giới hạn người phê duyệt | Không thể thêm quá một người phê duyệt. |
| 50062 | Người phê duyệt được thêm đang xét duyệt | Người phê duyệt được thêm đang trong trạng thái xét duyệt. |
| 50070 | Thất bại trả về | Không thể trả về node plugin. |
| 50073 | Thất bại trả về | Không thể trả về node đang trong tiến trình. |
