API 整合規格產生器
用途
把第三方 API 文件丟給 AI，讓它產出認證設定、主要 Endpoint 表、可執行程式碼骨架（含錯誤處理）與 Rate Limit 注意事項，讓你跳過翻文件的苦差事直接開始整合。
何時用
- 適合：要快速串接第三方 API（金流、簡訊、物流、地圖等），想讓 AI 先讀文件產出整合骨架，再由工程師填入業務邏輯時。
- 不要用：既有串接已在運作但出問題需要除錯——那時用「Debug 根因分析」更直接；也不要用在你自己要設計的 API（那是 API 設計題，不是整合題）。
Prompt
text
請根據以下資訊，幫我產出完整的 API 整合規格。
API 用途：{{這個 API 是做什麼的，例：台灣電子發票 API，用來開立 B2C 發票}}
語言與框架：{{例：Python 3.12 + FastAPI}}
API 文件關鍵段落：
{{貼上 API 文件的認證方式、主要 endpoint、請求/回應格式}}
使用場景：{{你要在什麼時機呼叫這個 API，例：訂單完成後自動開立發票}}
請輸出以下四個部分：
**1. Authentication 設定**
- 認證方式（API Key / OAuth / JWT / ...）
- 環境變數清單（列出需要設定哪些 env vars，不要把真實值寫進程式碼）
- 初始化範例程式碼
**2. 主要 Endpoint 表**
| Endpoint | 方法 | 用途 | 必填參數 | 回應格式 |
**3. 可執行程式碼範例**
- 至少一個完整的呼叫範例，含錯誤處理（4xx / 5xx 分開處理）
- 程式碼要能直接複製貼上執行，不要用假的 placeholder 函式
**4. 常見失敗場景與 Rate Limit**
- 列出至少 3 種常見錯誤回應與處理方式
- Rate Limit 上限與建議的 retry 策略範例 / 變體
- 填好變數：API 用途填
台灣電子發票 API（綠界科技）、語言框架填Python 3.12 + FastAPI、使用場景填訂單完成後 webhook 觸發開立 B2C 發票、API 文件段落填入官方文件的認證與 Endpoint 部分。 - 變體（n8n 整合版）：語言框架改為
n8n HTTP Request 節點，請 AI 輸出的不是 Python 程式碼，而是 n8n HTTP Request 節點的欄位設定（Method / URL / Headers / Body）。 - 變體（只要 Endpoint 表）：在 prompt 後加「只輸出第 2 部分 Endpoint 表就好，其他略過」，快速掃描 API 涵蓋範圍。
🎯 範例輸出（實測）
在 Claude.ai 跑這句、把
{{API 用途}}填成「台灣電子發票 API（綠界科技 ECPay）」、語言框架填「Python 3.12 + FastAPI」、使用場景填「訂單完成後 webhook 觸發開立 B2C 發票」的結果：
點開看 AI 實際輸出
1. Authentication 設定
認證方式：API Key + HashKey/HashIV（SHA-256 簽章驗證）
環境變數清單：
text
ECPAY_MERCHANT_ID=...
ECPAY_HASH_KEY=...
ECPAY_HASH_IV=...
ECPAY_API_URL=https://einvoice.ecpay.com.tw/B2CInvoice/Issue初始化範例：
text
import hashlib, os
from urllib.parse import urlencode
def sign_payload(params: dict) -> str:
raw = "HashKey=" + os.environ["ECPAY_HASH_KEY"]
raw += "&" + urlencode(sorted(params.items()))
raw += "&HashIV=" + os.environ["ECPAY_HASH_IV"]
return hashlib.sha256(raw.lower().encode()).hexdigest().upper()2. 主要 Endpoint 表
| Endpoint | 方法 | 用途 | 必填參數 | 回應格式 |
|---|---|---|---|---|
| /B2CInvoice/Issue | POST | 開立發票 | MerchantID, RelateNumber, CustomerEmail, SalesAmount | JSON |
| /B2CInvoice/GetIssue | POST | 查詢發票 | MerchantID, RelateNumber | JSON |
| /B2CInvoice/Void | POST | 作廢發票 | MerchantID, InvoiceNumber, VoidReason | JSON |
3. 可執行程式碼範例
text
import httpx
from fastapi import HTTPException
async def issue_invoice(order_id: str, amount: int, email: str) -> dict:
payload = {
"MerchantID": os.environ["ECPAY_MERCHANT_ID"],
"RelateNumber": order_id,
"CustomerEmail": email,
"SalesAmount": amount,
"InvType": "07", # B2C 一般發票
"TaxType": "1", # 應稅
}
payload["CheckMacValue"] = sign_payload(payload)
async with httpx.AsyncClient() as client:
resp = await client.post(os.environ["ECPAY_API_URL"], data=payload, timeout=10)
resp.raise_for_status() # 5xx → 拋出 HTTPStatusError
result = dict(x.split("=") for x in resp.text.split("&"))
if result.get("RtnCode") != "1":
# 4xx 業務錯誤（非 HTTP 錯誤）
raise HTTPException(status_code=400, detail=f"發票開立失敗：{result.get('RtnMsg')}")
return result4. 常見失敗場景與 Rate Limit
| 錯誤代碼 | 說明 | 處理方式 |
|---|---|---|
| RtnCode=10000001 | 簽章驗證失敗 | 檢查 HashKey/IV 環境變數，重新產生簽章 |
| RtnCode=10200047 | 重複 RelateNumber | 訂單號已開過發票，查詢後回傳既有發票號 |
| HTTP 503 | ECPay 維護中 | Exponential backoff，最多重試 3 次，間隔 2/4/8 秒 |
Rate Limit：建議每分鐘不超過 60 次呼叫；Retry 策略採指數退避，建議 jitter ±500ms 避免雪崩。
💡 實測心得：把 API 文件的「認證方式」段落貼進去比貼整份文件效果更好——貼整份文件 AI 容易產出不必要的 endpoint；只貼關鍵段落讓輸出更聚焦，工程師調整時間也短。
延伸
簡單來說，這道 prompt 把「翻 API 文件 + 寫整合骨架」這兩件耗時的事交給 AI 做，讓工程師專注在業務邏輯。但 AI 不一定了解你的完整業務脈絡，所以「使用場景」那一欄要填清楚——一樣是金流 API，「結帳時即時授權」和「訂單完成後開發票」的呼叫時機和錯誤處理策略會差很多。