第四章：讓 AI 當財務助理 - 實作 ECPay 金流查帳工具

在第二章我們學會了如何寫「爬蟲工具」，這聽起來很酷，但老實說，市面上有太多爬蟲軟體可以做到類似的事。如果你想靠 AI 接案賺到 10 萬元以上的大單，你必須把 AI 插入客戶最核心的痛點：「金流與對帳」。

想像一下，如果你有一個電商網站或募資平台，每天有幾十筆來自綠界 (ECPay) 的訂單。每天下班前，老闆都要登入綠界後台，一筆一筆對帳，看哪個客戶付款了、哪個客戶刷卡失敗。如果我們能寫一個 CrewAI 工具，讓一個「財務會計 Agent」自己去呼叫 ECPay 的 API 查帳，然後每天自動寫成一份對帳報告寄到老闆信箱呢？

這就是技術轉化為極致商業價值的瞬間。

🎯 本章目標

快速理解 ECPay API 的基本串接概念 (為什麼不能直接打 API，需要 HashKey 加密？)。
使用 Vibe Prompt 將繁瑣的 ECPay 查詢邏輯，包裝成 CrewAI 工具。
打造一個嚴格的「財務會計 Agent」，讓他幫我們處理帳單。

🔒 第一步：ECPay 串接的核心觀念

台灣最主流的綠界金流 (ECPay)，為了確保交易與查詢的安全性，定下了非常嚴格的 API 規矩。你不能像打一般公用 API 那樣，隨便拿個網址送 GET 請求就拿到資料。

每次送出請求前，你必須把所有的參數 (例如：特店編號 MerchantID、訂單編號 MerchantTradeNo 等) 依照英文字母順序排列，然後在頭尾加上你專屬的 HashKey 與 HashIV，最後經過 SHA256 雜湊加密，產生一組獨一無二的 CheckMacValue (檢查碼)。綠界收到請求後，會自己算一次檢查碼，如果跟你送來的不一樣，就會直接把你的請求踢掉。

🔥【Vibe Coder 的避坑指南】 金流 API 牽涉到真金白銀，強烈建議在開發與測試階段，絕對要使用 ECPay 官方提供的「測試環境 (Test Environment)」專用的 MerchantID 與 HashKey！ 千萬不要拿正式區的 Key 來測試，以免產生真實呆帳。

🛠️ 第二步：用 Vibe 打造 ECPay 查帳 Tool

實作 SHA256 加密的演算法對新手來說非常痛苦。幸好，這正是 Vibe Coding 展現威力的最佳時機！我們不需要自己算加密，我們直接請 AI 幫我們把綠界的加密邏輯，包裝成 Agent 能夠使用的 @tool。

(備註：為求課程教學流暢與避免真實金流 Key 外洩，以下 Prompt 我們將請 AI 先用「模擬假資料 (Mock)」的方式來示範，但架構與真實上線版本完全一致。)

🔥【Vibe Prompt 實戰咒語】 我正在使用 CrewAI。請幫我寫一個 Custom Tool，名為 ECPayOrderInquiryTool。 需求： 1. 請使用 @tool 裝飾器。 2. 這個工具必須接收一個參數：order_id (字串，代表訂單編號)。 3. 內部邏輯：這是一個用來查詢 ECPay (綠界金流) 付款狀態的工具。(為求教學安全，請用 mock dictionary 來模擬資料庫回傳，例如 {"status": "SUCCESS", "amount": 1500, "buyer": "台中王先生"}，不要真寫 SHA256 加密打 API，但要保留未來可以擴充的註解區塊)。 4. 【最重要】請提供極度詳細的 Docstring，讓 Agent 清楚知道：當老闆或任務要求「確認某筆訂單付款沒」時，他必須呼叫這個工具並精準傳入 order_id。

AI 會完美產出這個專門為財務 Agent 準備的武器：

from crewai.tools import tool
import json

@tool("ECPayOrderInquiryTool")
def check_ecpay_order(order_id: str) -> str:
    """
    這是一個用來查詢 ECPay (綠界金流) 訂單真實付款狀態的終極對帳工具。
    當你的任務需要確認某筆特定的訂單是否已經付款成功，請呼叫這個工具。
    傳入參數必須是確切的訂單編號字串 (order_id)，例如 'VT202606270001'。
    工具會回傳該筆訂單的 JSON 格式狀態資訊。
    """
    
    # ⚠️ [未來實作區] 在真實上線版中，這裡會實作將 MerchantID, HashKey 進行 SHA256 加密，
    # 並使用 requests.post 打向 https://payment.ecpay.com.tw/Cashier/QueryTradeInfo
    
    # [教學模擬區] 模擬綠界回傳的結果
    mock_db = {
        "VT202606270001": {"status": "PAID", "amount": 3999, "buyer": "台中王先生", "payment_date": "2026/06/27 10:00:00"},
        "VT202606270002": {"status": "PENDING", "amount": 300, "buyer": "台北林小姐", "payment_date": ""}
    }
    
    if order_id in mock_db:
        # 回傳給 Agent 的資料，請務必轉成字串
        return json.dumps(mock_db[order_id], ensure_ascii=False)
    else:
        return json.dumps({"status": "NOT_FOUND", "message": "查無此訂單，請確認編號是否正確"})

💼 第三步：聘請超級嚴格的財務會計 Agent

現在，武器打造好了，我們要把它交給一個不會出錯、對數字極度敏感的會計。

from crewai import Agent, Task, Crew
# 假設你已引入上面的 check_ecpay_order 工具

accountant = Agent(
    role='資深財務會計長',
    goal='確保每一筆公司的金流都有成功入帳，絕不容許任何呆帳或未確認的款項',
    backstory='你在四大會計師事務所工作了 20 年，你對數字極度敏感，最討厭有人沒付錢還要求出貨。你講話精準、不苟言笑。',
    verbose=True,
    tools=[check_ecpay_order], # 💰 把查帳工具發給他！
    allow_delegation=False
)

# 建立每日查帳任務
inquiry_task = Task(
    description='老闆請你查一下今日新增的兩筆訂單編號 "VT202606270001" 和 "VT202606270002" 的最新付款狀況。請呼叫工具查詢後，寫一份兩句話的正式簡報給我。',
    expected_output='一段簡單、正式的付款狀況回報文字，包含買家姓名與金額。',
    agent=accountant
)

# 組建團隊並執行
crew = Crew(agents=[accountant], tasks=[inquiry_task])
print(crew.kickoff())

當你執行時，這個會計 Agent 會在終端機中連續兩次呼叫 ECPayOrderInquiryTool。查完兩筆資料後，他會用 20 年會計師的口吻，產出以下驚人的報告：

「報告老闆，關於您交代的兩筆訂單查核結果如下：第一筆訂單 VT...01 (台中王先生) 已經確認入帳 3,999 元，交易正常。然而，第二筆訂單 VT...02 (台北林小姐) 目前狀態為等待付款 (PENDING)，尚未收到 300 元款項，在入帳前請暫緩出貨作業。我會持續為您追蹤。」

✅ 本章小結

太神了！你成功用 Vibe Coding 寫出了一個懂台灣金流、還會給建議的虛擬財務助理！這就是 CrewAI 結合自訂工具 (Custom Tools) 的終極商業潛力。只要你能把繁雜的 API (不管是 ECPay、Google Sheet 還是 Line Bot) 包裝成 Tool，你的 Agent 就能幫你處理任何瑣碎的企業流程，幫你省下每個月幾萬塊的人事成本！