「支援 API 串接」

在 SaaS 的產品型錄或業務簡報裡，幾乎天天都會看到這句話。

然而，真正導入之後，資訊系統部門或內部系統工程師從現場接到的，卻常是這樣的抱怨：

「明明說好可以用 API 自動化，結果每個月還是得打開畫面手動輸入，這件事怎樣都消不掉」

為什麼「有 API」卻還是留下手工作業？現場業務到底能被 API 救到幾成？

答案不在型錄裡那句抽象的「串接」二字，而是在於必須實際做過一項一項的欄位名稱對照，才能明白。

編輯部以已完成初步調查的公開 82 個系統為對象，從 API 處理的 922 筆資料對象之 CRUD 比例，到Money Forward Cloud 發票（450 項）以及會計（890 項）的全畫面欄位 × API request schema 的逐項對照，甚至連通訊限制與方案限制都納入，從第一手資料做了徹底的實測。

從中浮現的，是現場前方依序立著 3 道牆的結構。「有 API」與「可以串接」都不等於「業務上真的能用」。

跨過第一道，還有第二道；跨過第二道，還有第三道。即使跨過 3 道牆，後面還有速率限制與方案限制這2 道會讓運作停擺的障礙。本文將依序說明這 3＋2 的全貌。

先講結論：「API 能救到幾成」沒有產品層級的唯一答案。 就算是同一家廠商的產品，後面會看到發票是 72.2%，會計是 17.5%，差距非常大；而且會計若只看 API 鎖定的「傳票」相關範圍，則會一下跳到 81.5%。真正影響結果的不是產品名稱，而是你想自動化的業務，是否位於該 API 所對應的物件內部。

請看上圖。這是在從銷售管理系統把銷售資料傳到會計系統時，現場會發生的「4 種不一致」。

如果只是像「客戶名稱」和「往來廠商名稱」這樣名稱不同，程式還能轉換。但若像「客戶 ID」與「往來代碼」那樣編號規則不同，或是需要做「含稅／未稅」的換算，最糟的情況則是像「負責人」這種接收端系統根本沒有該欄位的案例。

當現場因為聽到「有 API」而放心時，為什麼還是會掉進手動輸入的陷阱？以下就用實測數據與圖表，一步步拆解整個故事。

1. 「有 API」的現實 —— 能不能讀得到可以確認；能不能寫入卻無法僅靠規格書確認

第一道牆，是「有 API」這句話本身的真實樣貌。

上圖是針對公開 82 個系統〔v2 §0〕中可確認 API 規格的 41 系列、合計 922 個資料對象（object），統計其 CRUD（取得・建立・更新・刪除）操作別的「有支援」件數與比例〔v2 §1〕。

從長條圖一眼就能看出，API 能做到的事當中，91.6%（845 筆）都只是讀取「Read（取得）」，也就是把清單或明細資料讀出來〔v2 §1〕。若用途是從外部撈資料來做彙整報表或儀表板，大多數系統的 API 都能如預期運作。

但一旦把目光轉向現場最期待的「從其他系統匯入資料（Create），並更新狀態、做沖銷（Update）」這種業務，情況就完全不同了。

可以從外部新增紀錄的 Create 只剩 56.7%（523 筆），而能改寫既有資料的 Update 更降到 41.8%（385 筆）〔v2 §1〕。

這裡要精準說明：並不是確認剩下那些就「不能寫」。編輯部的台帳中，無法確認 Create 的 399 筆、無法確認 Update 的 537 筆，全部都只記錄為「從公開規格無法判定」〔v2 §1〕。我們調查範圍內，沒有任何一筆是廠商明言「不提供寫入」的對象。

也就是說，「可讀」能從公開規格確認，但「可寫」卻有一半以上無法僅靠規格書判定。 即使標榜「公開 API」，從規格書能看出的通常也只是讀取端（GET）是否開放；你自己想寫入的對象有沒有寫入端，很多時候要問廠商才知道。也就是說，在稟議階段無法自行判斷——這就是第一道牆。

2. 「可以串接」的非對稱性 —— 78.0% 的系統都踩著「只能讀」與「能寫入」的落差陷阱

第二道牆，是系統內部「串接方向的非對稱性」。

上圖顯示的是，在擁有 API 的 41 系列中，「只能讀的對象」與「可以寫的對象」是如何交錯存在的。根據實測，41 系列之中有 32 系列（78.0%）同時包含「只能讀的對象」與「可寫的對象」〔v2 §2〕。

從各系統的長條圖可見，即便是同一個產品的 API，不同對象可做的操作也完全不同。

