Ragic HTTP API (3.0)

Ragic HTTP API 是 REST 風格的介面，可讓您讀取、建立、更新和刪除任何 Ragic 表單上的資料。您可以使用任何 HTTP 用戶端工具，包括 cURL、Postman 或您所使用程式語言的 HTTP 函式庫。

Ragic 的REST API 讓你可以查詢在 Ragic 的資料，或是透過程式新增、更新或刪除資料，從而與其他應用程式整合。 由於這個 API 是基於 REST 原則，因此編寫和運用非常容易。你可以使用瀏覽器訪問 URL，並且可以使用任何程式語言中的任何 HTTP 用戶端與 API 互動。 HTTP 請求可以用兩種內容類型發出，表單資料和 JSON。但是，上傳檔案只能透過表單資料的選項。

您可以輕鬆地在瀏覽器中輸入 API 端點 URL 來測試大多數的 GET API。例如，您可以嘗試以下 URL 來訪問 Ragic 範例中的客戶資訊：

https://www.ragic.com/demo/sales/1?api

請注意，根據您的 Ragic 帳號的 URL，您可能需要將 URL 中的 www 修改為 na3 、ap5 或 eu2 等。 但在瀏覽器中創建 POST 方法請求並不那麼容易，因此建議使用 cURL 的工具來建立所有類型的 HTTP 請求以測試我們的 API。文件中也會使用 cURL 命令作為 API 調用的範例，但您也可以使用任何您熟悉的工具來建立 HTTP 請求並解析回應。 您可以在 https://curl.haxx.se/download.html 下載適用於您平台的 cURL，並在 https://curl.haxx.se/docs/manpage.html 閱讀完整文件。但是不用擔心，我們將在解釋 Ragic HTTP API 時告訴您 cURL 的必要用法。 下載 cURL 之後，您可以使用以下命令訪問我們上述的相同端點，您應該會看到與在瀏覽器中相同的輸出。

curl https://www.ragic.com/demo/sales/1?api

請注意，當使用 CURL 時，-d 不會將內容編碼為 URL 字串。如果您的字串內容中有 % 或 & 等字元，請使用 --data-urlencode 選項來代替 -d。

Postman 是一個幫助您發送 HTTP 請求而無需編碼的工具。您可以在這裡查看 Postman 文件，並在這裡下載 Postman。 Postman 適合技術經驗較少的用戶使用，並且基本原理會在本教學中介紹。 Postman 的使用介面如下圖所示：

1. 下拉選單，列出所有可以選擇的 HTTP 方法
2. 發送 HTTP 請求的目標 URL
3. 發送 HTTP 請求的操作按鈕
4. 與 HTTP 請求相關的屬性

對於上述圖片，HTTP 請求是一個 GET 請求，並且它被發送到 https://www.ragic.com/demo/sales/1，帶有一個沒有值的查詢參數 "api"。 下拉選單中列出的 HTTP 方法。

欄位 ID 是 Ragic 分配給每個欄位的一個獨特值。它為您的程式提供了一種明確的方式來指定欄位。這樣的設計，即使在同一個表單中有欄位名稱相同，Ragic 仍然能夠區分它們。 從上方頁籤列中點擊表單名稱旁的三角形符號，選擇 Javascript 工作流程 後，就可以看到該張表單中各欄位對應的欄位 ID 。 你也可以進入設計模式，點擊要指定的欄位。在左側工具列，可以看到欄位名稱 。欄位 ID 就在欄位名稱的正下方。 其他查詢欄位 ID 的方式，請參考此篇文章。

您可以透過將 api 作為查詢字串參數傳遞來查找您的 Ragic 表單或資料的 API 端點，以指定這是一個 API 請求。

https://www.ragic.com/{ACCOUNT_NAME}>/{TAB_FOLDER}>/{SHEET_INDEX}/{RECORD_ID}?v=3&api

請注意：

• 根據您的 Ragic 帳號 URL，在 API URL 中需要將 www 修改為 na3 、ap5 或 eu2 等。
• API 版本由 URL 參數指定。詳見 指定 API 版本

每次發送請求時指定 API 版本是一個好習慣，以確保使用正確的版本。如果未指定版本，將使用最新版本，但 API 的意外變更可能會導致您的程式出現問題。 例如，如果您通常使用以下 URL 訪問您的 Ragic 表單：

https://www.ragic.com/demo/sales/1

其 HTTP API 端點 URL 將為：

https://www.ragic.com/demo/sales/1?v=3&api

或者對於表單中的資料，您需要包含一個 ID（例如資料 ID 為 1）來指定一筆資料：

https://www.ragic.com/demo/sales/1/1

其對應的 HTTP API 端點 URL 為：

https://www.ragic.com/demo/sales/1/1?v=3&api

只要在合理使用範圍內，我們的 API 呼叫沒有限制。如果您不確定您的使用是否合理，隨時可以發送信件至 support@ragic.com 與我們聯繫。 儘管 API 使用沒有硬性限制，但每個資料庫帳號都有排隊機制。隊列的最大大小為 50，當隊列滿時將停止接受 API 請求。因此，我們建議在發送下一個請求之前等待上一個請求的回應。請注意，此限制目前僅適用於 GET API 請求。 這只是為了確保我們系統的合理使用，以避免小型帳號出現過度使用的情況。如果使用量超過每秒 5 次請求，將觸發人工審核流程，以確定是否需要進行限流。

