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发给技术支持，我们能通过它定位到完整的请求链路。

想了解更多技术细节？推荐阅读我们的低代码平台技术架构白皮书，了解平台底层是怎么运作的。如果是运维同学，也可以看看企业级部署方案。