開發指南 - Jodoo - 開放平臺

簡介

Jodoo 包含以下 API：

規則

API 的統一造訪地址為：https://api.jodoo.com/api（非直接造訪 URL，結合後文 appid 等一起造訪）
所有 API 請求都必須透過 HTTPS 進行身份驗證和發起
統一採用 POST 請求的形式
資料傳輸編碼為 UTF-8
文件上傳API為 form_data 格式，其他均為 JSON 格式

頻率限制

全局最多接受請求：50 次/秒

各個 API 的請求頻率限制參見各個 API 的 API 文件：

鑑權方式

Jodoo 使用基於簡單令牌的身份驗證，API Key 預設未生成，需要點擊建立 API KEY 去生成。

生成方式：「開放平台 > 密鑰管理 > 建立 API Key」；一個企業最多生成 500 對 API Key。

對於已建立的 API Key 還可以進行啟用、停用和刪除。

開發文件中的「API 文件」是專門根據當前表單的配置生成的，可以點開查看詳細的說明。

查看方式：「開放平台 > 開發文件 > API 文件」。

透過 HTTP Headers 設定 Authorization 的值為"Bearer YOUR_APIKEY"來進行安全性驗證，

範例如下：

$ curl -i https://app.jodoo.com/api/v5/callback \
  -H "Authorization: Bearer YOUR_APIKEY"

錯誤對照表

所有 API 使用狀態碼+錯誤碼的回應方式來表示錯誤原因。API 正確統一返回 HTTP 狀態碼為 2xx 的正確回應。API錯誤則統一返回 HTTP 狀態碼為 400 的錯誤回應，同時回應內容會返回錯誤碼（code）和錯誤資訊（msg）

HTTP/1.1 400
Content-Type: application/json
{
  "code": 8303,
  "msg": "超出請求頻率限制",
}

狀態碼

狀態返回碼對照表如下：

狀態返回碼	說明
2xx	回應成功
400	API 錯誤統一返回
502	網關異常
579	文件上傳失敗

錯誤碼

當狀態返回碼為 400 時，伺服器會返回具體的錯誤碼（code）和錯誤資訊（msg），對照表如下：

