openapi: 3.0.3
info:
  title: Ragic HTTP API
  version: "3.0"
  contact:
    name: Ragic Support
    url: https://www.ragic.com/intl/en/support
    email: support@ragic.com
  license:
    name: Proprietary
    url: https://www.ragic.com/intl/en/tos
  description: |
    Ragic REST API 可讓您以程式方式查詢、建立、更新和刪除資料。所有 API 請求必須透過 HTTPS 進行。
servers:
  - url: https://{server}
    variables:
      server:
        default: www.ragic.com
        description: >-
          Your Ragic server hostname — must match your account URL (e.g. www.ragic.com, ap2.ragic.com, na3.ragic.com,
          eu2.ragic.com)
security:
  - basicAuth: []
  - apiKey: []
tags:
  - name: introduction
    x-displayName: 簡介
    description: >
      Ragic HTTP API 是 REST 風格的介面，可讓您讀取、建立、更新和刪除任何 Ragic 表單上的資料。您可以使用任何 HTTP 用戶端工具，包括 cURL、Postman 或您所使用程式語言的 HTTP 函式庫。



      ## Ragic REST 網路服務介面


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


      ## 使用 cURL 存取 HTTP API


      您可以輕鬆地在瀏覽器中輸入 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 之後，您可以使用以下命令訪問我們上述的相同端點，您應該會看到與在瀏覽器中相同的輸出。

      ```bash

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

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

      ## 使用 Postman 存取 HTTP API


      Postman 是一個幫助您發送 HTTP 請求而無需編碼的工具。您可以在[這裡](https://learning.postman.com/docs/getting-started/introduction/)查看
      Postman 文件，並在[這裡](https://www.postman.com/downloads/)下載 Postman。 Postman 適合技術經驗較少的用戶使用，並且基本原理會在本教學中介紹。 Postman
      的使用介面如下圖所示： ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-05-30+at+6.55.43+PM.png)

      1. 下拉選單，列出所有可以選擇的 HTTP 方法

      2. 發送 HTTP 請求的目標 URL

      3. 發送 HTTP 請求的操作按鈕

      4. 與 HTTP 請求相關的屬性


      對於上述圖片，HTTP 請求是一個 GET 請求，並且它被發送到 https://www.ragic.com/demo/sales/1，帶有一個沒有值的查詢參數 "api"。 下拉選單中列出的 HTTP 方法。
      ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-05-31+at+11.00.00+AM.png)


      ## 如何找欄位 ID


      **欄位 ID** 是 Ragic 分配給每個欄位的一個獨特值。它為您的程式提供了一種明確的方式來指定欄位。這樣的設計，即使在同一個表單中有欄位名稱相同，Ragic 仍然能夠區分它們。
      從上方頁籤列中點擊表單名稱旁的三角形符號，選擇 **Javascript 工作流程** 後，就可以看到該張表單中各欄位對應的**欄位 ID** 。
      ![](https://www.ragic.com/sims/file.jsp?a=kb&f=_clipboard1753173678696.png)
      你也可以進入設計模式，點擊要指定的欄位。在左側工具列，可以看到**欄位名稱** 。**欄位 ID** 就在欄位名稱的正下方。
      ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Field+ID.png) 其他查詢**欄位 ID**
      的方式，請參考[此篇文章](https://www.ragic.com/intl/zh-TW/doc-kb/176/what-is-field-id)。


      ## 查找 API 端點


      您可以透過將 **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 版本](https://www.ragic.com/intl/zh-TW/doc-api/46)

      每次發送請求時指定 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 限制


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


      ## 指定 API 版本


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

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

      ## 日期格式版本機制（現行版本）


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


      ## 舊版本機制（依然可使用）


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


      ## 版本列表：


      | 版本參數 | 備註 |

      | --- | --- |

      | (無對應) | v=1 |

      | (無對應) | v=2 |

      | version=2025-01-01 | 等同 v=3。最新版本。 |

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


      ```bash

      curl https://www.ragic.com/demo/sales/1\
         --get -d api \
         -H "Authorization:Basic YOUR_API_KEY_GOES_HERE"
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-06+at+5.49.47+PM.png) 請注意，HTTP 標頭名稱為 Authorization，值是你的 API 金鑰，前面帶有 "Basic "，Basic 後面有一個空格，你可能需要根據你的 Ragic 帳號 URL 將 URL 中的 **www** 修改為 **na3** 、**ap5** 或 **eu2** 等。 你可以在[個人設定](https://www.ragic.com/intl/zh-TW/doc-user/20/personal-settings#4)中產生你的 API 金鑰。 ![](https://www.ragic.com/sims/file.jsp?a=kb&f=_clipboard1716451918956.png) 大多數 HTTP 用戶端（包括網頁瀏覽器）會顯示一個對話框或提示你提供用於 HTTP 基本認證的使用者名稱和密碼（留空）。大多數用戶端還允許你在 URL 中提供憑證。 如果由於某種原因你無法將 API 金鑰作為 HTTP 標頭或基本身份驗證發送，你可以將 API 金鑰作為參數名為 **APIKey** 發送。你需要為你發送的每個請求增加此參數。

      ```bash

      curl https://www.ragic.com/demo/sales/1\
         --get -d api \
         -d "APIKey=YOUR_API_KEY_GOES_HERE"
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-06+at+5.52.50+PM.png)
  - name: auth-password
    x-displayName: 密碼驗證
    description: >
      如果您的平台不支援 HTTP 基本身份驗證，您可以透過傳遞使用者的電子信箱和密碼作為登錄憑據來驗證。 **如果您透過 Google 登入註冊，請確保在繼續本教學之前設定一個 Ragic 密碼。** **請僅在無法使用 HTTP
      基本身份驗證時使用此方法。** 您可以使用有效的電子信箱和密碼發送請求以獲取 session id。您可以使用 -d 參數發出包含 id 和密碼的 HTTP 請求。-c 參數將 sessionId 儲存在指定的 cookie
      jar 文件中：


      ```bash

      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
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-07+at+9.31.35+AM.png) 如果身份驗證失敗，伺服器將回傳**-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 對象。

      ```bash

      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
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-07+at+9.32.09+AM.png) 回傳的格式如下所示：

      ```json

      {

      "sid":"8xkz874fdftl116vkd3wgjq0t",

      "email":"jeff@ragic.com",

      "accounts":
        {
          "account":"demo",
          "ragicId":25,
          "external":false,
          "groups":["EVERYONE","SYSADMIN"]
        }
      }

      ```
  - name: reading-format
    x-displayName: 回傳資料的 JSON 格式
    description: |
      例如，這是 API 回應的範例，網址為 **https://www.ragic.com/demo/sales/1?v=3 &api**。請記得在呼叫中指定你的 cookie jar 檔案，如 "-b cookie.txt"。

      ```json
      {
      "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** 以回傳回應的資料。
  - name: reading-filter
    x-displayName: 篩選條件
    description: |
      你的資料庫中通常包含大量資料，因此在檢索資料時建議套用篩選條件。Ragic API 篩選工具具有特殊格式。 你可以使用參數 "where" 來為搜尋加入篩選條件，如下所示：

      ```bash
      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
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-06+at+6.03.38+PM.png) 參數是逗號分隔格式，至少包含 3 個參數：
      1. 你想要篩選的欄位 ID。
      2. 用於指定篩選操作的整數形式的運算符號。運算符號列表如下。
      3. 你想要篩選欄位的值。請記住，如果你的值可能包含逗號字元，請對其進行 URL 編碼或使用 %2C 以避免衝突。

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

      ```bash
      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
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-06+at+6.08.17+PM.png) 以下是支援的運算符號列表：

      | 運算符號名稱 | 運算值 |
      | --- | --- |
      | 等於 | eq |
      | 正規表示法 | regex |
      | 大於等於 | gte |
      | 小於等於 | lte |
      | 大於 | gt |
      | 小於 | lt |
      | 包含 | like |
      | 等於 node id | eqeq |

       請注意：

        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，你可以在查詢中使用。常見的系統欄位如下：

      | 系統欄位名稱 | 欄位 ID |
      | --- | --- |
      | 建立日期 | 105 |
      | 資料管理者 | 106 |
      | 建立使用者 | 108 |
      | 最後更新日期 | 109 |
      | 通知使用者 | 110 |
      | 是否上鎖 | 111 |
      | 是否打星號 | 112 |

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

      ```bash
      curl --get -d "fts=Alphabet" \
      -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
      -d api \
      https://www.ragic.com/demo/sales/1
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-06+at+6.09.27+PM.png) 也可以套用[共通篩選](https://www.ragic.com/intl/zh-TW/doc/19/saving-frequent-searches#2)。只需設定如下 ID。

      ```bash
      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
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-06+at+6.10.10+PM.png) 你可以透過點擊共通篩選 URL 取得 ID。 ![](https://www.ragic.com/sims/file.jsp?a=kb&f=shared+view+url.png)
  - name: reading-paging
    x-displayName: 限制資料數量 / 分頁
    description: >
      很多時候，你可能不希望在一次請求中檢索所有資料，你可以使用 **limit** 和 **offset** 參數來指定你想要檢索的資料數量，以及在開始時要跳過的資料數量，這樣用戶端就可以實現分頁查看資料。 limit 和
      offset 參數的使用方式類似於 SQL 的 limit 參數。Offset 是在開始時要跳過的資料數量，limit 是要回傳的資料數量。 **預設回傳資料量是 1000 筆** ，如果希望回傳包含超過 1000
      筆資料，則需要提供 limit 參數。 格式如下：


      ```

      limit=< limit >&offset=< offset >

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

      ```bash

      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

      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-08-15+at+4.56.08+PM1.png)
  - name: reading-sorting
    x-displayName: 排序與排列
    description: |
      若未指定排序，資料預設會按照建立日期時間由舊到新排序。若您希望最新的結果排在最前面，可以像這樣指定 **reverse=true** ：

      ```bash
      curl --get -d "reverse=true" \
      -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
      -d api \
      https://www.ragic.com/demo/sales/1
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-06+at+6.16.31+PM.png) 您也可以增加 **order** 參數來指定資料排序的方式。這有點類似於 SQL 中的 ORDER BY 子句，其值是一個以逗號分隔的字串，包含兩個參數。第一個是您希望資料根據其排序的欄位 ID，第二個是排序方式：ASC 表示升序，或 DESC 表示降序。

      ```bash
      curl --get -d "order=800236,DESC" \
      -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
      -d api \
      https://www.ragic.com/demo/sales/1
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-07+at+9.37.13+AM.png)
  - name: reading-callback
    x-displayName: 回呼函式 (JSONP)
    description: >
      增加回呼函式參數會將回傳的 JSON 對象作為參數包含在您指定的回呼函式中。這在您使用 Javascript 訪問我們的 API 時特別有用，因為您可能需要這樣做來進行跨域 ajax 調用。 像下方範例加入
      callback=testFunc：


      ```bash

      curl --get -d "callback=testFunc" \

      -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \

      -d api \

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

      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-06+at+6.24.04+PM.png) 會將回傳的 JSON 對象包含在函式調用中，這樣您就可以在回呼函式中處理回傳的資料：

      ```

      testFunc({"17": {


      "Account Name": "Dunder Mifflin",


      "Account Owner": "Jim Halpert",


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

       ...

       ...

      });

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

      ```bash
      curl --get -d "naming=EID" \
      -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
      -d api \
      https://www.ragic.com/demo/sales/1
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-06+at+6.25.20+PM1.png)
  - name: reading-other-params
    x-displayName: 其他 GET 參數
    description: >
      有幾個參數可以用於 HTTP GET 請求，以改變回傳的內容：


      | 參數名稱 | 描述 |

      | --- | --- |

      | subtables | 指定 **subtables=0** 告訴 Ragic API 不在回傳中包含子表格資訊。 |

      | listing | 指定 **listing=true** 告訴 Ragic API 僅包含列表頁的欄位。 |

      | reverse | 指定 **reverse=true** 告訴 Ragic API 反轉列表頁面回傳的預設排序。 |

      | info | 加入 **info=true** 參數將在回傳中增加「建立日期」、「建立使用者」資訊。 |

      | conversation | 加入 **conversation=true** 參數將在回傳中增加與此資料相關的信件資訊。 |

      | approval | 加入 **approval=true** 參數將在回傳中增加與此資料相關的簽核資訊。 |

      | comment | 加入 **comment=true** 參數將在回傳中增加與此資料相關的回應紀錄。 |

      | bbcode | 加入 **bbcode=true** 參數將取得保存到欄位中的原始 BBCode 值，而不是轉換為 HTML。 |

      | history | 加入 **history=true** 參數將在回傳中增加與此資料相關的修改紀錄。修改紀錄將以 JSON 表示，包含時間、類型、表單、使用者、詳細資訊。


      CODEBLOCK_0_PLACEHOLDER |

      | ignoreMask | 當給定 **ignoreMask=true** 時，在查看時「遮罩欄位」的值將不會被遮罩。點擊 此處 查看遮罩欄位的介紹。 |

      | ignoreFixedFilter | 當給定 **ignoreFixedFilter=true** 時，此表單上的固定篩選將被忽略。但請注意，這僅在 API 調用的 API 金鑰使用者具有 SYSAdmin 權限時才有效。
      |
  - name: reading-files
    x-displayName: 取得上傳檔案、圖片及 E-mail 附件
    description: |
      在你的 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 發送時要對其進行編碼。檔案原始的名稱將從 @ 字元後面開始，這樣可以避免檔案名稱衝突。
  - name: reading-exports
    x-displayName: 取得資料的 HTML、PDF、Excel 或合併列印及客製列印報表
    description: >
      如果你有一筆資料的 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** 來取得資料的**[合併列印](https://www.ragic.com/intl/zh-TW/doc/42/mail-merge)
      **，以指定使用的範本（範例中為合併列印範本編號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?** 以及搭配以下參數(要加上 **&**
      來連接各參數)來取得資料的**[客製列印報表](https://www.ragic.com/intl/zh-TW/doc/138/custom-print-report) **下載 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=「[欄位編號](https://www.ragic.com/intl/zh-TW/doc-kb/176/%E6%AC%84%E4%BD%8D-ID-%28%E6%AC%84%E4%BD%8D%E7%B7%A8%E8%99%9F%29%E6%98%AF%E4%BB%80%E9%BA%BC%EF%BC%9F)」，例如：**fileNameRefDomainId=1001000**
  - name: writing-create
    x-displayName: 建立新資料
    description: >
      如果您不是只用 HTML 表單來在 Ragic 建立資料，則需要通過 API 請求來建立。寫入表單的端點與讀取表單的端點相同，但您需要發送 POST 請求而不是 GET 請求。 API 支援 JSON
      格式，並且推薦使用此方式執行 HTTP 請求。 要發送 JSON 資料，您需要將 Body 設置更改為原始 JSON，如下圖所示。
      ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-07+at+9.42.41+AM.png) 要做的是使用欄位的 ID
      作為名稱，並將要插入的值作為參數值。 請注意，您的使用者需要對該表單具有編輯權限才能使用此功能。


      ```bash

      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
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-07+at+9.46.48+AM.png) JSON 格式如下所示：

      ```json

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

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

      ```bash

      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
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-07+at+9.48.05+AM.png) 相應的 JSON 格式如下，方括號內的 1000143 欄位 ID 允許在一個語句中包含多個值。

      ```json

      {
          "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:

      ```bash

      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
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-07+at+9.51.52+AM.png) 相應的 JSON 格式如下：

      ```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

      ```
  - name: writing-modify
    x-displayName: 修改資料
    description: >
      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** 格式。

      ```bash

      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>
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-07+at+10.18.32+AM.png) 相應的 JSON 格式如下：

      ```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

      ```
       整個請求將如下所示：

      ```bash

      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>
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-07+at+10.20.15+AM.png) 相應的 JSON 格式如下：

      ```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，整個請求如下所示：

      ```bash

      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>
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-07+at+10.21.13+AM.png) 相應的 JSON 格式如下：

      ```json

      {
          "_DELSUB_2000154": [3]
      }

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

      ```json

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

      </subtable></subtable>

      ```
  - name: writing-params
    x-displayName: 建立或更新參數
    description: |
      有許多有用的參數可以在 Ragic 上建立或更新資料時使用，以節省編寫程式的時間。

      | 參數名稱 | 描述 |
      | --- | --- |
      | doFormula | 指定 doFormula=true 告訴 Ragic API 在建立或更新資料時先重新計算所有公式。請注意，如果設定為 true，為避免無限迴圈，建立在表單中的 workflow 將不會運行。 |
      | doDefaultValue | 指定 doDefaultValue=true 告訴 Ragic API 在建立或更新資料時載入所有預設值。 |
      | doLinkLoad | 指定 doLinkLoad=true 告訴 Ragic API 在建立或更新資料時，先重新計算所有公式，再執行所有連結與載入。
      指定 doLinkLoad=first 告訴 Ragic API 在建立或更新資料時，先執行所有連結與載入，再重新計算所有公式。
      若使用以上兩項參數並需要重新計算公式，請同時指定 doFormula=true。 |
      | doWorkflow | 指定 doWorkflow=true 告訴 Ragic API 執行與此 API 調用相關的 workflow。 |
      | notification | 指定 notification=true 告訴 Ragic API 向相關使用者發送通知，否則為 false。若未指定，預設為 true。 |
      | checkLock | 指定 checkLock=true 告訴 Ragic API 在更新前檢查資料是否被鎖定，如果資料被鎖定則不編輯。 |
  - name: writing-delete
    x-displayName: 刪除資料
    description: |
      刪除資料與讀取資料非常相似。你只需要將請求方法從 GET 更改為 **DELETE** 。當使用 DELETE 請求時，API 端點的資料將被刪除。

      ```bash
      curl -X DELETE \
      -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
      -d "api"  \
      https://www.ragic.com/demo/sales/1/3
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-06+at+6.53.07+PM.png)
  - name: writing-upload
    x-displayName: 上傳檔案及圖片
    description: >
      確保你的 content-type 是 **multipart/form-data** ，這樣你就可以上傳檔案。


      ```bash

      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",

      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-07+at+10.42.52+AM.png) 將滑鼠停留在方框區域上以顯示下拉選單，並選擇 "File" 來上傳檔案。 ![](https://www.ragic.com/sims/file.jsp?a=kb&f=Screen+Shot+2022-07-07+at+10.43.12+AM.png) 如果你想取得剛剛上傳的檔案，請按照[這裡的說明](https://www.ragic.com/intl/zh-TW/doc-api/14)操作。 如果想利用連結上傳檔案，首先下載檔案，然後按照上述說明操作。

      ```bash

      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** 。 你可以在[個人設定](https://www.ragic.com/intl/zh-TW/doc-user/20/personal-settings#4)取得你的 API 金鑰。
  - name: writing-comment
    x-displayName: 留言回應
    description: |
      請確保你的 content-type 是 **multipart/form-data** 。

      ```bash
      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
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=commentApi_20250213.png) 參數 **c** 為留言回應的內容(必填)，參數 **at** 為附件(選填)。 你可以在[個人設定](https://www.ragic.com/intl/zh-TW/doc-user/20/personal-settings#4)取得你的 API 金鑰。

      **回應範例：**

      ```json
      {
        "61": "2025/02/13 14:30",
        "65": "王小明",
        "66": "請檢查此訂單。",
        "67": "",
        "73": "1739425800000"
      }
      ```
       欄位 61 為格式化時間戳記，65 為留言者姓名，66 為留言內容，67 為附件檔名（無附件時為空），73 為原始時間戳記（毫秒）。
  - name: writing-import
    x-displayName: 從網址匯入
    description: >
      您必須為具備 **系統管理員 (SYSAdmin)** 權限，才能使用此 API。
      使用此API，需先啟動「[定期從網址匯入](https://www.ragic.com/intl/zh-TW/doc/73)」功能。完成相關設定後，即可透過下列 API 呼叫觸發匯入作業：


      ```bash

      curl -F "importData="

      -F "api=" \

      -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \

      https://www.ragic.com/demo/ragicsales-order-management/10001

      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=importData_api_postman.png) 當您需要**新增或修改大量資料** 時，也可透過此方式一次匯入，避免大量呼叫 API，提高效率。 你可以在[個人設定](https://www.ragic.com/intl/zh-TW/doc-user/20/personal-settings#4)取得你的 API 金鑰。

      **回應範例：**


      ```json

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

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

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


      ```bash
      curl -X POST https://www.ragic.com/demo/ragicforms23/10004/102?api&unlock
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=lock_unlock.png) 上鎖/解鎖 所需權限與從表單操作相同。 你可以在[個人設定](https://www.ragic.com/intl/zh-TW/doc-user/20/personal-settings#4)取得你的 API 金鑰。

      **回應範例：**

      ```json
      {
        "status": "SUCCESS",
        "code": 200
      }
      ```
  - name: writing-action
    x-displayName: 執行動作按鈕
    description: |
      要使用 Http API 執行動作按鈕，您需要取得 **動作按鈕 ID** 。 請使用 **GET** 方法發送以下請求：

      ```bash
      curl "https://{serverName}/{accountName}{path}/{sheetIndex}/metadata/actionButton?api&category=massOperation" \
        -H "Authorization: {Basic apiKey}"
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=getButtonIdAPI1.png) 取得 動作按鈕 ID 後，您即可使用 **POST** 方法發送以下請求，對指定資料執行該動作按鈕：

      ```bash
      curl -X POST "https://{serverName}/{accountName}{path}/{sheetIndex}/{recordId}?api&bId={buttonId}" \
        -H "Authorization: Basic apiKey"
      ```
       ![](https://www.ragic.com/sims/file.jsp?a=kb&f=actionButtonAPI.png) **提醒：** 除了執行目標動作按鈕的權限以外，您還需要**瀏覽目標資料的權限** ，才可以使用此 Http API。 你可以在[個人設定](https://www.ragic.com/intl/zh-TW/doc-user/20/personal-settings#4)取得你的 API 金鑰。

      **回應範例：**

      ```json
      {
        "status": "SUCCESS",
        "msg": "Action completed."
      }
      ```
  - name: error-responses
    x-displayName: API 請求錯誤回應
    description: |
      如果請求回傳錯誤，通常會顯示如下內容：

      ```json
      {
          "status": "ERROR",
          "code": 303,
          "msg": "Your account has expired."
      }
      ```
       以下是可能在 Ragic 請求中回傳的 HTTP 狀態代碼列表：

      | HTTP 狀態碼 | 描述 |
      | --- | --- |
      | 200 | OK - 一切正常。 |
      | 400 | Bad Request - 常見於缺少必需參數。 |
      | 401 | Unauthorized - 未提供有效的 API 金鑰。 |
      | 402 | 請求失敗 - 參數有效但請求失敗。 |
      | 404 | 未找到 - 請求的項不存在。 |
      | 500, 502, 503, 504 | 伺服器錯誤 - Ragic 端出現問題。 |

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

      | 錯誤代碼 | 錯誤描述 |
      | --- | --- |
      | 101 | 無效的帳號名稱：{Account_Name} |
      | 102 | 無效路徑：{Path} |
      | 103 | 無效表單索引：{Form_Index} |
      | 104 | 無法向自訂表單提交資料 |
      | 105 | 需要在使用 API 前進行身份驗證 |
      | 106 | 沒有訪問權限 |
      | 107 | 找不到資源包 |
      | 108 | 載入請求的表單時出錯 |
      | 109 | 無法建立更多資料 |
      | 201 | 處理請求參數時出錯 |
      | 202 | 執行請求時出錯 |
      | 203 | POST 請求未完成 |
      | 204 | 請求頻率過高 |
      | 301 | Sid 參數/會話已超時 |
      | 303 | 帳號已過期 |
      | 304 | 無效的金鑰 |
      | 402 | 資料已鎖定 |
      | 404 | 未找到資料 |
  - name: mass-operations
    x-displayName: 大量操作
    description: |
      大量操作 API 設計用來在單一請求中對表單中的多筆資料執行相同的操作。 有兩種指定要更新資料的方法：

        * 使用 [where](https://www.ragic.com/intl/zh-TW/doc-api/32)篩選

      ```
      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 允許一次鎖定或解鎖多筆資料。 [大量鎖定](https://www.ragic.com/intl/zh-TW/doc-user/64/batch-execute#2)

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

      {
          "action": <lock 或 unlock>
      }

      ==========

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


      ## 批次簽核

      批次簽核 API 允許一次同意或拒絕多筆資料的簽核。 [批次簽核](https://www.ragic.com/intl/zh-TW/doc-user/64/batch-execute#3)

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

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

      ==========

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


      ## 批次執行動作按鈕

      批次執行動作按鈕 API 允許一次執行多筆資料的按鈕。 [批次執行動作按鈕](https://www.ragic.com/intl/zh-TW/doc-user/64/batch-execute#1)

      ```
      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 允許一次更新多筆資料的欄位值。 [大量修改](https://www.ragic.com/intl/zh-TW/doc-user/5/mass-update-records#1)

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

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

      ==========

      回應
      {
          "taskId": "6dbc796a-07d5-475b-b578-d254eb30f7d2"
      }
      ```
       大量修改API也支持對 [內部使用者表單](https://www.ragic.com/intl/zh-TW/doc/3/internal-users) 與 [外部使用者表單](https://www.ragic.com/intl/zh-TW/doc/2/external-users) 進行修改，但使用上有一些限制。 以下欄位不開放大量修改：

        * 電子郵件(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` 欄位分別表示已處理、成功和失敗的資料筆數。
  - name: webhooks-about
    x-displayName: 什麼是 webhook
    description: >
      Webhook 是透過外部應用程式訂閱您的 Ragic 變更的一種方式。 透過訂閱這些變更，每當 Ragic 上發生變更時，Ragic 將調用您提供的 Webhook URL 來通知您變更的情況，包括被更改的資料 ID。 使用
      Webhook API 的最大優勢之一是，它在處理變更時效率更佳。不需要每隔幾小時輪詢 API 來檢查最新的變更情況。
  - name: webhooks-ragic
    x-displayName: 在 Ragic 中使用 Webhook
    description: >
      您可以在 Ragic 的工具列中的同步下方找到表單的 Webhook。 ![](https://www.ragic.com/sims/file.jsp?a=kb&f=_clipboard1588559009475.png) 關於
      webhook API 的一些注意事項： 它會在建立、更新和刪除時觸發。 它不是完全同步的，當負載較高時可能會有輕微延遲。 變更不包括對關聯工作表（如多版本）的更改。
      ![](https://www.ragic.com/sims/file.jsp?a=kb&f=_clipboard1682668318180.png) 點擊 “webhook” 功能並輸入應接收通知的
      URL，然後完成設定。您還可以選擇勾選「發送更改記錄的完整內容」來接收修改資料的完整資訊。要取消 webhook 設定，請點擊 webhook 視窗角落的 **X** 。 不帶完整內容的 JSON 格式如下：


      ```json

      [1, 2, 4]

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

      ```json

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

      ```
  - name: webhooks-signature
    x-displayName: Webhook簽章
    description: >
      ## 簽章的用途


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


      ## 驗證流程


      ### 1. 取得 string-to-sign


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


      ```javascript

      // 轉換前 (原始 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. 點擊 [這裡](https://www.ragic.com/api/http/getWebhookSignaturePublicKey.jsp?type=pem) 下載 PEM 檔。

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


      ## 其他注意事項

        * 若您使用私有主機版，或未啟用「發送更改記錄的完整內容」功能，Webhook 將不支援簽章驗證。
        * 請確保您的程式正確處理 JSON 序列化的一致性，否則會出現驗證錯誤。
x-tagGroups:
  - name: 使用 Ragic HTTP API
    tags:
      - introduction
  - name: 驗證
    tags:
      - auth-basic
      - auth-password
  - name: 讀取
    tags:
      - reading-format
      - reading-filter
      - reading-paging
      - reading-sorting
      - reading-callback
      - reading-naming
      - reading-other-params
      - reading-files
      - reading-exports
  - name: 寫入
    tags:
      - writing-create
      - writing-modify
      - writing-params
      - writing-delete
      - writing-upload
      - writing-comment
      - writing-import
      - writing-lock
      - writing-action
  - name: API 請求錯誤回應
    tags:
      - error-responses
  - name: 大量操作
    tags:
      - mass-operations
  - name: Webhooks
    tags:
      - webhooks-about
      - webhooks-ragic
      - webhooks-signature
paths:
  /{apname}/{path}/{sheetIndex}:
    get:
      operationId: listRecords
      tags:
        - reading-format
      parameters:
        - $ref: "#/components/parameters/apname"
        - $ref: "#/components/parameters/path"
        - $ref: "#/components/parameters/sheetIndex"
        - $ref: "#/components/parameters/where"
        - $ref: "#/components/parameters/fts"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/order"
        - $ref: "#/components/parameters/reverse"
        - $ref: "#/components/parameters/subtables"
        - $ref: "#/components/parameters/listing"
        - $ref: "#/components/parameters/naming"
        - $ref: "#/components/parameters/info"
        - $ref: "#/components/parameters/ignoreMask"
        - $ref: "#/components/parameters/ignoreFixedFilter"
        - $ref: "#/components/parameters/filterId"
        - $ref: "#/components/parameters/defaultFilter"
        - $ref: "#/components/parameters/bbcode"
        - $ref: "#/components/parameters/comment"
        - $ref: "#/components/parameters/history"
        - $ref: "#/components/parameters/approval"
        - $ref: "#/components/parameters/conversation"
        - $ref: "#/components/parameters/tz"
        - $ref: "#/components/parameters/version"
        - $ref: "#/components/parameters/v"
        - $ref: "#/components/parameters/taskId"
        - $ref: "#/components/parameters/api"
        - $ref: "#/components/parameters/callback"
      responses:
        "200":
          description: 成功取得資料列表
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecordList"
              examples:
                simpleList:
                  summary: 資料列表
                  value:
                    "12345":
                      "1000001": Acme Corp
                      "1000002": "2024-01-15"
                      "1000003": Active
                      _ragicId: 12345
                    "12346":
                      "1000001": Beta Inc
                      "1000002": "2024-01-16"
                      "1000003": Pending
                      _ragicId: 12346
                withSubtable:
                  summary: 包含子表格的資料
                  value:
                    "12345":
                      "1000001": "Order #001"
                      _ragicId: 12345
                      _subtable_1000010:
                        "67890":
                          "1000011": Widget A
                          "1000012": 5
                          "1000013": 100
                        "67891":
                          "1000011": Widget B
                          "1000012": 3
                          "1000013": 50
                withInfo:
                  summary: 包含中繼資料的資料（info=1）
                  value:
                    "12345":
                      "1000001": Sample Record
                      _ragicId: 12345
                      _seq: "001"
                      _create_date: "2024-01-15 10:30:00"
                      _create_user: user@example.com
                      _update_date: "2024-01-16 14:20:00"
                      _update_user: user@example.com
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: 讀取資料
      description: |
        從表單取得資料列表。

        回傳資料預設為 1000 筆。您可以使用 **limit** 與 **offset** 參數來指定要取回多少筆資料，以及要跳過多少筆資料。

        **範例：** 取得分頁資料
        ```bash
        curl -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
          "https://www.ragic.com/demo/sales/1?api&limit=50&offset=0"
        ```

        使用 `subtables=0` 參數來排除子表格資料以獲得較快的回應速度。

        ---

        ## 查詢任務進度

        當大量操作回傳 `taskId` 時，您可以透過在此端點加上 `taskId` 查詢參數來查詢進度。

        **範例：**
        ```bash
        curl -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
          "https://www.ragic.com/demo/sales/1?api&taskId=550e8400-e29b-41d4-a716-446655440000"
        ```

        **回應：**
        ```json
        {
          "status": "RUNNING",
          "progress": 45,
          "total": 100,
          "message": "處理資料中..."
        }
        ```

        當 `status` 為 `COMPLETED` 或 `FAILED` 時，表示任務已完成。
    post:
      operationId: createRecord
      tags:
        - writing-create
      parameters:
        - $ref: "#/components/parameters/apname"
        - $ref: "#/components/parameters/path"
        - $ref: "#/components/parameters/sheetIndex"
        - $ref: "#/components/parameters/doFormula"
        - $ref: "#/components/parameters/doDefaultValue"
        - $ref: "#/components/parameters/doLinkLoad"
        - $ref: "#/components/parameters/doWorkflow"
        - $ref: "#/components/parameters/notification"
        - $ref: "#/components/parameters/info"
        - $ref: "#/components/parameters/importData"
        - $ref: "#/components/parameters/tz"
        - $ref: "#/components/parameters/version"
        - $ref: "#/components/parameters/v"
        - $ref: "#/components/parameters/api"
        - $ref: "#/components/parameters/callback"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecordInput"
            examples:
              simpleCreate:
                summary: 建立簡單資料
                value:
                  "1000001": New Customer
                  "1000002": "2024-01-15"
                  "1000003": Active
              withSubtable:
                summary: 建立包含子表格列的資料
                value:
                  "1000001": New Order
                  _subtable_1000010:
                    "-1":
                      "1000011": Item A
                      "1000012": 2
                    "-2":
                      "1000011": Item B
                      "1000012": 5
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/RecordInputMultipart"
      responses:
        "200":
          description: 成功建立資料
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MutationResponse"
              examples:
                success:
                  summary: 建立成功
                  value:
                    status: SUCCESS
                    rv: "12345"
                    ragicId: 12345
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: 建立新資料
      description: |
        透過 API 而非 HTML 表單建立資料時，使用 POST 請求（而非 GET）到與讀取相同的端點。

        API 現在支援 JSON 資料，這是發送 HTTP 請求的建議方式。

        欄位 ID 作為參數名稱，想要的值作為值。使用者需要對表單有寫入權限才能使用此功能。

        如果欄位是**日期欄位**，值需要使用 **yyyy/MM/dd** 或 **yyyy/MM/dd HH:mm:ss**（包含時間時）的格式。

        **cURL 範例：**
        ```bash
        curl -F "1000001=新訂單" \
          -F "1000002=2024/01/15" \
          -F "api=" \
          -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
          https://www.ragic.com/demo/sales/1
        ```

        **JSON 格式：**
        ```json
        {
          "1000001": "新訂單",
          "1000002": "2024/01/15"
        }
        ```

        **包含子表格列：**
        同時填入子表格時，同一列的欄位值必須使用相同的負數列識別碼（任意負整數）。
        ```json
        {
          "1000001": "新訂單",
          "_subtable_1000010": {
            "-1": {"1000011": "品項 A", "1000012": 2},
            "-2": {"1000011": "品項 B", "1000012": 5}
          }
        }
        ```
  /{apname}/{path}/{sheetIndex}/{rootNodeId}:
    get:
      operationId: getRecord
      tags:
        - reading-format
      parameters:
        - $ref: "#/components/parameters/apname"
        - $ref: "#/components/parameters/path"
        - $ref: "#/components/parameters/sheetIndex"
        - $ref: "#/components/parameters/rootNodeId"
        - $ref: "#/components/parameters/subtables"
        - $ref: "#/components/parameters/naming"
        - $ref: "#/components/parameters/info"
        - $ref: "#/components/parameters/ignoreMask"
        - $ref: "#/components/parameters/bbcode"
        - $ref: "#/components/parameters/comment"
        - $ref: "#/components/parameters/history"
        - $ref: "#/components/parameters/approval"
        - $ref: "#/components/parameters/conversation"
        - $ref: "#/components/parameters/tz"
        - $ref: "#/components/parameters/version"
        - $ref: "#/components/parameters/v"
        - $ref: "#/components/parameters/api"
      responses:
        "200":
          description: 成功取得資料
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SingleRecord"
              examples:
                simpleRecord:
                  summary: 單筆資料
                  value:
                    "12345":
                      "1000001": Acme Corp
                      "1000002": "2024-01-15"
                      _ragicId: 12345
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: 取得單筆資料
      description: |
        透過 ID（rootNodeId）取得特定資料。

        **範例：** 取得資料 #12345
        ```bash
        curl -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
          "https://www.ragic.com/demo/sales/1/12345?api"
        ```
    post:
      operationId: updateRecord
      tags:
        - writing-modify
      parameters:
        - $ref: "#/components/parameters/apname"
        - $ref: "#/components/parameters/path"
        - $ref: "#/components/parameters/sheetIndex"
        - $ref: "#/components/parameters/rootNodeId"
        - $ref: "#/components/parameters/doFormula"
        - $ref: "#/components/parameters/doDefaultValue"
        - $ref: "#/components/parameters/doLinkLoad"
        - $ref: "#/components/parameters/doWorkflow"
        - $ref: "#/components/parameters/notification"
        - $ref: "#/components/parameters/checkLock"
        - $ref: "#/components/parameters/lock"
        - $ref: "#/components/parameters/unlock"
        - $ref: "#/components/parameters/bId"
        - $ref: "#/components/parameters/info"
        - $ref: "#/components/parameters/tz"
        - $ref: "#/components/parameters/version"
        - $ref: "#/components/parameters/v"
        - $ref: "#/components/parameters/api"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecordInput"
            examples:
              updateFields:
                summary: 更新指定欄位
                value:
                  "1000003": Completed
                  "1000004": "2024-01-20"
              addSubtableRow:
                summary: 新增子表格列
                value:
                  _subtable_1000010:
                    "-1":
                      "1000011": New Item
                      "1000012": 3
              deleteSubtableRow:
                summary: 刪除子表格列
                value:
                  DELSUB: "67890"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/RecordInputMultipart"
      responses:
        "200":
          description: 成功更新資料
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MutationResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: 修改資料
      description: |
        Ragic API 支援 POST、PUT 和 PATCH 方法來修改資料。當你編輯一筆資料時，你的端點需要額外的 record id 來指向確切的資料。

        你只需要提供你想要變更的欄位 ID。日期欄位需要使用 `yyyy/MM/dd` 或 `yyyy/MM/dd HH:mm:ss` 格式。

        **cURL 範例：**
        ```bash
        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/3
        ```

        **JSON 格式：**
        ```json
        {
          "2000123": "Dunder Mifflin",
          "2000127": "Jim Halpert"
        }
        ```

        **子表格修改：**
        對於子表格列，你必須從 API 回應中識別列 ID。格式使用 `fieldid_rowid` 符號。
        ```json
        {
          "_subtable_2000154": {
            "29": {
              "2000147": "Amy Tsai",
              "2000148": "資深專員"
            }
          }
        }
        ```

        **刪除子表格列：**
        使用 `DELSUB_[subtable_id]` 參數搭配列 ID：
        ```json
        {
          "_DELSUB_2000154": [3]
        }
        ```
        多筆刪除：`"_DELSUB_subtable_key": [row_id1, row_id2, ...]`
    delete:
      operationId: deleteRecord
      tags:
        - writing-delete
      parameters:
        - $ref: "#/components/parameters/apname"
        - $ref: "#/components/parameters/path"
        - $ref: "#/components/parameters/sheetIndex"
        - $ref: "#/components/parameters/rootNodeId"
        - $ref: "#/components/parameters/version"
        - $ref: "#/components/parameters/v"
        - $ref: "#/components/parameters/api"
      responses:
        "200":
          description: 成功刪除資料
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      summary: 刪除資料
      description: |
        透過 ID 刪除資料。

        **警告：** 此操作無法復原。

        **範例：**
        ```bash
        curl -X DELETE \
          -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
          "https://www.ragic.com/demo/sales/1/12345?api"
        ```
  /sims/file.jsp:
    get:
      operationId: getFile
      tags:
        - reading-files
      parameters:
        - name: a
          in: query
          required: true
          schema:
            type: string
          example: demo
        - name: f
          in: query
          required: true
          schema:
            type: string
          example: Ni92W2luv@My_Picture.jpg
      responses:
        "200":
          description: 檔案內容
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "404":
          $ref: "#/components/responses/NotFound"
      summary: 取得上傳檔案、圖片及 Email 附件
      description: |
        下載上傳的檔案、圖片或電子郵件附件。

        檔案參照在 JSON 回應中會以此格式出現：`"1000537": "Ni92W2luv@My_Picture.jpg"`

        實際檔案名稱跟在 "@" 字元後面，以避免命名衝突。

        **範例：** 下載檔案
        ```bash
        curl "https://www.ragic.com/sims/file.jsp?a=demo&f=Ni92W2luv@My_Picture.jpg"
        ```

        注意：檔案名稱作為參數傳送時必須進行 URL 編碼。
  /{apname}/{path}/{sheetIndex}/{rootNodeId}.xhtml:
    get:
      operationId: getRecordHtml
      tags:
        - reading-exports
      parameters:
        - $ref: "#/components/parameters/apname"
        - $ref: "#/components/parameters/path"
        - $ref: "#/components/parameters/sheetIndex"
        - $ref: "#/components/parameters/rootNodeId"
      responses:
        "200":
          description: HTML 友善列印版本
          content:
            text/html:
              schema:
                type: string
      summary: 取得 HTML 友善列印版本
      description: |
        在 URL 後方加入 `.xhtml` 取得該資料的 HTML 友善列印版本。

        **範例：**
        ```
        https://www.ragic.com/demo/sales/1/41.xhtml
        ```
  /{apname}/{path}/{sheetIndex}/{rootNodeId}.pdf:
    get:
      operationId: getRecordPdf
      tags:
        - reading-exports
      parameters:
        - $ref: "#/components/parameters/apname"
        - $ref: "#/components/parameters/path"
        - $ref: "#/components/parameters/sheetIndex"
        - $ref: "#/components/parameters/rootNodeId"
      responses:
        "200":
          description: 資料的 PDF 版本
          content:
            application/pdf:
              schema:
                type: string
                format: binary
      summary: 取得 PDF 版本
      description: |
        在 URL 後方加入 `.pdf` 來取得 PDF 版本。

        **範例：**
        ```
        https://www.ragic.com/demo/sales/1/41.pdf
        ```
  /{apname}/{path}/{sheetIndex}/{rootNodeId}.xlsx:
    get:
      operationId: getRecordExcel
      tags:
        - reading-exports
      parameters:
        - $ref: "#/components/parameters/apname"
        - $ref: "#/components/parameters/path"
        - $ref: "#/components/parameters/sheetIndex"
        - $ref: "#/components/parameters/rootNodeId"
      responses:
        "200":
          description: 資料的 Excel 版本
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
      summary: 取得 Excel 版本
      description: |
        在 URL 後方加入 `.xlsx` 來取得 Excel 版本。

        **範例：**
        ```
        https://www.ragic.com/demo/sales/1/41.xlsx
        ```
  /{apname}/{path}/{sheetIndex}/{rootNodeId}.custom:
    get:
      operationId: getRecordMailMerge
      tags:
        - reading-exports
      parameters:
        - $ref: "#/components/parameters/apname"
        - $ref: "#/components/parameters/path"
        - $ref: "#/components/parameters/sheetIndex"
        - $ref: "#/components/parameters/rootNodeId"
        - name: cid
          in: query
          required: true
          schema:
            type: integer
          example: 1
      responses:
        "200":
          description: 合併列印文件
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
      summary: 取得合併列印文件
      description: |
        在 URL 後方加入 `.custom` 和一個合併列印 CID 來取得資料的合併列印，以指定使用的範本。

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

        **範例：**
        ```
        https://www.ragic.com/demo/sales/1/41.custom?cid=1
        ```
  /{apname}/{path}/{sheetIndex}/metadata/actionButton:
    get:
      operationId: getActionButtonMetadata
      tags:
        - writing-action
      parameters:
        - $ref: "#/components/parameters/apname"
        - $ref: "#/components/parameters/path"
        - $ref: "#/components/parameters/sheetIndex"
        - name: category
          in: query
          required: false
          schema:
            type: string
            enum:
              - massOperation
        - $ref: "#/components/parameters/api"
      responses:
        "200":
          description: 成功取得動作按鈕清單
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionButtonList"
              examples:
                buttonList:
                  summary: 動作按鈕清單
                  value:
                    - id: btn_001
                      name: Send Notification
                    - id: btn_002
                      name: Generate Report
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: 取得動作按鈕中繼資料
      description: |
        取得表單上設定的動作按鈕清單。

        使用選填參數 `category=massOperation` 來篩選支援大量操作的按鈕。

        **範例：**
        ```bash
        curl -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
          "https://www.ragic.com/demo/sales/1/metadata/actionButton?api"
        ```

        **篩選大量操作按鈕：**
        ```bash
        curl -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
          "https://www.ragic.com/demo/sales/1/metadata/actionButton?api&category=massOperation"
        ```

        **回應：**
        ```json
        [
          {"id": "btn_001", "name": "發送通知"},
          {"id": "btn_002", "name": "產生報表"}
        ]
        ```
  /{apname}/{path}/{sheetIndex}/massOperation/{operationType}:
    post:
      operationId: executeMassOperation
      tags:
        - mass-operations
      parameters:
        - $ref: "#/components/parameters/apname"
        - $ref: "#/components/parameters/path"
        - $ref: "#/components/parameters/sheetIndex"
        - name: operationType
          in: path
          required: true
          schema:
            type: string
            enum:
              - massUpdate
              - massSearchReplace
              - massLock
              - massApproval
              - massActionButton
        - $ref: "#/components/parameters/where"
        - name: recordId
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - $ref: "#/components/parameters/api"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            examples:
              massUpdate:
                summary: 大量更新欄位
                value:
                  "1000001": New Value
                  "1000002": 2024/06/01
              massSearchReplace:
                summary: 大量搜尋取代
                value:
                  fieldId: "1000001"
                  search: old text
                  replace: new text
              massLock:
                summary: 大量鎖定資料
                value:
                  lock: true
              massApproval:
                summary: 大量簽核
                value:
                  action: approve
              massActionButton:
                summary: 大量執行動作按鈕
                value:
                  bId: btn_001
      responses:
        "200":
          description: 已接受大量操作
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MassOperationResponse"
              examples:
                accepted:
                  summary: 操作已接受
                  value:
                    taskId: 550e8400-e29b-41d4-a716-446655440000
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      summary: 執行大量操作
      description: |
        對多筆資料同時執行批次操作。所有大量操作都是非同步的，會回傳一個 `taskId` 供查詢進度使用。

        **資料選取：** 使用 `where` 查詢參數或 `recordId` 查詢參數來選取要操作的資料。

        **操作類型：**

        ### massUpdate
        批次更新多筆資料的欄位值。
        ```json
        {
          "1000001": "新值",
          "1000002": "2024/06/01"
        }
        ```

        ### massSearchReplace
        在多筆資料中搜尋欄位文字並取代。
        ```json
        {
          "fieldId": "1000001",
          "search": "舊文字",
          "replace": "新文字"
        }
        ```

        ### massLock
        批次鎖定或解鎖多筆資料。
        ```json
        {"lock": true}
        ```

        ### massApproval
        批次簽核或退回多筆資料。
        ```json
        {"action": "approve"}
        ```

        ### massActionButton
        對多筆資料執行動作按鈕。
        ```json
        {"bId": "btn_001"}
        ```

        **回應：**
        ```json
        {"taskId": "550e8400-e29b-41d4-a716-446655440000"}
        ```

        使用 `taskId` 搭配「讀取資料」端點來查詢進度。
  /AUTH:
    get:
      operationId: passwordAuth
      tags:
        - auth-password
      security: []
      parameters:
        - name: u
          in: query
          required: true
          schema:
            type: string
          example: user@example.com
        - name: p
          in: query
          required: true
          schema:
            type: string
          example: password123
        - name: login_type
          in: query
          required: false
          schema:
            type: string
            enum:
              - sessionId
        - name: json
          in: query
          required: false
          schema:
            type: integer
            enum:
              - 1
        - name: api
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: 認證成功
          content:
            text/plain:
              schema:
                type: string
              examples:
                sessionId:
                  summary: 工作階段 ID 回應
                  value: abc123def456
            application/json:
              schema:
                $ref: "#/components/schemas/AuthResponse"
              examples:
                jsonResponse:
                  summary: JSON 回應（json=1）
                  value:
                    status: SUCCESS
                    sid: abc123def456
                    email: user@example.com
                    accounts:
                      - myaccount
                      - otheraccount
        "401":
          $ref: "#/components/responses/Unauthorized"
      summary: 密碼認證
      description: |
        使用電子郵件與密碼認證使用者以取得工作階段 ID。這是次要的認證方式；**大多數情況下建議使用 HTTP Basic Auth 搭配 API 金鑰**。

        此端點不需要認證標頭 — 這本身就是認證端點。

        **基本用法（回傳純文字工作階段 ID）：**
        ```bash
        curl "https://www.ragic.com/AUTH?u=user@example.com&p=mypassword&api"
        ```

        **JSON 回應（包含帳號清單）：**
        ```bash
        curl "https://www.ragic.com/AUTH?u=user@example.com&p=mypassword&json=1&api"
        ```

        **JSON 回應：**
        ```json
        {
          "status": "SUCCESS",
          "sid": "abc123def456",
          "email": "user@example.com",
          "accounts": ["myaccount", "otheraccount"]
        }
        ```

        **使用工作階段 ID：** 將回傳的工作階段 ID 作為 Cookie（`JSESSIONID`）傳送，或使用 `login_type=sessionId` 直接取得以工作階段為基礎的 Cookie。
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: |
        使用您的電子郵件與 API 金鑰進行 HTTP Basic 認證。
        API 金鑰可從帳號設定 > API 取得。
    apiKey:
      type: apiKey
      in: query
      name: api
      description: |
        以查詢參數傳遞 API 金鑰。
        安全性較低；僅在必要時使用。
    sessionAuth:
      type: apiKey
      in: cookie
      name: JSESSIONID
      description: |
        使用從 /AUTH 端點取得的 JSESSIONID Cookie 進行工作階段認證。
        大多數整合請使用 HTTP Basic Auth 搭配 API 金鑰。
  parameters:
    apname:
      name: apname
      in: path
      required: true
      schema:
        type: string
        example: myaccount
      description: 您的帳號名稱（網址中的子網域，例如 www.ragic.com/demo/... 中的 "demo"）
    path:
      name: path
      in: path
      required: true
      schema:
        type: string
        example: sales
      description: 網址中的資料夾路徑（例如 "sales" 或 "hr/employees"）
    sheetIndex:
      name: sheetIndex
      in: path
      required: true
      schema:
        type: integer
        example: 1
      description: 網址中的表單編號（資料夾路徑後面的數字）
    rootNodeId:
      name: rootNodeId
      in: path
      required: true
      schema:
        type: integer
        example: 12345
      description: 網址中的資料 ID（查看單筆資料時顯示）
    where:
      name: where
      in: query
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          type: string
      examples:
        equals:
          summary: 等於篩選
          value:
            - 1000001,eq,Active
        multipleFilters:
          summary: 多重篩選（AND）
          value:
            - 1000001,eq,Active
            - 1000002,gt,100
        contains:
          summary: 包含（LIKE）
          value:
            - 1000001,lk,Corp
        dateRange:
          summary: 日期區間
          value:
            - 1000002,range,2024/01/01~2024/12/31
      description: >
        篩選條件，使用逗號分隔的參數。格式：`欄位ID,運算子,值`


        **可用運算子：**

        - `eq` - 等於

        - `regex` - 正規表示式

        - `gte` - 大於或等於

        - `lte` - 小於或等於

        - `gt` - 大於

        - `lt` - 小於

        - `like` - 包含

        - `eqeq` - 依內部資料 ID 精確比對（進階功能，極少使用）


        對同一欄位使用多個 "eq"、"regex" 或 "like" 條件會執行 OR 運算。

        對同一欄位組合 gte/gt 和 lte/lt 條件會執行 AND 運算（適合日期區間）。


        日期/日期時間值必須使用格式：`yyyy/MM/dd` 或 `yyyy/MM/dd HH:mm:ss`


        **篩選空值：** 第三個參數留空，例如 `where=2000127,eq,`


        **篩選值中有逗號** 需要 URL 編碼（`%2C`）


        **雙重 URL 編碼：** 如果篩選值包含 `%` 後接十六進位字元（例如 `%20`），`%` 必須雙重 URL 編碼為 `%25`，以避免伺服器將其誤判為已編碼的字元。例如，要搜尋文字 `100%`，請編碼為
        `100%2525`。


        **範例：** `where=2000123,eq,Alphabet Inc.`
    fts:
      name: fts
      in: query
      required: false
      schema:
        type: string
        example: search term
      description: |
        跨所有可搜尋欄位的關鍵字全文搜尋。

        **範例：** `fts=搜尋關鍵字`
    limit:
      name: limit
      in: query
      required: false
      schema:
        type: string
      examples:
        countOnly:
          summary: 前 N 筆資料
          value: "50"
        offsetAndCount:
          summary: 跳過後取得
          value: 100,50
      description: |
        指定要取回多少筆資料。

        回傳資料預設為 1000 筆，如果需要回傳超過 1000 筆資料，需要提供 limit 參數。

        **範例：** `limit=50` - 回傳 50 筆資料
    offset:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        example: 0
      description: |
        指定要跳過多少筆資料。

        與 limit 一起使用來分頁。例如，要跳過前 5 筆並回傳第 6-13 筆（共 8 筆資料）：`limit=8&offset=5`
    order:
      name: order
      in: query
      required: false
      schema:
        type: string
      examples:
        ascending:
          summary: 升冪排列
          value: 1000001,ASC
        descending:
          summary: 降冪排列
          value: 1000001,DESC
      description: |
        排序方式。格式：`欄位ID,ASC` 或 `欄位ID,DESC`

        預設情況下，資料按建立日期和時間排序，從最舊到最新。

        **範例：** `order=800236,DESC` - 依欄位 800236 降冪排列
    subtables:
      name: subtables
      in: query
      required: false
      schema:
        type: string
        default: "1"
      description: |
        在回應中包含子表格資料。
        - `1`（預設）- 包含子表格
        - `0` - 不含子表格（大量資料時回應較快）
    listing:
      name: listing
      in: query
      required: false
      schema:
        type: string
      description: |
        僅回傳在表單列表檢視中可見的欄位（在 Ragic 瀏覽資料時顯示的欄位）。適合用於建立表格/列表介面，不需要所有欄位時使用——回應更小、速度更快。
        - 未設定（預設）- 完整資料（所有欄位）
        - `1` - 僅列表檢視欄位
    naming:
      name: naming
      in: query
      required: false
      schema:
        type: string
        enum:
          - EID
          - FNAME
      description: |
        選擇回應 JSON key 中欄位的命名方式。
        - `EID`（預設）- 使用數字欄位 ID（如 `"1000001": "範例公司"`）。建議用於整合，因為 ID 不會變動。
        - `FNAME` - 使用可讀的欄位名稱（如 `"客戶名稱": "範例公司"`）。適合除錯，但若欄位名稱包含特殊字元或被重新命名時可能出錯。
    info:
      name: info
      in: query
      required: false
      schema:
        type: string
      description: |
        包含資料的中繼資料（誰建立/修改了資料，以及何時）。適用於稽核記錄或資料同步。
        - 未設定（預設）- 僅欄位值
        - `1` - 同時包含 `_create_date`、`_create_user`、`_update_date`、`_update_user`、`_seq`（自動產生的序號）
    ignoreMask:
      name: ignoreMask
      in: query
      required: false
      schema:
        type: string
      description: |
        Ragic 中某些欄位可設定為遮罩敏感資料（例如電話號碼顯示為 `***-**1234`）。此參數可顯示完整的未遮罩值。需要適當權限。
        - 未設定（預設）- 套用欄位遮罩
        - `1` - 顯示未遮罩值
    filterId:
      name: filterId
      in: query
      required: false
      schema:
        type: integer
      description: |
        套用指定 ID 的已儲存篩選器。已儲存的篩選器是在 Ragic 介面中建立的預設搜尋條件（可從任何表單的篩選器下拉選單存取）。使用此參數取代複雜的 `where` 參數。
    defaultFilter:
      name: defaultFilter
      in: query
      required: false
      schema:
        type: string
      description: |
        套用表單的預設篩選器（由表單設計者在表單設定中配置的預設篩選條件）。回傳結果與使用者在 Ragic 介面中預設看到的篩選結果相同。
        - 未設定（預設）- 不套用預設篩選器
        - `1` - 套用預設篩選器
    comment:
      name: comment
      in: query
      required: false
      schema:
        type: string
      description: |
        包含附加到每筆資料的評論/備註討論串。評論是使用者透過 Ragic 介面新增的討論記錄。
        - 未設定（預設）- 不含評論
        - `1` - 在回應中包含評論
    history:
      name: history
      in: query
      required: false
      schema:
        type: string
      description: |
        包含每筆資料的欄位變更歷史記錄——誰在何時更改了哪個欄位，以及舊值/新值。適用於稽核追蹤。
        - 未設定（預設）- 不含歷史記錄
        - `1` - 包含修改歷史
    approval:
      name: approval
      in: query
      required: false
      schema:
        type: string
      description: |
        包含簽核流程狀態。Ragic 的簽核功能可讓您設定多步驟的資料審核流程。此參數回傳目前的簽核狀態、簽核人員清單和簽核歷史。
        - 未設定（預設）- 不含簽核資訊
        - `1` - 包含簽核狀態與歷史
    conversation:
      name: conversation
      in: query
      required: false
      schema:
        type: string
      description: |
        包含與資料相關聯的電子郵件對話串。當資料有相關的郵件討論串（透過 Ragic 的郵件功能），此參數會回傳那些訊息。
        - 未設定（預設）- 不含對話
        - `1` - 包含對話訊息
    tz:
      name: tz
      in: query
      required: false
      schema:
        type: number
        example: -8
      description: |
        日期/時間欄位的時區偏移量（小時）。

        **範例：** `tz=8` 代表 UTC+8（台北時間）

        回應中的日期值將依此時區調整。
    api:
      name: api
      in: query
      required: false
      schema:
        type: string
      description: |
        用於認證的 API 金鑰（替代 HTTP Basic Auth）。

        **範例：** `api=YOUR_API_KEY`
    callback:
      name: callback
      in: query
      required: false
      schema:
        type: string
      description: |
        JSONP 回呼函數名稱。加入回呼函數參數會將回傳的 JSON 物件包裝為您指定的回呼函數的參數。當您使用 Javascript 存取我們的 API 進行跨網域 ajax 呼叫時，這特別有用。

        **範例：** `callback=testFunc`

        回應將包裝為：`testFunc({"17": {"Account Name": "Dunder Mifflin", ...}});`
    doFormula:
      name: doFormula
      in: query
      required: false
      schema:
        type: string
        enum:
          - "true"
          - "false"
        default: "false"
      description: |
        儲存後執行公式。
        - `false`（API 預設）- 跳過公式執行
        - `true` - 執行公式（可能影響效能）
    doDefaultValue:
      name: doDefaultValue
      in: query
      required: false
      schema:
        type: string
        enum:
          - "true"
          - "false"
        default: "false"
      description: |
        為空白欄位套用預設值。
        - `false`（API 預設）- 跳過預設值
        - `true` - 套用設定的預設值
    doLinkLoad:
      name: doLinkLoad
      in: query
      required: false
      schema:
        type: string
        enum:
          - "true"
          - "false"
          - first
        default: "false"
      description: |
        執行「連結載入」操作。在 Ragic 中，連結載入會自動從連結的資料複製欄位值到目前資料（例如選擇客戶後自動帶入地址）。API 預設跳過此操作以提升效能。
        - `false`（API 預設）- 跳過連結載入
        - `true` - 對所有連結欄位執行連結載入
        - `first` - 僅對第一個連結欄位執行連結載入
    doWorkflow:
      name: doWorkflow
      in: query
      required: false
      schema:
        type: string
        enum:
          - "true"
          - "false"
        default: "true"
      description: |
        觸發工作流程動作（前置工作流程、後置工作流程）。
        - `true`（預設）- 觸發工作流程
        - `false` - 跳過工作流程執行
    notification:
      name: notification
      in: query
      required: false
      schema:
        type: string
        enum:
          - "true"
          - "false"
        default: "true"
      description: |
        發送通知（電子郵件、簽核通知）。
        - `true`（預設）- 發送通知
        - `false` - 跳過所有通知
    reverse:
      name: reverse
      in: query
      required: false
      schema:
        type: string
        enum:
          - "true"
      description: |
        反轉列表頁面回應的預設排序。

        要取得最新的資料在前，使用 `reverse=true`

        **範例：** `reverse=true`
    bbcode:
      name: bbcode
      in: query
      required: false
      schema:
        type: string
        enum:
          - "true"
      description: |
        Ragic 富文字欄位以 BBCode 語法儲存格式（例如 `[b]粗體[/b]`）。預設情況下 API 會將其轉換為 HTML。使用此參數可取得原始 BBCode。
        - 未設定（預設）- 回傳 HTML 格式內容
        - `true` - 回傳原始 BBCode 格式
    ignoreFixedFilter:
      name: ignoreFixedFilter
      in: query
      required: false
      schema:
        type: string
        enum:
          - "true"
      description: |
        固定篩選器是由表單設計者設定的永久篩選條件，限制所有使用者可看到的資料（例如「只顯示有效客戶」）。此參數可略過固定篩選器。需要系統管理員權限。
        - 未設定（預設）- 套用固定篩選器
        - `true` - 忽略固定篩選器
    checkLock:
      name: checkLock
      in: query
      required: false
      schema:
        type: string
        enum:
          - "true"
      description: |
        在更新前檢查資料是否已上鎖，如果已上鎖則不編輯資料。
        - 未設定（預設）- 無論上鎖狀態都更新
        - `true` - 更新前檢查上鎖狀態
    version:
      name: version
      in: query
      required: false
      schema:
        type: string
      example: "2025-01-01"
      description: |
        使用日期格式的 API 版本（建議）。格式：`YYYY-MM-DD`

        使用版本控制可確保您的整合在 Ragic 引入重大變更時保持穩定。API 會依據您指定的版本運作。

        **範例：** `version=2025-01-01`
    v:
      name: v
      in: query
      required: false
      schema:
        type: integer
        enum:
          - 1
          - 2
          - 3
      description: |
        舊版 API 版本號碼。新的整合請改用 `version` 參數。
        - `1` - 版本 1
        - `2` - 版本 2
        - `3` - 版本 3（最新舊版）
    lock:
      name: lock
      in: query
      required: false
      allowEmptyValue: true
      schema:
        type: string
      description: |
        鎖定資料以防止其他使用者編輯。以 POST 請求搭配此參數送至資料端點。不需要請求內容。

        **範例：** `POST /demo/sales/1/12345?api&lock`
    unlock:
      name: unlock
      in: query
      required: false
      allowEmptyValue: true
      schema:
        type: string
      description: |
        解鎖先前已鎖定的資料。以 POST 請求搭配此參數送至資料端點。不需要請求內容。

        **範例：** `POST /demo/sales/1/12345?api&unlock`
    bId:
      name: bId
      in: query
      required: false
      schema:
        type: string
      description: |
        對資料執行動作按鈕。傳入從「動作按鈕中繼資料」端點取得的按鈕 ID。

        **範例：** `POST /demo/sales/1/12345?api&bId=btn_001`
    importData:
      name: importData
      in: query
      required: false
      allowEmptyValue: true
      schema:
        type: string
      description: |
        從 URL 匯入資料至表單。需要系統管理員權限。

        **範例：** `POST /demo/sales/1?api&importData`
    taskId:
      name: taskId
      in: query
      required: false
      schema:
        type: string
        format: uuid
      description: |
        查詢非同步大量操作的進度。傳入大量操作端點回傳的任務 ID。

        **範例：** `GET /demo/sales/1?api&taskId=550e8400-e29b-41d4-a716-446655440000`
  schemas:
    RecordList:
      type: object
      additionalProperties:
        $ref: "#/components/schemas/RecordData"
      description: 以 rootNodeId 為鍵值的資料集合
    SingleRecord:
      type: object
      additionalProperties:
        $ref: "#/components/schemas/RecordData"
      description: 以 rootNodeId 為鍵值的單筆資料
    RecordData:
      type: object
      properties:
        _ragicId:
          type: integer
          readOnly: true
        _seq:
          type: string
          readOnly: true
        _create_date:
          type: string
          format: date-time
          readOnly: true
        _create_user:
          type: string
          readOnly: true
        _update_date:
          type: string
          format: date-time
          readOnly: true
        _update_user:
          type: string
          readOnly: true
      additionalProperties:
        oneOf:
          - type: string
          - type: number
          - type: object
          - type: array
            items:
              type: string
      description: |
        以欄位 ID 為鍵值的資料。

        **系統欄位（使用 `info=1` 時為唯讀）：**
        - `_ragicId` - 資料 ID（同 rootNodeId）
        - `_seq` - 流水號（自動產生）
        - `_create_date` - 建立時間
        - `_create_user` - 建立者電子郵件
        - `_update_date` - 最後更新時間
        - `_update_user` - 最後更新者電子郵件

        **子表格：**
        子表格資料以 `_subtable_{欄位ID}` 為鍵值，內含子表格列 ID 作為巢狀鍵值。
    RecordInput:
      type: object
      additionalProperties:
        oneOf:
          - type: string
          - type: number
          - type: object
          - type: array
            items:
              type: string
      description: |
        用於新增/更新操作的資料。

        使用欄位 ID 作為鍵值，欄位值作為值。

        **子表格格式：**
        ```json
        {
          "_subtable_1000010": {
            "-1": {"1000011": "品項 1", "1000012": 5},
            "-2": {"1000011": "品項 2", "1000012": 3}
          }
        }
        ```
        新列使用負數 ID（-1、-2 等）。

        **刪除子表格列：**
        ```json
        {"DELSUB": "67890"}
        ```
    RecordInputMultipart:
      type: object
      properties:
        file:
          type: string
          format: binary
      additionalProperties:
        type: string
    MutationResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - SUCCESS
            - ERROR
        rv:
          type: string
        ragicId:
          type: integer
        msg:
          type: string
        warning:
          type: string
      description: 新增/更新操作的回應
    DeleteResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - SUCCESS
            - ERROR
      description: 刪除操作的回應
    FormDefinition:
      type: object
      properties:
        sheetIndex:
          type: integer
        sheetName:
          type: string
        path:
          type: string
        fields:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/FieldDefinition"
      description: |
        表單結構與欄位定義。

        包含欄位 ID、名稱、類型、選項（選擇欄位）及其他中繼資料。
    FieldDefinition:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
        inputType:
          type: string
        required:
          type: boolean
        options:
          type: array
          items:
            type: object
            properties:
              v:
                type: string
      description: |
        個別欄位定義。

        **常見類型：**
        - `D` - 文字/預設
        - `L` - 單選
        - `M` - 多選
        - `U` - 檔案上傳
        - `G` - 圖片/圖形
    ActionButtonList:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
          name:
            type: string
      description: |
        表單上設定的動作按鈕清單。每個按鈕包含 `id`（用於 `bId` 參數）和 `name`（顯示名稱）。
    MassOperationResponse:
      type: object
      properties:
        taskId:
          type: string
          format: uuid
      description: |
        大量操作請求的回應。包含 `taskId`，可用於透過「讀取資料」端點搭配 `taskId` 參數查詢操作進度。
    TaskProgress:
      type: object
      properties:
        status:
          type: string
          enum:
            - RUNNING
            - COMPLETED
            - FAILED
        progress:
          type: integer
        total:
          type: integer
        message:
          type: string
      description: |
        非同步大量操作的進度資訊。
        - `status` - 目前狀態：`RUNNING`、`COMPLETED` 或 `FAILED`
        - `progress` - 已處理的資料筆數
        - `total` - 總共要處理的資料筆數
        - `message` - 人類可讀的狀態訊息
    AuthResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - SUCCESS
            - ERROR
        sid:
          type: string
        email:
          type: string
        accounts:
          type: array
          items:
            type: string
      description: |
        /AUTH 端點的 JSON 回應（使用 `json=1` 時）。
        - `status` - `SUCCESS` 或 `ERROR`
        - `sid` - 後續請求使用的工作階段 ID
        - `email` - 已認證使用者的電子郵件
        - `accounts` - 使用者可存取的 Ragic 帳號清單
    Error:
      type: object
      properties:
        status:
          type: string
          enum:
            - ERROR
        errorCode:
          type: integer
        msg:
          type: string
      description: 包含錯誤碼與訊息的錯誤回應
  responses:
    BadRequest:
      description: 錯誤的請求 - 無效的參數或資料
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            invalidJson:
              summary: 無效的 JSON 內容
              value:
                status: ERROR
                errorCode: 102
                msg: Invalid JSON post body.
            validationError:
              summary: 驗證錯誤
              value:
                status: ERROR
                errorCode: 103
                msg: "Validation failed: Field 'Customer Name' is required."
    Unauthorized:
      description: 需要認證 - 請提供有效的憑證
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            noAuth:
              summary: 未提供認證
              value:
                status: ERROR
                errorCode: 101
                msg: Authentication required. Please provide API key.
            invalidAuth:
              summary: 無效的憑證
              value:
                status: ERROR
                errorCode: 101
                msg: Invalid API key or password.
    Forbidden:
      description: 存取被拒絕 - 此操作權限不足
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            noAccess:
              summary: 無法存取此表單
              value:
                status: ERROR
                errorCode: 106
                msg: >-
                  This sheet is access right protected. You will need to provide an API key of a user who has access
                  right to this sheet.
    NotFound:
      description: 找不到資源 - 請檢查 URL 與資料 ID
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            recordNotFound:
              summary: 找不到資料
              value:
                status: ERROR
                errorCode: 104
                msg: The record you are updating is not found.
            sheetNotFound:
              summary: 找不到表單
              value:
                status: ERROR
                errorCode: 105
                msg: Sheet not found.

