API整合開發指南

一、概述

這篇指南是寫給需要和算數低代碼平臺做系統整合的開發者的。不管你是要把平臺的資料同步到ERP，還是要從外部系統調平臺的介面建立表單，又或者是訂閱平臺的事件做實時聯動——這篇文件都會給你講明白。

算數平臺提供的是標準RESTful API，支援JSON格式的請求和響應。認證機制支援OAuth2和API Key兩種方式，適用不同場景。下面我們從設計規範開始，一步步把整個API體系過一遍。

二、RESTful API設計規範

我們的API設計嚴格遵循RESTful原則。說直白點，就是URL表示資源，HTTP方法表示操作，HTTP狀態碼錶示結果。聽起來是常識，但很多平臺的API其實並沒有真正遵守這些原則。

2.1 URL規範

• 使用名詞複數形式：/api/v1/apps 而不是 /api/v1/app
• 資源層級用斜槓分隔：/api/v1/apps/{appId}/forms/{formId}
• 查詢引數用小駝峰：?pageSize=20&pageNum=1
• 版本號放在URL路徑中：/api/v1/，不使用Header版本控制

2.2 HTTP方法使用

2.3 API端點總覽

以下是平臺核心API端點的完整列表，按模組分組：

三、認證機制

平臺支援兩種認證方式，選用哪種取決於你的整合場景。

3.1 OAuth2 授權碼模式

適合需要代表使用者操作的場景（比如發起審批流程、獲取使用者個人資料）。流程是標準的OAuth2 Authorization Code Flow：

1. 引導使用者訪問授權頁面：https://api.micount.cn/oauth/authorize?client_id=YOUR_ID&redirect_uri=YOUR_URI&response_type=code&scope=app:read+app:write
2. 使用者授權後，平臺回撥你的redirect_uri，攜帶authorization code
3. 用code換取access_token：

POST /api/v1/auth/token
Content-Type: application/json

{
    "grant_type": "authorization_code",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "code": "authorization_code_from_redirect",
    "redirect_uri": "https://your-app.com/callback"
}

返回結果：

{
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 7200,
    "refresh_token": "d4f5e6a7b8c9...",
    "scope": "app:read app:write"
}

3.2 API Key 認證

適合服務端到服務端的整合場景（比如資料同步、批次匯入）。API Key在平臺後臺生成，透過HTTP Header傳遞：

GET /api/v1/apps
X-API-Key: mk_live_a1b2c3d4e5f6g7h8
X-API-Signature: hmac_sha256(timestamp + body, api_secret)

API Key分為兩種許可權級別：只讀Key（mk_readonly_字首）和讀寫Key（mk_live_字首）。建議在只需要讀取資料的場景下使用只讀Key，遵循最小許可權原則。

四、資料格式

所有API請求和響應統一使用JSON格式。我們設計了一套統一的響應結構，不管是成功還是失敗，返回格式是一致的：

4.1 統一響應結構

{
    "code": 0,
    "message": "success",
    "data": {
        "id": "app_6f8a2b3c",
        "name": "銷售管理應用",
        "status": "published",
        "createdAt": "2024-06-01T10:30:00+08:00"
    },
    "requestId": "req_8a7b6c5d4e3f",
    "timestamp": 1717200000000
}

欄位說明：code為0表示成功，非0表示錯誤（具體錯誤碼見下文）；message是人類可讀的描述資訊；data是實際業務資料；requestId用於問題排查；timestamp是伺服器時間戳。

4.2 分頁格式

列表類API統一支援分頁，引數和返回格式如下：

GET /api/v1/apps?pageSize=20&pageNum=1&keyword=銷售

{
    "code": 0,
    "message": "success",
    "data": {
        "list": [...],
        "total": 156,
        "pageSize": 20,
        "pageNum": 1,
        "totalPages": 8
    }
}

五、錯誤處理

一套好的API必須有清晰的錯誤碼體系。我們的錯誤碼分三層：HTTP狀態碼 + 業務錯誤碼 + 錯誤描述。HTTP狀態碼告訴你大概是什麼型別的問題，業務錯誤碼告訴你具體哪裡出了問題。

5.1 HTTP狀態碼

5.2 業務錯誤碼

5.3 錯誤響應示例

{
    "code": 10002,
    "message": "引數格式錯誤：欄位'email'不符合郵箱格式",
    "data": null,
    "errors": [
        {
            "field": "email",
            "message": "必須為有效的郵箱地址",
            "value": "test@@invalid.com"
        }
    ],
    "requestId": "req_8a7b6c5d4e3f",
    "timestamp": 1717200000000
}

六、限流策略

為了保護平臺穩定性，我們對API呼叫做了限流。限流演算法用的是令牌桶（Token Bucket），比簡單的固定視窗計數更靈活——允許一定程度的突發流量，但總體速率有上限。

6.1 限流規則

6.2 限流響應頭

每次API響應都會攜帶限流資訊頭，方便客戶端做自適應調整：