目前 API 以日期格式作為版本參數，同時仍相容舊版數字版本。 API 支援以下兩種版本機制：

• 現行版本（建議）： version=YYYY-MM-DD
• 舊版本（仍可使用）： v=1、v=2、v=3。

目前推薦使用的版本格式為日期字串，例如：version=2025-01-01 。 未來所有新增版本將僅支援日期格式。

舊版使用數字做為版本參數，例如：v=1 、v=2 、v=3 。 舊版仍可使用，但不建議用於新整合。

若請求未帶版本參數，API 將自動使用最新版本。

你可以在請求中提供 API 金鑰之一來認證 Ragic API。API 金鑰具有許多權限，因此請務必保密！ 當你的程式通過 API 金鑰訪問 Ragic 時，將基本上以 API 金鑰使用者的身份登錄並執行讀寫操作。我們強烈建議為 API 金鑰訪問建立一個單獨的使用者帳號。這樣 API 訪問才不會與其他使用者混淆，能讓系統審計追蹤更方便，也將使你的 API 程式除錯更加容易。 API 認證是通過 HTTP 基本認證進行的。提供你的 API 金鑰作為基本身份驗證的使用者名稱，不需要提供密碼。 所有 API 請求必須通過 HTTPS 進行。通過普通 HTTP 發出的請求會失敗。你必須為所有請求進行身份驗證。

curl https://www.ragic.com/demo/sales/1\
   --get -d api \
   -H "Authorization:Basic YOUR_API_KEY_GOES_HERE"

請注意，HTTP 標頭名稱為 Authorization，值是你的 API 金鑰，前面帶有 "Basic "，Basic 後面有一個空格，你可能需要根據你的 Ragic 帳號 URL 將 URL 中的 www 修改為 na3 、ap5 或 eu2 等。 你可以在個人設定中產生你的 API 金鑰。 大多數 HTTP 用戶端（包括網頁瀏覽器）會顯示一個對話框或提示你提供用於 HTTP 基本認證的使用者名稱和密碼（留空）。大多數用戶端還允許你在 URL 中提供憑證。 如果由於某種原因你無法將 API 金鑰作為 HTTP 標頭或基本身份驗證發送，你可以將 API 金鑰作為參數名為 APIKey 發送。你需要為你發送的每個請求增加此參數。

curl https://www.ragic.com/demo/sales/1\
   --get -d api \
   -d "APIKey=YOUR_API_KEY_GOES_HERE"

如果您的平台不支援 HTTP 基本身份驗證，您可以透過傳遞使用者的電子信箱和密碼作為登錄憑據來驗證。 如果您透過 Google 登入註冊，請確保在繼續本教學之前設定一個 Ragic 密碼。 請僅在無法使用 HTTP 基本身份驗證時使用此方法。 您可以使用有效的電子信箱和密碼發送請求以獲取 session id。您可以使用 -d 參數發出包含 id 和密碼的 HTTP 請求。-c 參數將 sessionId 儲存在指定的 cookie jar 文件中：

curl --get -d "u=jeff@ragic.com" \
 --data-urlencode "p=123456" \
 -d "login_type=sessionId" \
 -d api \
 -c cookie.txt \
 -k \
 https://www.ragic.com/AUTH

如果身份驗證失敗，伺服器將回傳**-1** 。如果身份驗證成功，您將在回應中收到一個 session id，如下所示：

2z5u940y2tnkes4zm49t2d4

請注意，這種身份驗證方法是基於會話的，會話是依賴於伺服器的。您可能需要根據您希望訪問的帳號位置修改 URL。例如，對於位於伺服器 https://ap8.ragic.com 的帳戶，請使用 https://ap8.ragic.com/AUTH。 在以後的請求中使用返回的 sessionId 以保持身份驗證，請在 URL 參數中包含 sessionId，如 sid= 。例如，https://www.ragic.com/demo/sales/1?sid=。 Ragic API 的使用將在後面的章節中介紹，請記住以這種方式包含您的 session ID 以保持身份驗證。 如果您想檢索登錄使用者的詳細資訊，還可以提供額外的 json=1 參數，以便 Ragic 回傳包含使用者詳細資訊的 json 對象。

curl --get -d "u=jeff@ragic.com" \
 --data-urlencode "p=123456" \
 -d "login_type=sessionId" \
 -d "json=1" \
 -d api \
 -c cookie.txt \
 -k \
 https://www.ragic.com/AUTH

回傳的格式如下所示：

{
"sid":"8xkz874fdftl116vkd3wgjq0t",
"email":"jeff@ragic.com",
"accounts":
  {
    "account":"demo",
    "ragicId":25,
    "external":false,
    "groups":["EVERYONE","SYSADMIN"]
  }
}

例如，這是 API 回應的範例，網址為 https://www.ragic.com/demo/sales/1?v=3 &api。請記得在呼叫中指定你的 cookie jar 檔案，如 "-b cookie.txt"。