錯誤碼	說明	排查建議
1	The request is invalid.	錯誤的請求，檢查參數是否缺失。
1005	The email already exists.	信箱已存在，可嘗試信箱驗證碼登入確認是否已註冊。
1010	The member doesn't exist.	使用者不存在，檢查成員參數是否正確傳入。
1017	The member's name is in an invalid format.	使用者名不符合格式要求，常規格式為字母數字下劃線任意組合，長度 50 個字符以內。
1018	The email is in an invalid format.	使用者信箱不符合格式要求，檢查郵件地址。
1019	The member's nickname is in an invalid format.	使用者暱稱不符合格式要求，檢查是否長度在 80 個字符以下且無特殊字符。
1022	The member's current company/team doesn't exist.	使用者團隊不存在，稍後重試，仍然出現可以諮詢技術支援。
1024	The mobile number is invalid. Enter a new number and try again.	手機號碼不正確，請重新輸入手機號。
1027	The phone number already exists.	手機號碼已存在，使用手機號驗證碼登入確認是否已註冊。
1058	Do not have permission to call the task list.	使用者操作權限不足。
1065	The member has already been added to the team.	當前使用者已加入團隊，檢查當前團隊內是否已經有當前使用者。
1082	The phone number/email is required.	手機號和信箱不能同時為空。
1085	The member's nickname is required.	暱稱不能為空。
1087	Duplicate unique fields.	唯一性欄位重複，檢查成員 ID 的重複情況。
1092	The length of the username has exceeded the limit.	工號長度超出限制，確認工號長度在 50 個字符以內。
1096	The request contains invalid member parameter(s).	使用者參數不合法，請檢查後重試。
1201	The role doesn't exist.	企業角色資訊不存在，檢查參數後重試。
1202	Unable to operate synchronized role or role groups	無法操作同步的角色/角色組，確認當前角色/角色組非其他平台同步而來。
1203	The role group/role information is invalid.	角色/角色組資訊不合法，檢查參數後重試。
1205	The role group is required.	必須指定角色組，檢查參數後重試。
1206	The role group doesn't exist.	指定的角色組不存在，檢查參數後重試。
1207	The length of the role group name has exceeded the limit.	角色/角色組名稱長度超限，確保長度在 24 個字符以內。
1208	Can't delete a role group with member(s).	非空角色組不能刪除，確保刪除角色組下角色後重試。
2004	The app doesn't exist.	應用不存在，檢查參數後重試。
3000	The form doesn't exist.	表單不存在，檢查參數後重試。
3001	The member or department name is required.	名稱不能為空。
3005	The request contains invalid parameter(s).	參數不正確。
3041	The number of Serial No. fields has exceeded the limit in the form.	單個表單流水號控件數量超出上限，有且只能有一個。
3042	Failed to verify the field alias.	欄位別名校驗失敗，檢查別名是否含有特殊字符，常規格式為字母數字下劃線任意組合。
3083	The number of widgets has exceeded the limit in the form.	控件數量超過上限，一般情況下這個值為 500。
3091	The number of characters in the form name exceeds 100.	表單名稱不能超過 100 個字符。
3092	The number of characters in the title exceeds 100.	標題不能超過 100 個字符。
4000	Failed to submit data.	資料送出失敗。
4001	Data doesn‘t exist.	資料不存在。
4007	No approver for the workflow.	操作失敗，沒有流程處理人。
4008	The workflow was closed.	操作失敗，流程已經關閉。
4009	Do not have permission to approve.	操作失敗，無權限。
4015	The approver of the transferred node is invalid.	操作失敗，當前節點不存在該候選人。
4016	The workflow can't be transferred to oneself.	操作失敗，流程不能轉交給自己。
4025	Do not have permission for the workflow.	您沒有資料流程權限。
4042	Failed to delete the data.	資料刪除失敗，檢查參數後重試。
4402	Failed to validate the aggregation calculation.	聚合計算校驗失敗，檢查參數後重試。
4815	The filter condition is invalid.	過濾條件設定有誤，可能是過濾條件過於冗長導致，可諮詢技術支援。
5003	The workflow node doesn't exist.	流程節點不存在。
5004	No comment for approval.	未送出流程簽核意見。
5009	The approver of the returned node is invalid.	找不到退回後的負責人。
5011	The target node is invalid.	找不到流轉節點。
5012	No signature for approval.	未送出流程手寫簽名。
5034	This node has child workflow(s)/plugin node(s).	目標節點包含子流程/外掛節點。
5044	The child workflow is wrongly configured. For example, no initiator for the child workflow.	子流程配置錯誤或找不到發起人。
5045	The number of child workflow exceeds 200.	發起子流程資料超過上限 200。
5049	The Transfer feature hasn't been enabled at this node.	當前流程節點未開啟轉交。
5053	The initial department is invalid. Can't flow to the node with multi-level approval.	流入多級主管簽核節點失敗，未指定發起部門。
6000	There is a sub-department with the same name within the same-level department.	已存在同名部門，檢查同級的父部門下所有子部門，排查同名情況。
6001	The parent department doesn't exist.	父部門不存在。
6002	The department doesn't exist.	部門不存在，檢查參數後重試。
6003	Can't delete a department with sub-department(s).	存在子部門，不能刪除。
6004	Failed to update the department.	部門修改失敗。
6005	Failed to create the department.	部門建立失敗，稍後重試，仍然出現可以諮詢技術支援。
6006	Can't delete a department with member(s).	部門內存在成員，不能刪除。
6010	The department ID is in an invalid format.	部門編號不在合法範圍內，結合自身部門路徑以及父部門，檢查參數後重試。
6011	There is a circular relationship among departments.	部門關係存在循環，不允許的部門樹關係，檢查參數後重試。
6012	The department name is invalid.	部門名稱不合法，檢查參數後重試。
6013	The department ID already exists.	部門編號重複，檢查同級的父部門下所有子部門，排查編號重複情況。
6014	There must be at least one sub-department belonging to the root department.	至少需要一個子部門屬於根部門。
6015	Can't delete a root department.	根部門不能被刪除。
6017	The number of cascade levels in the department exceeds the limit.	部門級聯層數超出限制，部門樹深度限制為 16。
6019	The member list is required.	成員列表不能為空，檢查參數後重試。
6020	The number of departments in a single import exceeds the limit.	單次匯入部門數量超出限制，上限為 10w。
6021	The number of members in a single import exceeds the limit.	單次匯入成員數量超出限制，上限為 2w。
6064	The parent department already exists.	已是目標部門的子部門。
7103	System usage exceeds the limit. The system has been suspended. Go to Management > Plan Details to view the usage details and upgrade plan to restore the system.	系統用量超出限制，系統已暫停使用。您可以至「企業管理-版本資訊」查看版本使用詳情和升級版本以恢復系統。
7212	Monthly data exceeds the limit. Can't submit new data. Contact the business owner to upgrade the plan.	該帳號的本月資料流量已用完，無法送出新資料，請聯繫帳號建立者升級版本。
7216	Attachment upload limit exceeded. Contact the link creator to enable cloud coin payment	附件上傳量超過當前版本限制，請聯繫連結發佈者開啟雲幣支付。
7217	Attachment upload limit exceeded. Contact the business owner to enable cloud coin payment.	附件上傳量超過當前版本限制，請聯繫企業建立者開啟雲幣支付。
7218	Attachment upload limit exceeded. Contact the link creator to purchase more cloud coins.	附件上傳量超過當前版本限制，請聯繫連接發佈者加值雲幣。
7219	Attachment upload limit exceeded. Contact the business owner to purchase more cloud coins.	附件上傳量超過當前版本限制，請聯繫企業建立者加值雲幣。
8017	Company/Team doesn't exist or has been closed.	企業不存在或者已經被解散，檢查參數後重試。
8301	Failed to verify the API key for authorization.	API 簽名校驗失敗，檢查參數後重試。
8302	Do not have permission for the API calls.	沒有 API 請求權限，檢查參數後重試。
8303	The call frequency of the company/team exceeds the frequency limit.	企業 API 請求次數達到頻率上限，可等待 1s 後重試，頻繁發生可以排查一下企業 API 請求佔用情況，或者新增頻率限制。
8304	The call frequency exceeds the frequency limit.	當前 API 請求次數達到頻率上限，可等待 1s 後重試當前 API，頻繁發生可以新增頻率限制。
9004	Failed to create the task.	隊列任務建立失敗，稍後重試，仍然出現可以諮詢技術支援。
9007	Failed to obtain the lock.	鎖取得失敗，稍後重試，仍然出現可以諮詢技術支援。
17017	The request contains invalid parameter(s).	平台 API 的參數異常，檢查參數後重試。
17018	The API key is invalid.	無效的 API Key。
17023	The batch update at one time exceeds the limit.	單次批次修改數量超出限制，上限為 100。
17024	The batch creation at one time exceeds the limit.	單次批次建立數量超出限制，上限為 100。
17025	The transaction_id contains invalid parameter(s).	transaction_id 參數格式不正確。
17026	The transaction_id already exists.	transaction_id 重複，請修改後重試。
17027	Failed to upload the API file.	API 文件上傳失敗，稍後重試，仍然出現可以諮詢技術支援。
17032	The field type isn't supported.	不支援的欄位類型，檢查參數後重試。
17034	The sub-field type isn't supported.	不支援的子表單欄位類型，檢查參數後重試。
17052	Not included in the IP whitelist.	不在 IP 白名單內，檢查對應 API Key 相關配置。
17053	Not among the authorized apps.	不在應用授權範圍內，檢查對應 API Key 相關配置。
17054	Not among the authorized APIs.	不在 API 授權範圍內，檢查對應 API Key 相關配置。
30002	Unable to retrieve the pre-set CRM form now.	CRM 預設表單暫不支援調用
50000	The target node doesn't exist.	目標節點不存在
50004	The task doesn't exist.	待辦任務不存在
50008	Workflow processing error.	流轉異常，稍後重試，仍然出現可以諮詢技術支援。
50011	The task doesn't exist.	執行實例不存在。
50014	No permission to close the task.	操作人不能為空。
50016	The instance_id is invalid.	流程實例不存在。
50019	The action is not supported.	不支援的簽核行為，檢查參數後重試。
50021	The data_id is invalid.	關聯業務對象不存在。
50031	The data_id is invalid.	流程資料不存在。
50040	This node can't be returned.	當前節點禁止退回，檢查節點配置並確認節點未在執行。
50041	Can't return to the current node.	退回節點為當前節點。
50047	Workflow being migrated. Try again later.	流程遷移中，請稍後再試。
50049	Can't return to the Start Node without an initiator.	不允許退回到沒有建立者的發起節點。
50051	The workflow has been approved/transferred/returned.	流程已被處理，請更新後查看。
50053	No approver to add.	加簽候選人列表不能為空，檢查參數後重試。
50054	Can't add nested approval. For example, after approver A has added approver B, approver B can't add approver C.	不支援嵌套加簽，檢查參數後重試。
50055	No pre-approver or post-approver was added.	僅支援前後加簽任務處理，檢查參數後重試。
50056	The parent task is lost. For example, approver A has added approver B. After approver B had approved the assigned task, the initial task for approver A was lost.	加簽父任務丟失，可能已經被處理，檢查參數後重試。
50057	The Add Approver feature hasn't been enabled.	加簽配置未開啟。
50059	The member has been added as an approver.	加簽候選人不能選擇節點負責人。
50060	The approver is invalid.	加簽候選人非法。
50061	Can't add more than one approver.	不支援多人加簽。
50062	The added approver is reviewing the task.	待被加簽人處理中。
50070	Can't return to the plugin node.	不允許退回到外掛節點。
50073	Can't return to the in-progress node.	禁止退回到進行中節點。