X-RateLimit-Limit: 50          # QPS上限
X-RateLimit-Remaining: 42      # 當前視窗剩餘可用請求數
X-RateLimit-Reset: 1717200060  # 限流視窗重置時間(Unix時間戳)
Retry-After: 2                 # 觸發限流後建議等待秒數(僅429響應)

6.3 客戶端重試建議

當收到429響應時，不要立即重試，應該採用指數退避策略。我們推薦的重試間隔：1秒 → 2秒 → 4秒 → 8秒，最多重試4次。如果4次後仍然429，說明你的呼叫頻率確實超了，需要考慮最佳化呼叫邏輯或升級套餐。

七、Webhook事件訂閱

Webhook是平臺主動通知外部系統的方式。當平臺內發生特定事件時（比如表單提交、流程審批完成），平臺會主動向你的回撥URL傳送HTTP POST請求，你不需要輪詢。

7.1 支援的事件型別

7.2 Webhook註冊

POST /api/v1/webhooks
X-API-Key: mk_live_xxxxxxxx
Content-Type: application/json

{
    "url": "https://your-app.com/webhook/micount",
    "events": ["form.submitted", "workflow.completed"],
    "appId": "app_6f8a2b3c",
    "description": "銷售管理應用事件回撥",
    "secret": "your_webhook_secret_for_signature_verification"
}

7.3 Webhook回撥格式

當事件觸發時，平臺會向註冊的URL傳送POST請求：

POST https://your-app.com/webhook/micount
Content-Type: application/json
X-Micount-Event: form.submitted
X-Micount-Signature: sha256=a1b2c3d4e5f6...
X-Micount-Timestamp: 1717200000

{
    "event": "form.submitted",
    "eventId": "evt_8a7b6c5d",
    "timestamp": 1717200000000,
    "data": {
        "appId": "app_6f8a2b3c",
        "formId": "form_9d8e7f6a",
        "dataId": "data_1a2b3c4d",
        "submitter": {
            "userId": "usr_12345",
            "name": "張三",
            "email": "zhangsan@company.com"
        },
        "formData": {
            "customer_name": "某某公司",
            "amount": 50000,
            "status": "pending"
        }
    }
}

7.4 簽名驗證

每個Webhook請求都帶有簽名，用於驗證請求確實來自算數平臺（防止偽造）。簽名演算法：HMAC-SHA256(timestamp + rawBody, webhook_secret)。你的服務端收到請求後應該：

1. 從Header中取出X-Micount-Timestamp和X-Micount-Signature
2. 檢查timestamp與當前時間差是否在5分鐘以內（防重放攻擊）
3. 用你註冊時設定的secret重新計算簽名，與Header中的簽名對比
4. 簽名一致才處理請求，不一致直接丟棄

7.5 重試機制

你的服務端收到Webhook請求後，需要在5秒內返回HTTP 200。如果超時或返回非2xx狀態碼，平臺會自動重試。重試策略：第1次間隔30秒，第2次間隔2分鐘，第3次間隔10分鐘，第4次間隔1小時，最多重試4次。超過4次仍然失敗的事件會被記錄到失敗佇列，可以在後臺手動重發。

八、SDK與工具

為了降低整合成本，我們提供了以下SDK和工具：

• Java SDK：Maven依賴cn.micount:lowcode-sdk:1.2.0，支援同步和非同步呼叫
• Python SDK：pip安裝pip install micount-lowcode，支援型別提示
• Node.js SDK：npm安裝npm install @micount/lowcode-sdk，支援TypeScript
• Postman Collection：一鍵匯入所有API，方便除錯
• 線上API除錯臺：平臺後臺內建，支援線上傳送請求檢視響應

提示：所有SDK和工具均開源在算數科技開發者中心。如果你在整合過程中遇到問題，可以聯絡技術支援：郵箱 cooper@micount.cn，電話 18016313342。

九、最佳實踐

最後總結幾條API整合的最佳實踐，都是踩坑總結出來的：

1. 快取token：access_token有效期2小時，不要每次請求都重新獲取。快取起來，過期前5分鐘重新整理即可。
2. 批次操作優先：需要提交100條表單資料時，用批次介面（POST /api/v1/apps/{appId}/forms/{formId}/data/batch）而不是迴圈呼叫單條介面。一次批次請求比100次單條請求快得多，也更不容易觸發限流。
3. Webhook優於輪詢：需要實時感知資料變化時，優先用Webhook，不要輪詢GET介面。輪詢既浪費配額又延遲高。
4. 實現指數退避重試：網路不穩定是常態，你的程式碼必須能處理臨時性錯誤。但重試不是無腦重試——用指數退避+最大重試次數，避免雪崩。
5. 使用requestId排查問題：遇到排查不了的問題，把requestId發給技術支援，我們能透過它定位到完整的請求鏈路。

想了解更多技術細節？推薦閱讀我們的低代碼平臺技術架構白皮書，瞭解平臺底層是怎麼運作的。如果是運維同學，也可以看看企業級部署方案。