• JINJER：共 156 個對象中，員工資訊與歷史等「只能讀」占 98 筆，而「可寫」僅 58 筆〔v2 §2〕。
• KING OF TIME：共 24 個對象中，打卡等「可寫」只有 6 筆，其餘 18 筆都是「只能讀」〔v2 §2〕。
• Money Forward Cloud 經費：共 34 個對象中，設定與主檔等 19 筆是「只能讀」，而經費申請等「可寫」為 15 筆〔v2 §2〕。
• Jobcan 會計：公開 API 的 4 個對象全部都是「只能讀」，在公開規格中找不到可從外部寫入傳票的入口〔v2 §2〕。

也就是說，多數業務系統都具有「主檔與歷史資料可讀，但單據無法從外部投入」，或者反過來「單據能送入，但前提主檔無法用 API 建立，仍必須手動」這種單邊運作的結構。

若沒有先確認自己要自動化的業務是屬於「寫入端」還是「讀取端」，就直接相信「可串接」這個詞，開發設計階段一定會撞牆。

3. 「業務上能用」的驗證① —— Money Forward Cloud 發票（450 項中，業務輸入 79 項的真相）

而第 3 道，也是最核心的一道牆，就是「是否真的能在業務上使用」的欄位粒度。

編輯部將日本國內代表性 SaaS「Money Forward Cloud 發票」的全畫面欄位與 API 規格逐條比對。

將官方指南中列出的 450 個畫面欄位逐一檢視後，可分成圖上方所示的 5 類〔v2 §4〕。扣除像小計與消費稅額這類自動計算（Cat-2：97 筆）、按鈕與搜尋等 UI 操作（Cat-3：62 筆）、自家帳戶等初始設定（Cat-4：126 筆）、以及在其他畫面重複登載的項目（Cat-5：86 筆）後，需要從外部系統逐次傳遞的「Cat-1 業務輸入欄位」只有 79 項（占整體 17.6%）〔v2 §4〕。

將這 79 項與 OpenAPI 規格書（raw/mf_invoice_openapi_v3.yaml）對照後，得到圖中段的結果〔v2 §4〕。

• ○ 完全（可直接用 API 寫入）：43 項（54.4%）〔v2 §4〕
• △ 有限制（需要先取得內部 ID 等）：14 項（17.7%）〔v2 §4〕
• × 無法傳遞（API 沒有可寫入的屬性）：22 項（27.8%）〔v2 §4〕

透過 API 的覆蓋率，若只看完全可傳遞的 ○，是 54.4%；若把有限制的 △ 也算進去，則為 72.2%〔v2 §4〕。

這裡補充一個重要事實。只看 components.schemas 的話，很容易誤讀成「收件方電子郵件、CC、負責人、客戶代碼都不能透過 API 登錄」，編輯部在初期調查時也曾這樣看錯。不過，仔細檢視 OpenAPI 原始檔的 requestBodies 後，可以確認 DepartmentCreateRequest（部門建立）裡網羅了 email, cc_emails, person_name, peppol_id 等欄位，而 PartnerCreateRequest 也存在 code（客戶代碼）〔v2 §4〕。也就是說，往來廠商的負責人資訊是可以透過 API 正確登錄的。

那麼，圖下方以紅色標示的「22 個無法傳遞的欄位（27.8%）」究竟是什麼？
經過對實測台帳的全面調查後，發現其中 15 項是「銷售管理台帳」畫面的欄位〔v2 §4〕。這是發票畫面之外另外提供的台帳功能，但 API 端根本沒有相對應的台帳交易物件。除此之外，電子發票（Peppol）特有的貨幣代碼與買方參照（5 項）、收據的備註文字（1 項）、郵寄留言（1 項）也都無法透過 API 寫入〔v2 §4〕。

即使畫面上有這些功能，若 API 沒有對應的物件或屬性，這些業務最後仍只能留在現場手動處理。

4. 「業務上能用」的驗證② —— Money Forward Cloud 會計（890 項中，業務輸入 126 項的牆）

接著來看後勤作業的核心——「Money Forward Cloud 會計」的全 890 項畫面欄位對照結果。

如圖上段所示，在 890 項畫面欄位中，扣除報表彙總（160 筆）、UI 操作（329 筆）、初始設定（167 筆）等之後，業務輸入欄位（Cat-1）只有 126 項（14.2%）〔v2 §4〕。

把這 126 項與 OpenAPI 規格書（raw/mf_accounting_openapi_v3.yaml）對照後，如圖中段所示，出現了驚人的偏差〔v2 §4〕。