{
"1":{
  "_ragicId": 1,
  "_star": false,
  "Account Name": "Alphabet Inc.",
  "_index_title_": "Alphabet Inc.",
  "Short Name": "",
  "Account ID": "C-00002",
  "EIN / VAT Number": "",
...
...
},
"0":{
  "_ragicId": 0,
  "_star": false,
  "Account Name": "Ragic, Inc.",
  "_index_title_": "Ragic, Inc.",
  "Short Name": "Ragic",
  "Account ID": "C-00001",
  "EIN / VAT Number": "",
...
...

預設情況下，列表顯示最多 1000 筆資料。你可以根據以下部分加入分頁參數 limit 以取得更多資料。 子表格中的資料顯示如下範例。屬性名稱是 subtable 後跟子表格 ID 以識別是哪個子表格。子表格的內容呈現方式與表單中的欄位相同。

"_subtable_2000154": {
    "0": {
      "_ragicId": 0,
      "Contact Name": "Jeff Kuo",
      "Title": "Technical Manager",
      "Phone": "886-668-037",
    },
    "1": {
      "Contact Name": "Amy Tsai",
      "Title": "Marketing",
      "Phone": "",
    },

如果你的應用程式不需要子表格中的資料，你可以加入參數 subtables=0 來關閉子表格資料的提取。 資料的回應也會以子表格的形式檢索。它將在欄位 ID 為 61 的子表格中檢索，但你需要在檢索資料時加入參數 comment=true 以回傳回應的資料。

你的資料庫中通常包含大量資料，因此在檢索資料時建議套用篩選條件。Ragic API 篩選工具具有特殊格式。 你可以使用參數 "where" 來為搜尋加入篩選條件，如下所示：

curl --get -d "where=2000123,eq,Alphabet Inc." \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d api \
https://www.ragic.com/demo/sales/1

參數是逗號分隔格式，至少包含 3 個參數：

1. 你想要篩選的欄位 ID。
2. 用於指定篩選操作的整數形式的運算符號。運算符號列表如下。
3. 你想要篩選欄位的值。請記住，如果你的值可能包含逗號字元，請對其進行 URL 編碼或使用 %2C 以避免衝突。

你可以用帶有多個篩選條件的查詢，如下所示：

curl --get -d "where=2000123,eq,Alphabet Inc." \
-d "where=2000127,eq,Jeff Kuo" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d api \
https://www.ragic.com/demo/sales/1

以下是支援的運算符號列表：

請注意：

1. 當你按日期或日期時間篩選時，需要使用以下格式：yyyy/MM/dd 或 **yyyy/MM/dd HH:mm:ss

**

1. 如果你想篩選空值，不需要填寫第三個參數，例如，**"where=2000127,eq,"** 。
2. 對同一欄位，設定多個 eq、regex 或者 like，會以 OR 條件 進行篩選。例如，要檢索欄位 ID 1000001 為 Ratshotel 或 Claflin 的資料，可以使用 **"where=1000001,eq,Ratshotel &where=1000001,eq,Claflin"**。
3. 對同一欄位，同時設定 gte/gt 和 lte/lt，則會以 AND 條件 進行篩選（適用於數值 或日期 欄位，用來指定範圍）。例如，要檢索欄位 ID 105 介於 2025/10/01 ~ 2025/10/31 的資料，可以使用 **"where=105,gte,2025/10/01 &where=105,lte,2025/10/31"**。
4. 若篩選值包含 % 並且 % 後面跟兩個十六進位字元（例如 ABC%DEF），需要進行兩次 URL encode。這是因為除了 Query string 在傳遞過程中需先進行一次 URL encode 外，篩選值為了避免後端在解析字串時受到特殊字元影響，仍需再進行一次 URL encode。例如，要檢索欄位 ID 1000002 的資料，其值為 ABC%DEF，由於該字串需要經過兩次 URL encode，因此應使用 where=1000002,eq,ABC%2525DEF 。

有些系統欄位具有特殊的欄位 ID，你可以在查詢中使用。常見的系統欄位如下：

你還可以使用 全文檢索 作為查詢篩選條件。只需在參數 fts 中提供查詢詞，就會回傳符合的結果。

curl --get -d "fts=Alphabet" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d api \
https://www.ragic.com/demo/sales/1

也可以套用共通篩選。只需設定如下 ID。

curl --get -d "filterId=YOUR_SHARED_VIEW_ID" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d api \
https://www.ragic.com/demo/sales/1

你可以透過點擊共通篩選 URL 取得 ID。

很多時候，你可能不希望在一次請求中檢索所有資料，你可以使用 limit 和 offset 參數來指定你想要檢索的資料數量，以及在開始時要跳過的資料數量，這樣用戶端就可以實現分頁查看資料。 limit 和 offset 參數的使用方式類似於 SQL 的 limit 參數。Offset 是在開始時要跳過的資料數量，limit 是要回傳的資料數量。 預設回傳資料量是 1000 筆 ，如果希望回傳包含超過 1000 筆資料，則需要提供 limit 參數。 格式如下：

limit=< limit >&offset=< offset >

offset 參數表示在回傳之前應跳過的資料數量，用於瀏覽已檢索頁面。 limit 參數是每次調用應回傳的最大資料數。 例如，下面的調用將跳過前 5 筆資料，並回傳第 6 到 13 筆，總共 8 筆資料。

curl --get -d "limit=8" \
-d "offset=5" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d api \
https://www.ragic.com/demo/sales/1

若未指定排序，資料預設會按照建立日期時間由舊到新排序。若您希望最新的結果排在最前面，可以像這樣指定 reverse=true ：

curl --get -d "reverse=true" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d api \
https://www.ragic.com/demo/sales/1

您也可以增加 order 參數來指定資料排序的方式。這有點類似於 SQL 中的 ORDER BY 子句，其值是一個以逗號分隔的字串，包含兩個參數。第一個是您希望資料根據其排序的欄位 ID，第二個是排序方式：ASC 表示升序，或 DESC 表示降序。

curl --get -d "order=800236,DESC" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d api \
https://www.ragic.com/demo/sales/1

增加回呼函式參數會將回傳的 JSON 對象作為參數包含在您指定的回呼函式中。這在您使用 Javascript 訪問我們的 API 時特別有用，因為您可能需要這樣做來進行跨域 ajax 調用。 像下方範例加入 callback=testFunc：

curl --get -d "callback=testFunc" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d api \
https://www.ragic.com/demo/sales/1

會將回傳的 JSON 對象包含在函式調用中，這樣您就可以在回呼函式中處理回傳的資料：

testFunc({"17": {

"Account Name": "Dunder Mifflin",

"Account Owner": "Jim Halpert",

"Phone": "1-267-922-5599",

 ...

 ...

});

JSON 資料格式使用欄位名稱字串作為屬性名稱，您可以使用 "naming" 參數來指定您希望使用欄位 ID 作為屬性名稱來識別欄位。 可能的值包括：EID（欄位 ID），FNAME（欄位名稱）。

curl --get -d "naming=EID" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d api \
https://www.ragic.com/demo/sales/1

有幾個參數可以用於 HTTP GET 請求，以改變回傳的內容：

CODEBLOCK_0_PLACEHOLDER | | ignoreMask | 當給定 ignoreMask=true 時，在查看時「遮罩欄位」的值將不會被遮罩。點擊 此處 查看遮罩欄位的介紹。 | | ignoreFixedFilter | 當給定 ignoreFixedFilter=true 時，此表單上的固定篩選將被忽略。但請注意，這僅在 API 調用的 API 金鑰使用者具有 SYSAdmin 權限時才有效。 |

在你的 HTTP API 呼叫回傳的 JSON 中，你會看到像這樣的檔案上傳欄位或圖片上傳欄位：

"1000537": "Ni92W2luv@My_Picture.jpg",

你可以使用下面的單獨呼叫下載該檔案（假設你的帳號名稱是 "demo"，API 呼叫 URL 為 https://www.ragic.com/demo/sales/1?v=3&api）：

https://www.ragic.com/sims/file.jsp?a=demo&f=Ni92W2luv@My_Picture.jpg

格式為：

https://www.ragic.com/sims/file.jsp?a=<帳號名稱>&f=<檔案名稱>

記住在將檔案名稱作為 URL 發送時要對其進行編碼。檔案原始的名稱將從 @ 字元後面開始，這樣可以避免檔案名稱衝突。

如果你有一筆資料的 URL 如下：

https://www.ragic.com/demo/sales/1/41

1. 友善列印

在 URL 後方加入 .xhtml 取得該資料的HTML 友善列印 版本：

https://www.ragic.com/demo/sales/1/41.xhtml

2. PDF 或 Excel 版本

在 URL 後方加入 .pdf 來取得 PDF 版本或 .xlsx 來取得 Excel 版本：

https://www.ragic.com/demo/sales/1/41.pdf
https://www.ragic.com/demo/sales/1/41.xlsx

3. 合併列印

在 URL 後方加入 .custom 和一個合併列印 CID 來取得資料的**合併列印 **，以指定使用的範本（範例中為合併列印範本編號1）：

https://www.ragic.com/demo/sales/1/41.custom?cid=1

要取得合併列印的 CID，你可以首先從 Ragic 介面手動下載合併列印，並找到下載 URL 中的 cid 參數：

https://www.ragic.com/demo/sales/1/41.custom?rn=41&<b>cid=1</b>

4. 客製列印報表

在 URL 後方加入 .carbone? 以及搭配以下參數(要加上 & 來連接各參數)來取得資料的**客製列印報表 **下載 URL：

https://www.ragic.com/demo/sales/1/41.carbone?fileFormat=pdf&ragicCustomPrintTemplateId=1&fileNameRefDomainId=1001000

(1) 檔案格式 參數：fileFormat=「檔案格式」(pdf, png, docx)，例如：fileFormat=pdf (2) 客製列印報表範本 ID 參數：ragicCustomPrintTemplateId=「Template ID」，例如：ragicCustomPrintTemplateId=1 要取得「Template ID」，首先先手動下載客製列印報表，並找到下載 URL 中的 「Template ID」 參數：

https://www.ragic.com/demo/sales/1/41.carbone?fileFormat=pdf&fileNameRefDomainId=-1&<b>ragicCustomPrintTemplateId=2</b>

(3) 檔案名稱參考欄位 參數(非必要)：fileNameRefDomainId=「欄位編號」，例如：fileNameRefDomainId=1001000

如果您不是只用 HTML 表單來在 Ragic 建立資料，則需要通過 API 請求來建立。寫入表單的端點與讀取表單的端點相同，但您需要發送 POST 請求而不是 GET 請求。 API 支援 JSON 格式，並且推薦使用此方式執行 HTTP 請求。 要發送 JSON 資料，您需要將 Body 設置更改為原始 JSON，如下圖所示。 要做的是使用欄位的 ID 作為名稱，並將要插入的值作為參數值。 請注意，您的使用者需要對該表單具有編輯權限才能使用此功能。

curl -F "2000123=Dunder Mifflin" \
 -F "2000125=1-267-922-5599" \
 -F "2000127=Jeff Kuo" \
-F "api=" \
 -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
 https://www.ragic.com/demo/sales/1

JSON 格式如下所示：

{
    "2000123": "Dunder Mifflin",
    "2000125": "1-267-922-5599",
    "2000127": "Jeff Kuo",
}

如果欄位是可以包含多個值的多選欄位 ，您可以使用多個具有相同欄位 ID 的參數名。如果欄位是日期欄位 ，則其值需要使用以下格式：yyyy/MM/dd 或者帶有時間部分 yyyy/MM/dd HH:mm 。因此，一個請求的格式會像這樣：

curl -F "2000123=Dunder Mifflin" \
 -F "2000125=1-267-922-5599" \
 -F "2000127=Jeff Kuo" \
 -F "1000001=Customer" \
 -F "1000001=Reseller" \
 -F "2000133=2018/12/25 23:30:00" \
 -F "api=" \
 -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
 https://www.ragic.com/demo/sales/1

相應的 JSON 格式如下，方括號內的 1000143 欄位 ID 允許在一個語句中包含多個值。

{
    "2000123": "Dunder Mifflin",
    "2000125": "1-267-922-5599",
    "2000127": "Jim Halpert",
    "1000001": ["Customer", "Reseller"],
    "2000133": "2018/12/25 23:30:00"
}

如果您想要同時插入資料到子表格 中，您需要對子表格中的欄位使用略有不同的格式，因為 Ragic 需要一種方法來確定欄位值是否屬於子表格中的同一筆資料。 如果欄位值在同一子表格列中，請將它們與每個其他欄位分配相同的負行 ID。這可以是任何負整數。這只是一種確定它們屬於同一列的方法。

2000147_-1=Bill
2000148_-1=Manager
2000149_-1=billg@microsoft.com

2000147_-2=Satya
2000148_-2=VP
2000149_-2=satyan@microsoft.com

The whole request would look like this:

curl -F "2000123=Dunder Mifflin" \
 -F "2000125=1-267-922-5599" \
 -F "2000127=Jeff Kuo" \
 -F "1000001=Customer" \
 -F "1000001=Reseller" \
 -F "2000133=2018/12/25 23:30:00" \
 -F "2000147_-1=Bill" \
 -F "2000148_-1=Manager" \
 -F "2000149_-1=billg@microsoft.com" \
 -F "2000147_-2=Satya" \
 -F "2000148_-2=VP" \
 -F "2000149_-2=satyan@microsoft.com" \
-F 'api=' \
 -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
 https://www.ragic.com/demo/sales/1

相應的 JSON 格式如下：

{

    "2000123": "Dunder Mifflin",
    "2000125": "1-267-922-5599",
    "2000127": "Jim Halpert",
    "1000001": ["Customer", "Reseller"],
    "2000133": "2018/12/25 23:30:00"
    "_subtable_2000154": {
        "-1": {
            "2000147": "Bill",
            "2000148": "Manager",
            "2000149": "billg@microsoft.com"
        },
       "-2": {
            "2000147": "Satya",
            "2000148": "VP",
            "2000149": "satyan@microsoft.com"
        }
    }
}

如果您想填入檔案上傳欄位 ，請確保請求的編碼類型是multipart/form-data 。在 HTML 中的等效操作是設置 enctype='multipart/form-data'。 使用多部分請求，您可以將檔案放入請求中，並將檔案名作為欄位值。

1000088=test.jpg

Ragic支援使用POST、PUT、PATCH請求來修改資料。 修改資料的端點與讀取現有資料的端點相同。請注意，當您建立資料時，端點指向一個 Ragic 表單，但當您編輯資料時，您的端點將需要額外的資料 ID 來指向確切的一筆資料 。

https://www.ragic.com/<account>/<tab folder>/<sheet index>/<record id>?api
</record></sheet></tab></account>

您只需提供要修改的欄位 ID。如果欄位是日期欄位 ，則其值需要使用 yyyy/MM/dd 或 yyyy/MM/dd HH:mm 格式。

curl -F "2000123=Dunder Mifflin" \
 -F "2000127=Jim Halpert" \
 -F "api=" \
 -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
 https://www.ragic.com/demo/sales/1<b>/3</b>

相應的 JSON 格式如下：

{
    "2000123": "Dunder Mifflin",
    "2000127": "Jim Halpert"
}

對於子表格來說，稍微複雜一些。因為 Ragic 需要知道您正在編輯的列。因此，您需要找到要編輯的列的 ID。此資訊可以從 API 調用中取得。 如前面章節所述，帶有子表格資料的回傳格式如下：

"_subtable_2000154": {
    "0": {
      "Contact Name": "Jeff Kuo",
      "Title": "Technical Manager",
      "Phone": "886-668-037",
      "E-mail": "jeff@ragic.com",
...
...
    },
    "1": {
      "Contact Name": "Amy Tsai",
      "Title": "Marketing",
      "Phone": "",
...
...
    },
    "2": {
      "Contact Name": "Allie Lin",
      "Title": "Purchasing",
...
...

在子表格中，1 是聯絡人 Amy Tsai 的列 ID，2 是聯絡人 Allie Lin 的列 ID。使用這些列 ID，就可以針對該子表格列修改資料。 您可以使用列 ID 作為跟隨在欄位 ID 之後的標識符號。並放入要修改的欄位：

2000147_1=Ms. Amy Tsai
2000148_1=Senior Specialist

2000148_2=Senior Manager

整個請求將如下所示：

curl -F "2000123=Dunder Mifflin" \
 -F "2000127=Jim Halpert" \
 -F "2000147_1=Ms. Amy Tsai" \
 -F "2000148_1=Senior Specialist" \
 -F "2000148_2=Senior Manager" \
 -F "api=" \
 -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
 https://www.ragic.com/demo/sales/1<b>/3</b>

相應的 JSON 格式如下：

{
    "2000123": "Dwight Schrute",
    "2000127": "Jim Halpert" ,
    "_subtable_2000154": {
        "29" :{
            "2000147": "Ms. Amy Tsai",
            "2000148": "Senior Specialist"
        },
        "30" :{
            "2000148": "Senior Manager"
        }
    }
}

如果要刪除子表格列，可以建立如下請求：

DELSUB_<subtable key>=<subtable row id>
</subtable></subtable>

相應的 JSON 格式如下：

_DELSUB_<subtable key>=[<subtable row id>,<subtable row id>,...,<subtable row id>];
</subtable></subtable></subtable></subtable>

例如，如果要刪除聯絡人 Arden Jacobs，整個請求如下所示：

curl -F "DELSUB_2000154=3" \
 -F "api=" \
 -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
 https://www.ragic.com/demo/sales/1<b>/3</b>

相應的 JSON 格式如下：

{
    "_DELSUB_2000154": [3]
}

使用 JSON 格式來刪除子表格列讓您以簡單的方式指定多列：

{
    "_DELSUB_subtable key": [<subtable row id>,..., <subtable row id>]
}
</subtable></subtable>

有許多有用的參數可以在 Ragic 上建立或更新資料時使用，以節省編寫程式的時間。

刪除資料與讀取資料非常相似。你只需要將請求方法從 GET 更改為 DELETE 。當使用 DELETE 請求時，API 端點的資料將被刪除。

curl -X DELETE \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d "api"  \
https://www.ragic.com/demo/sales/1/3

確保你的 content-type 是 multipart/form-data ，這樣你就可以上傳檔案。

curl -F "1000088=@/your/file/path" \
-F "api=" \
-F "v=3" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
https://www.ragic.com/demo/sales/1

上傳成功後，你將以以下格式接收到你的檔案。

"1000088": "Ni92W2luv@test.jpg",

將滑鼠停留在方框區域上以顯示下拉選單，並選擇 "File" 來上傳檔案。 如果你想取得剛剛上傳的檔案，請按照這裡的說明操作。 如果想利用連結上傳檔案，首先下載檔案，然後按照上述說明操作。

curl -o __TEMP_FILE__ YOUR_IMAGE_LINK
curl -F "1000002=@__TEMP_FILE__" -F "api=" -F "v=3" -H "Authorization:Basic YOUR_API_KEY" https://www.ragic.com/demo/sales/1

記得替換 YOUR_IMAGE_LINK 和 YOUR_API_KEY 。 你可以在個人設定取得你的 API 金鑰。

請確保你的 content-type 是 multipart/form-data 。

curl -F "at=@/your/file/path" \
-F "c=yourComment"
-F "api=" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
https://www.ragic.com/demo/ragicsales-order-management/10001/2

參數 c 為留言回應的內容(必填)，參數 at 為附件(選填)。 你可以在個人設定取得你的 API 金鑰。

回應範例：

{
  "61": "2025/02/13 14:30",
  "65": "王小明",
  "66": "請檢查此訂單。",
  "67": "",
  "73": "1739425800000"
}

欄位 61 為格式化時間戳記，65 為留言者姓名，66 為留言內容，67 為附件檔名（無附件時為空），73 為原始時間戳記（毫秒）。

您必須為具備 系統管理員 (SYSAdmin) 權限，才能使用此 API。 使用此API，需先啟動「定期從網址匯入」功能。完成相關設定後，即可透過下列 API 呼叫觸發匯入作業：

curl -F "importData="
-F "api=" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
https://www.ragic.com/demo/ragicsales-order-management/10001

當您需要新增或修改大量資料 時，也可透過此方式一次匯入，避免大量呼叫 API，提高效率。 你可以在個人設定取得你的 API 金鑰。

回應範例：

{
  "status": "SUCCESS",
  "msg": "Import completed."
}

使用 Http API 上鎖/解鎖 資料，只需在目標資料的網址加上要求字串 api 與 lock/unlock，並以POST方法發送即可。

curl -X POST https://www.ragic.com/demo/ragicforms23/10004/102?api&lock

curl -X POST https://www.ragic.com/demo/ragicforms23/10004/102?api&unlock

上鎖/解鎖 所需權限與從表單操作相同。 你可以在個人設定取得你的 API 金鑰。

回應範例：

{
  "status": "SUCCESS",
  "code": 200
}

要使用 Http API 執行動作按鈕，您需要取得 動作按鈕 ID 。 請使用 GET 方法發送以下請求：

curl "https://{serverName}/{accountName}{path}/{sheetIndex}/metadata/actionButton?api&category=massOperation" \
  -H "Authorization: {Basic apiKey}"

取得 動作按鈕 ID 後，您即可使用 POST 方法發送以下請求，對指定資料執行該動作按鈕：

curl -X POST "https://{serverName}/{accountName}{path}/{sheetIndex}/{recordId}?api&bId={buttonId}" \
  -H "Authorization: Basic apiKey"

提醒： 除了執行目標動作按鈕的權限以外，您還需要瀏覽目標資料的權限 ，才可以使用此 Http API。 你可以在個人設定取得你的 API 金鑰。

回應範例：

{
  "status": "SUCCESS",
  "msg": "Action completed."
}

如果請求回傳錯誤，通常會顯示如下內容：

{
    "status": "ERROR",
    "code": 303,
    "msg": "Your account has expired."
}

以下是可能在 Ragic 請求中回傳的 HTTP 狀態代碼列表：

如果請求處理過程中出現錯誤，通常會包含一個錯誤代碼和描述。以下是可能作為響應 Ragic 請求的錯誤代碼列表：

大量操作 API 設計用來在單一請求中對表單中的多筆資料執行相同的操作。 有兩種指定要更新資料的方法：

• 使用 where篩選

https://www.ragic.com/<帳號>/<頁籤路徑參數>/<表單路徑參數>/massOperation/<大量操作類型>?api&where=<欄位 ID>,<過濾操作元>,<值>

• 在查詢欄位中使用 recordId，例如 recordId=1&recordId=2

https://www.ragic.com/<帳號>/<頁籤路徑參數>/<表單路徑參數>/massOperation/<大量操作類型>?api&recordId=<資料 ID>

• 大量操作 API 是非同步 操作。
  • 根據您的 Ragic 資料庫帳號 URL，需要將 API URL 中的 www 修改為 na3、ap5 或 eu2。

HTTP 方法 - POST
URL - https://www.ragic.com/<帳號>/<頁籤路徑參數>/<表單路徑參數>/massOperation/<大量操作類型>?api
標頭
Authorization: Basic <api 金鑰>

主體
{
// 描述要執行操作的 JSON 資料
}

==========

回應
{
"taskId": <識別任務的 UUID>
}
</api>

大量鎖定 API 允許一次鎖定或解鎖多筆資料。 大量鎖定

HTTP 方法 - POST
URL - https://www.ragic.com/<帳號>/<頁籤路徑參數>/<表單路徑參數>/massOperation/massLock?api

{
    "action": <lock 或 unlock>
}

==========

回應
{
    "taskId": "6dbc796a-07d5-475b-b578-d254eb30f7d2"
}
</lock>

批次簽核 API 允許一次同意或拒絕多筆資料的簽核。 批次簽核

HTTP 方法 - POST
URL - https://www.ragic.com/<帳號>/<頁籤路徑參數>/<表單路徑參數>/massOperation/massApproval?api

{
    "action": <approve 或 reject>,
    "comment": <回應> // 可選
}

==========

回應
{
    "taskId": "6dbc796a-07d5-475b-b578-d254eb30f7d2"
}
</approve>

批次執行動作按鈕 API 允許一次執行多筆資料的按鈕。 批次執行動作按鈕

HTTP 方法 - POST
URL - https://www.ragic.com/<帳號>/<頁籤路徑參數>/<表單路徑參數>/massOperation/massActionButton?api
{
"buttonId": <按鈕 ID>
}

==========

回應
{
"taskId": "6dbc796a-07d5-475b-b578-d254eb30f7d2"
}

取得表單中可用的動作按鈕列表

HTTP 方法 - GET
URL - https://www.ragic.com/<帳號>/<頁籤路徑參數>/<表單路徑參數>/metadata/actionButton?api&category=massOperation

==========

回應
{
    "actionButtons": [
        {
            "id": <按鈕 ID 1>,
            "name": <按鈕名稱 1>
        },
        .....
        ,{
            "id": <按鈕 ID 2>,
            "name": <按鈕名稱 2>
        }
    ]
}

大量修改 API 允許一次更新多筆資料的欄位值。 大量修改

HTTP 方法 - POST
URL - https://www.ragic.com/<帳號>/<頁籤路徑參數>/<表單路徑參數>/massOperation/massUpdate?api

{
    "action": [
        {
            "field": <欄位 ID>,
            "value": <新欄位值>
        }
    ]
}

==========

回應
{
    "taskId": "6dbc796a-07d5-475b-b578-d254eb30f7d2"
}

大量修改API也支持對 內部使用者表單 與 外部使用者表單 進行修改，但使用上有一些限制。 以下欄位不開放大量修改：

• 電子郵件(domainId: 1)
• 使用者名稱(domainId: 4)
• 系統備註(domainId: 10)
• 狀態(domainId: 31)
• 內外部(domainId: 43)

群組(domainId: 3) 開放修改，但有限制：

• value 的值必須為 JSON 陣列，其中包含字串元素。
• 字串中的特殊字元需要使用跳脫字符（\）來表示，特別是雙引號（“）需要表示為 \”

HTTP 方法 - POST
URL - https://www.ragic.com/<帳號>/<頁籤路徑參數>/<表單路徑參數>/massOperation/massUpdate?api

{
    "action": [
        {
            "field": 3,
            "value": "[\"SYSAdmin\"]"
        }
    ]
}

==========

回應
{
    "taskId": "6dbc796a-07d5-475b-b578-d254eb30f7d2"
}

• 內部使用者表單，必須至少有一個使用者的群組為 SYSAdmin
  • 外部使用者表單，使用者的群組必須以 x- 或 X- 開頭

大量操作是非同步的。操作的工作項目 ID 可用於監控其進度。

HTTP 方法 - GET
URL - https://www.ragic.com/<帳號>?api&taskId=<工作項目 ID>

==========

回應
{
  "id": "6dbc796a-07d5-475b-b578-d254eb30f7d2",
  "ap": "myaccount",
  "taskName": "Mass Update",
  "status": "PROCESSING",
  "processed": 50,
  "success": 48,
  "fail": 2,
  "message": ""
}

status 欄位可為 NOT_STARTED（尚未開始）、PROCESSING（處理中）或 DONE（已完成）。processed、success 和 fail 欄位分別表示已處理、成功和失敗的資料筆數。

Webhook 是透過外部應用程式訂閱您的 Ragic 變更的一種方式。 透過訂閱這些變更，每當 Ragic 上發生變更時，Ragic 將調用您提供的 Webhook URL 來通知您變更的情況，包括被更改的資料 ID。 使用 Webhook API 的最大優勢之一是，它在處理變更時效率更佳。不需要每隔幾小時輪詢 API 來檢查最新的變更情況。

您可以在 Ragic 的工具列中的同步下方找到表單的 Webhook。 關於 webhook API 的一些注意事項： 它會在建立、更新和刪除時觸發。 它不是完全同步的，當負載較高時可能會有輕微延遲。 變更不包括對關聯工作表（如多版本）的更改。 點擊 “webhook” 功能並輸入應接收通知的 URL，然後完成設定。您還可以選擇勾選「發送更改記錄的完整內容」來接收修改資料的完整資訊。要取消 webhook 設定，請點擊 webhook 視窗角落的 X 。 不帶完整內容的 JSON 格式如下：

[1, 2, 4]

例如，此範例表示具有節點 ID 1、2 和 4 的資料已更改。 帶完整內容的 JSON 格式如下：

{
  "data": [
    < 修改後的資料 JSON >
  ],
  "apname": "< 帳號名稱 >",
  "path": "< 路徑名稱 >",
  "sheetIndex": < 表單序號 >,
  "eventType": "< 事件類型 CREATE/UPDATE/DELETE >"
}

為了確保 Webhook 請求確實來自Ragic、且內容未被竄改，設定為「發送更改記錄的完整內容」的 Webhook，發出的請求會附帶一個 signature。 您可以在接收到 Webhook 後，使用我們提供的公鑰驗證該簽章是否正確。 若驗證失敗，表示該請求可能已被竄改，建議拒絕處理。

1. 取得 string-to-sign

1.1. 取出 Webhook 請求中的 data 屬性。 (data 屬性應該為 JSONArray 格式) 1.2. 將其序列化為 按照 key 名字排序 、無縮排 、無換行 的 JSON 字串。可以理解為「將JSONArray中，物件的所有欄位依照字母順序重新排序，然後輸出一行 JSON」。

// 轉換前 (原始 data 屬性)：
[
  {
    "1001030":"banana",
    "1001029":"apple"
  }
]

// 轉換後 (string-to-sign)：
[{"1001029":"apple","1001030":"banana"}]

注意： 若序列化方式與我們不一致，會導致簽章驗證失敗。

2. 驗證簽章

2.1. 取出 Webhook 請求中的 signature 屬性。 2.2. 下載公鑰（參考 取得公鑰）。 2.3. 使用支援 SHA256withRSA 的驗簽工具。

1. 將 string-to-sign 轉換為 UTF-8 byte array
2. 使用公鑰與演算法驗證簽章

2.4. 驗證結果若為成功，表示請求來自Ragic且內容未被竄改。

我們提供兩種方式供您取得公鑰，請選擇最適合您的情境：

1. 直接取得公鑰字串，請呼叫：https://www.ragic.com/api/http/getWebhookSignaturePublicKey.jsp?type=string。
2. 點擊 這裡 下載 PEM 檔。

建議將公鑰快取在您的伺服器上，僅在啟動時重新下載。

• 若您使用私有主機版，或未啟用「發送更改記錄的完整內容」功能，Webhook 將不支援簽章驗證。
  • 請確保您的程式正確處理 JSON 序列化的一致性，否則會出現驗證錯誤。