API对接帮助文档

文档概述

本文档旨在帮助开发人员快速、顺利地完成与我方API系统的对接工作。文档包含了API的基本信息、多种认证方式、请求格式、常见接口示例以及故障排除指南。

1. 基本信息

1.1 接口地址

• 测试环境：https://api-test.mandao.com/v1
• 生产环境：https://api.mandao.com/v1

1.2 支持协议

• HTTPS
• RESTful API

1.3 数据格式

• 请求/响应数据格式：JSON
• 字符编码：UTF-8

2. 认证方式

2.1 API密钥认证（推荐用于服务端对接）

2.1.1 认证方式

所有API请求需要在Header中包含认证信息：

Authorization: Bearer {api_key}
X-API-Secret: {api_secret}

2.1.2 获取API密钥步骤

1. 登录管理后台
2. 进入”开发者中心” → “API管理”
3. 创建新的API密钥
4. 保存API Key和Secret（Secret仅显示一次）

2.1.3 请求示例

POST /api/v1/orders HTTP/1.1
Host: api.example.com
Authorization: Bearer your_api_key
X-API-Secret: your_api_secret
Content-Type: application/json

{
    "product_id": "123",
    "quantity": 1
}

2.2 OAuth 2.0认证（推荐用于第三方应用）

2.2.1 支持的授权模式

2.2.2 授权码模式流程

步骤1：获取授权码

请求参数：

请求示例：

GET /oauth/authorize?client_id=your_client_id&redirect_uri=https://your-app.com/callback&response_type=code&state=random_string&scope=read%20write

步骤2：换取访问令牌

请求参数：

请求示例：

POST /oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=https://your-app.com/callback
&client_id=your_client_id
&client_secret=your_client_secret

响应示例：

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "def50200de9a3a7a...",
    "scope": "read write"
}

2.2.3 客户端凭证模式

请求示例：

POST /oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=your_client_id
&client_secret=your_client_secret
&scope=read

2.2.4 刷新访问令牌

请求示例：

POST /oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=REFRESH_TOKEN
&client_id=your_client_id
&client_secret=your_client_secret

2.3 OAuth 2.0权限范围（Scopes）

3. 请求规范

3.1 请求头

Content-Type: application/json
Authorization: Bearer your_access_token
X-API-Secret: your_api_secret  # 仅API密钥认证需要
X-Request-ID: unique_request_id  # 可选，用于请求追踪

3.2 通用参数

所有请求都应包含以下通用参数（如适用）：

3.3 签名生成规则

步骤：

1. 将所有参数按参数名ASCII码从小到大排序
2. 使用URL键值对的格式拼接成字符串
3. 在字符串最后加上API Secret
4. 使用MD5加密生成签名

Python示例：

import hashlib
import time

def generate_sign(params, api_secret):
    # 排序参数
    sorted_params = sorted(params.items())
    # 拼接字符串
    sign_str = '&'.join([f'{k}={v}' for k, v in sorted_params])
    sign_str += api_secret
    # 生成MD5
    return hashlib.md5(sign_str.encode()).hexdigest()

# 使用示例
params = {
    'timestamp': int(time.time() * 1000),
    'nonce': 'random_string_123',
    'param1': 'value1'
}
sign = generate_sign(params, 'your_api_secret')

JavaScript示例：

function generateSign(params, apiSecret) {
    // 排序参数
    const sortedParams = Object.keys(params).sort();
    // 拼接字符串
    let signStr = '';
    sortedParams.forEach(key => {
        signStr += `${key}=${params[key]}&`;
    });
    signStr = signStr.slice(0, -1) + apiSecret;
    // 生成MD5
    return md5(signStr);
}

4. 响应格式

4.1 成功响应

{
    "code": 0,
    "message": "success",
    "data": {
        "id": "123",
        "name": "示例数据"
    },
    "timestamp": 1633046400000
}

4.2 错误响应

{
    "code": 1001,
    "message": "参数错误",
    "data": null,
    "timestamp": 1633046400000
}

4.3 OAuth 2.0错误响应

{
    "error": "invalid_request",
    "error_description": "Missing required parameter: client_id",
    "error_uri": "https://api.example.com/docs/errors/invalid_request"
}

4.4 常见错误码

5. 核心接口示例

5.1 用户信息查询

接口地址： GET /users/{user_id}

认证方式： API密钥 或 OAuth 2.0（需要read scope）

请求示例：

GET /users/123456 HTTP/1.1
Authorization: Bearer your_access_token

响应示例：

{
    "code": 0,
    "message": "success",
    "data": {
        "user_id": "123456",
        "username": "john_doe",
        "email": "john@example.com",
        "created_at": "2023-01-01T00:00:00Z"
    }
}

5.2 创建订单

接口地址： POST /orders

认证方式： API密钥 或 OAuth 2.0（需要write scope）

请求示例：

POST /orders HTTP/1.1
Authorization: Bearer your_access_token
Content-Type: application/json

{
    "product_id": "prod_001",
    "quantity": 2,
    "amount": 199.99,
    "currency": "USD",
    "customer_info": {
        "name": "John Doe",
        "email": "john@example.com"
    }
}

响应示例：

{
    "code": 0,
    "message": "success",
    "data": {
        "order_id": "ord_202312010001",
        "status": "pending",
        "created_at": "2023-12-01T10:30:00Z"
    }
}

6. 限流策略

6.1 频率限制

6.2 限流响应

当触发限流时，API会返回：

{
    "code": 1004,
    "message": "请求频率超限",
    "data": null
}

同时会在响应头中包含限流信息：

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1633046500
Retry-After: 60

7. 安全最佳实践

7.1 OAuth 2.0安全实践

• ✅ 使用state参数防止CSRF攻击
• ✅ 确保redirect_uri精确匹配
• ❌ 不要在前端代码中暴露client_secret
• ✅ 使用PKCE增强安全性
• ✅ 定期轮换client_secret

7.2 令牌管理

• ✅ 访问令牌设置短有效期（建议1小时）
• ✅ 安全存储刷新令牌
• ✅ 实现令牌自动刷新机制
• ✅ 及时撤销不再需要的令牌

7.3 通用安全建议

• ✅ 定期更换API密钥
• ✅ 使用HTTPS确保传输安全
• ✅ 验证服务器证书
• ✅ 实现请求签名防止篡改

8. 故障排除

8.1 OAuth 2.0常见问题

问题：收到”invalid_client”错误

原因： 客户端认证失败
解决方案：

1. 检查client_id和client_secret是否正确
2. 确认客户端应用已启用
3. 验证redirect_uri是否与注册的一致

问题：收到”invalid_grant”错误

原因： 授权码或刷新令牌无效
解决方案：

1. 授权码可能已过期（通常5分钟有效期）
2. 授权码已被使用
3. 刷新令牌已过期或撤销

问题：收到”insufficient_scope”错误

原因： 权限不足
解决方案：

1. 检查请求的接口是否需要特定scope
2. 在授权请求中申请足够的scope

8.2 通用问题排查

问题：收到”认证失败”错误

解决方案：

1. 检查API Key和Secret是否正确
2. 确认请求头格式正确
3. 验证时间戳是否在允许的误差范围内（±5分钟）

问题：收到”签名错误”

解决方案：

1. 检查签名生成算法
2. 确认参数排序正确
3. 验证特殊字符的编码处理

8.3 调试工具推荐

• Postman - API测试和调试
• curl - 命令行调试
• OAuth 2.0 Playground - OAuth流程调试
• 浏览器开发者工具 - 网络请求分析