• ○ 完全（可直接寫入）：15 項（11.9%）〔v2 §4〕
• △ 有限制（如需內部 ID 等）：7 項（5.6%）〔v2 §4〕
• × 無法傳遞（沒有寫入口）：104 項（82.5%）〔v2 §4〕

在會計業務輸入欄位中，竟有超過 8 成（104 項）無法透過 API 傳遞，覆蓋率只靠 ○ 時為 11.9%，把 △ 算進去也只有 17.5%〔v2 §4〕。

為什麼無法傳遞的比例會高到這種程度？因為 Web 畫面大量使用的功能領域，API 根本沒有整套提供。
像是傳票字典（18 項全數 ×）、消費稅申報（17 項全數 ×）、憑證 OCR 讀取資訊（只能上傳檔案本體，沒有把讀取欄位寫入 API；14 項 ×）、債務管理相關（付款對象 11 項、交易 8 項、分類主檔 5 項全數 ×）、科目 5 項與輔助科目 3 項的新建立（僅供讀取、沒有建立 API）、固定資產台帳（5 項全數 ×）等，大量功能都未提供 API〔v2 §4〕。

不過，不能因此就下結論說「會計 API 不能用」。

如圖下段所示，若只把 API 原本就要處理的「傳票」「往來廠商」「明細」27 項範圍縮小來看，○ 15 項＋△ 7 項＝22 項，覆蓋率可達 81.5%〔v2 §4〕。也就是說，若只限定於每天從其他系統流入傳票資料的核心業務，其實超過 8 成的欄位都有支援。

但讓現場困擾的是這 7 個帶有 △ 的「有限制」項目。
在投入傳票時，不能直接傳遞像科目名稱或部門名稱這類字串，而是必須先取得 Money Forward 內部編號的 account_id、department_id 等數值型「內部 ID」再指定〔v2 §4〕。由於沒有主檔建立 API，如果外部系統出現新的部門未登錄，必須由人先到會計畫面手動建檔，否則 API 就會以錯誤停止。

5. 阻礙即時串接的 2 大障壁 —— 速率限制與方案限制

即便欄位對照全部過關，實際運作中還有 2 道會讓系統停下來的牆：速率限制（通訊頻率限制）與方案限制。

上圖整理的是從公開 82 個系統台帳調查中看見的實態。

5-1. ① 速率限制的單位各不相同，無法直接比較

在公開 82 系統之中，有逐字明記次數上限的只有 23 系列〔v2 §7〕。但其限制單位卻完全不同，例如：

• 每日：BASE（100,000 次/日）、board（3,000 次/日）〔v2 §7〕
• 每小時：freee 人事勞務（10,000 次/時）、Kaonavi（3,000 次/時）〔v2 §7〕
• 每 5 分鐘：Chatwork（300 次/5 分鐘）、KING OF TIME（500 次/5 分鐘）〔v2 §7〕
• 每分鐘：Google Workspace（每位使用者 2,400 查詢/分鐘）、LINE WORKS（免費方案 60 次/分鐘、較高方案 240 次/分鐘）〔v2 §7・§8〕
• 每秒：Money Forward Cloud 發票（3 次/秒・報表建立 POST）〔v2 §7〕

因為單位不同，數字大小不能直接拿來比寬鬆程度。即使可接受「每日 3,000 次」，如果另有「每秒 3 次」的限制，晚上批次匯入銷售傳票時就可能瞬間超過 burst 限制，因 HTTP 429（Too Many Requests）而中斷串接。另外，像 freee 會計與 Money Forward Cloud 會計這類系統，會在不公開具體數值的同時規定「超過一定頻率就回傳 429」，因此重試設計不可或缺〔v2 §7〕。

5-2. ② 方案對 API 的阻斷

另外，也有 API 使用受契約方案限制的情況。檢視台帳中含有方案相關明文的 18 筆後，可知實況如下〔v2 §8〕。

• 必須為付費方案：Jobcan 會計只有在簽約付費方案時才能使用；「Jobcan 勤怠管理」則除了付費方案之外，還必須簽署 NDA（保密協議）才可使用 API〔v2 §8〕。
• 限制因方案而變動：「LINE WORKS」免費方案為 60 次/分鐘，高階方案為 240 次/分鐘；「BowNow」免費方案是 1,000 次/日，通常付費方案則提升到 10,000 次/日，差距非常大〔v2 §8〕。
• 所有方案開放：另一方面，也有像 BowNow 這樣不論付費或免費方案都可免費使用 API 的例子，或像 Money Forward Cloud 會計的遠端 MCP 伺服器那樣，在所有方案都提供的例子〔v2 §8〕。

