外部服務與 ERP 系統串接

前一章講的是別人怎麼呼叫 AI GO。這一章講反方向——AI GO 怎麼呼叫別人。

平台有兩套機制，用途不同：

1. 外部服務：應用程式的對外出口

Custom App 不能隨意連上網際網路。所有對外呼叫都必須經過授權過的外部服務，這是刻意的設計——避免應用程式把企業資料送到未經核可的地方。

設定入口

Builder 的「外部服務」分頁是唯一入口。 這裡設定的是「這個應用程式可以呼叫哪些外部服務」。

網域白名單

授權以網域為單位：您授權 api.logistics.example.com，該應用就只能呼叫這個網域底下的路徑。未授權的網域一律呼叫不到，不論程式碼怎麼寫。

認證方式：金鑰歸應用程式自管

閘道只做網域驗證——不代管金鑰、不注入也不剝除 Authorization header。 對外 API 的憑證存放在應用程式的 App Secrets（ctx.secrets），由 Server Action 在呼叫時自行組出認證 header：

def execute(ctx):
    resp = ctx.http.call('logistics', '/track',
                         method='POST',
                         headers={'Authorization': f"Bearer {ctx.secrets.get('LOGISTICS_KEY')}"},
                         body={'no': ctx.params['tracking_no']})

若外部 API 回 401，代表應用程式自帶的憑證有問題（header 沒組對、金鑰過期）—— 檢查 App Secrets 與程式碼，不需要動外部服務設定。

在程式碼中使用

def execute(ctx):
    resp = ctx.http.call('logistics', '/track',
                         method='POST',
                         body={'no': ctx.params['tracking_no']})

    if resp['status'] != 200:
        # data 帶 error_type / error / fix
        return ctx.response.json({'error': resp['data'].get('fix')})

    ctx.response.json(resp['data'])

第一個參數是服務代號（不是完整網址），路徑會接在該服務的基底網址後面。

可行動的錯誤訊息

外部呼叫失敗時，回應的 data 會帶三個欄位：

fix 是刻意設計的——它讓應用程式可以把「怎麼修」直接顯示給操作者，而不是丟一個技術堆疊。Builder 介面與 AI 開發助手也會讀取這個欄位來協助排錯。

授權缺漏的症狀

程式碼呼叫了沒有建立同名外部服務、或未授權給本應用的服務時，執行期會被閘道擋下， 回應的 fix 欄位會指出缺什麼。平台不驗證也不保管金鑰——金鑰缺漏要到實際呼叫 外部 API 收到 401 才會浮現，屬應用程式側要處理的錯誤。

抓取任意網址

除了具名服務，ctx.http.fetch 可以抓取任意公開網址（例如讀取公開的匯率或公告頁面）。安全限制仍然完整保留——不能藉此存取內部網路位址。

2. 外部數據串接：與既有系統同步

入口：主控台「資料中心 › 外部數據」，需要 system.admin 權限。

與「外部服務」不同，這套機制處理的是結構化的資料同步——把既有 ERP 或資料庫的資料與 AI GO 的資料模型對應起來，定期雙向同步。

支援的來源

• 通用 RESTful API
• 通用外部資料庫（PostgreSQL、MySQL 等）
• 主流 ERP 系統的預設連線設定

建立資料來源後可以「測試連線」，即時檢測連通性與健康狀態。

欄位映射

連上來源後，需要把外部的欄位與 AI GO 的資料模型對應起來。

映射模板：常見的 ERP 系統提供預設映射模板（客戶主檔、產品主檔等），可用精靈快速套用。

AI 映射建議：對接自訂表或非標準系統時，可使用 AI 自動建議——系統會分析外部欄位名稱、資料型態與 AI GO 欄位的語意相似度，提出最佳對應。這大幅降低了逐欄設定的負擔。

同步方向與日誌

同步日誌記錄每次執行的時間、異動筆數、成功狀態與錯誤訊息，供追蹤資料一致性與排查問題。

3. 該用哪一個

判準：單次呼叫用外部服務，持續同步用串接，一次性搬遷用匯入。

4. 反方向：讓外部系統推送給您

若外部系統支援事件推送，不需要輪詢——用 Webhook 讓它主動打進來。

在 Custom App 的 Action 上開啟 Webhook 即可取得對外端點：

POST https://{app 子網域}/webhook/{action_name}

請務必在 Action 內驗證來源（例如以 ctx.crypto.hmac_sign 比對簽章）。詳見第 9 章。

5. 安全邊界摘要

• 應用程式只能呼叫被明確授權的網域
• 對外憑證存放在 App Secrets，不落在應用程式的原始碼裡
• 內部網路位址受保護，不能透過抓取任意網址繞過
• 呼叫外部服務需要 http scope，屬於高風險等級——授權時需要擁有者密碼再驗證
• 每一次對外呼叫都留下稽核紀錄