在正式簽約前，必須確認自己的契約版本到底能不能打 API、若要大量傳輸資料是否需要升級到更高方案，這些都是非常重要的事項。

6. 現場的防衛對策 —— 簽約前、設計前應確認的 4 項檢查清單

從前面的實測可知，在 SaaS 導入簽核通過之前，或在開始開發 API 串接之前，社內 SE 與資訊系統部門應採取的自我防衛措施已經很明確了。

我們在上圖所示的「3 項基本確認」之外，加入運作設計，整理出「4 項防衛檢查清單」。

① 先列出自己想要搬動的業務欄位（Cat-1），並與對方清單逐項比對了嗎？
不要輕信業務說法中的「發票可以串接」「傳票可以匯入」。請把自己公司真正想從外部傳入的欄位整理成清單，並與對方 API request schema 的屬性逐一對照。
像 Money Forward Cloud 發票的銷售管理台帳（15 項）或會計的傳票字典（18 項）這種畫面上有，但 API 物件本身不存在的領域，一旦確認到這一點，就表示「手動輸入會留下來」已成定局。即使想改用 CSV 匯入繞過 API，只要對方 CSV 接收欄位很窄，本質上仍然是無法傳遞。

② 對象物件是否同時有 C（建立）與 U（更新）的入口？
從公開規格確認可讀的對象超過九成，但能確認可寫的只有 Create 56.7%、Update 41.8%〔v2 §1〕。無法確認的部分不是「不能寫」，而是「規格書看不出來」，所以不要自行臆測，請書面向廠商確認。 由於 41 系列中有 32 系列（78.0%）同時混有「只能讀」與「可寫」，所以重點不是產品層級，而是對象（object）層級去確認〔v2 §2〕。

③ 設計中是否納入內部 ID 與主檔的預先取得／解決流程？
如會計系統對照所揭示，當要用 API 投入傳票時，不能直接指定科目名稱等字串，而必須指定內部 ID（如 account_id）〔v2 §4〕。若沒有主檔建立 API，就必須事先規劃當新主檔出現時的作業流程：由誰、在何時、到畫面上手動先建好。

④ 速率限制的單位，以及在自家契約方案下是否能容納通訊量？
請計算自家資料量（月件數、尖峰 burst 件數），確認是否不會碰到對方的秒／分／日限制〔v2 §7〕。另外也請在簽約前以書面向廠商確認：API 使用是否需要額外費用、是否要升級到更高方案、是否需要簽 NDA〔v2 §8〕。

結語

「因為能串接 API，所以業務就會自動化」——這其實只代表系統基礎設施的入口有打開而已。

對於開頭那個問題「API 能救到幾成」的答案，實測已經很清楚了。這不是在選產品，而是在看自己的業務是否落在 API 對象物件的內部。 會計全畫面欄位只看起來是 17.5%，但若限定在 API 真正鎖定的傳票、往來廠商、明細，則可到 81.5%。同一個產品，數字可以差到 4 倍以上，因此型錄上寫的「支援 API」，以及本文某一個比例，若直接拿來看，都不會自動變成你公司的答案。把自己每天手動輸入的欄位列出來，再與對方的 request schema 一列一列對照——看起來繞遠路，其實這才是最近的路。

另外，本文中的數字，是編輯部依據公開規格可確認的範圍所整理。無法確認的部分，本文並沒有寫成「不存在」。 對於那些無法確認可寫的對象，建議直接向廠商確認。

不要被「有 API」這句話迷惑，務必從對象的方向性、欄位的缺漏與多餘、以及對內部 ID 的依賴關係一起看待設計。這才是防止導入後出現「怎麼會跟想像不一樣」的唯一道路。

【歡迎轉載】本文轉載說明

本文的文字與圖表皆可自由轉載。圖片請不要加工，以原樣使用即可。轉載時請註明出處為 renkeimap.jp 或本文章連結，無需事前聯絡。

※ 作者曾任職於日立系 IT 廠商、長照軟體廠商，以及大學附設醫院 IT 部門，現已獨立，並在協助中小企業進行 IT／DX 支援的同時，以第一手資料調查業務系統之間的「連結」。文中的「編輯部」指的是作者所屬的 IT 連結地圖編輯部。若發現錯誤，歡迎至 更正窗口（免費、無需帳號）提出；更正紀錄也會公開。

原文出處：https://qiita.com/songchong/items/d1e1e908a1b76d6995b1