业务要求
产品、市场、用户角色、财务规则、限制及预期结果。
文档 / API 要求
接入 API 前需要准备什么
集成开始前收集项目、访问、数据、安全及测试场景信息，有助于提前明确范围并避免返工。
范围
产品与市场
访问
密钥与环境
数据
格式与状态
验收
场景测试
需求包
工作开始前需要确认的内容
01
项目要求
产品、市场、货币、提供商、用户及运营流程。
02
数据交换规则
请求、字段、标识符、状态、错误及事件。
03
访问与安全
访问密钥、请求签名、允许的 IP 地址、角色及活动日志。
04
测试与验收
测试数据、成功和错误场景、结果验证及上线标准。
概览
统一需求可以缩短交付时间并减少返工
工作开始前，双方应对项目目标、数据来源、操作状态、系统职责、安全规则及验收标准形成一致理解。这样集成即可按约定设计执行，而不是依赖假设。
集成规则
数据交换方式、请求和响应结构、标识符、状态、通知、错误及限额。
验收标准
测试场景、预期数据、报表、运营监控及切换上线的标准。
项目数据
项目与接入系统信息
首先建立整体上下文：接入哪些产品、涉及哪些系统、主要数据存储在哪里，以及各流程由谁负责。
项目范围与目标
产品：赌场、体育博彩、支付、KYC、CRM、奖金、报表或后台管理。
国家、许可、货币、语言、品牌及使用渠道。
用户类型、角色、限额、状态及核心运营场景。
优先级、上线阶段、关键功能及商业限制。
系统与数据所有权
参与流程的内部和外部系统列表。
玩家、余额、交易、投注、奖金或 KYC 检查数据的权威记录系统。
可用 API、数据库、消息队列、通知、文件及旧版接口。
复杂问题对应的责任团队、运营联系人及升级流程。
集成要求
API 数据交换要求
文档应足以让团队无需猜测即可完成集成。每项操作都应提前定义用途、输入数据、结果、可能错误及重试规则。
端点与请求方法
API 基础 URL、请求路径、HTTP 方法、参数、请求头及每项操作的用途。
请求与响应格式
数据类型、必填字段、日期格式、金额精度、允许的 null 值及示例。
操作状态
从创建到完成的完整操作生命周期、允许的状态转换及最终状态。
错误与操作
错误码、明确原因、是否允许重试以及接收系统需要执行的操作。
事件通知
事件结构、签名、投递、接收确认、重新投递及处理顺序。
防重复
唯一操作标识符、识别重复请求以及故障后的安全恢复。
限额与负载
请求频率、超时、并发操作、响应大小及预计峰值负载。
版本变更
API 版本、向后兼容性、通知周期及变更管理流程。
API 访问
API 密钥、OAuth、JWT、服务账号、令牌有效期及定期轮换。
请求签名
HMAC 验证、请求时间以及用于防重放的唯一值。
网络访问
允许的 IP 地址和域名、安全连接、VPN、网络规则以及测试与生产环境隔离。
角色与权限
按照最小权限原则分配服务和员工权限。
数据保护
加密、敏感值遮蔽、保存期限、删除及个人数据处理规则。
活动日志
请求标识符、操作人、时间、变更、错误及关键操作历史。
测试与验收
测试与验收要求
测试环境不仅要覆盖成功操作，还应覆盖错误、延迟、重试、限额及最终报表。
测试环境
独立端点、访问密钥、通知接收方、限制及数据重置规则。
测试数据
用于可重复场景的玩家、货币、支付方式、提供商、状态及数值。
成功场景
从第一个请求到最终状态，并在报表中体现的完整流程。
错误场景
无效数据、超时、重复操作、余额不足、拒绝及提供商错误。
日志与诊断
请求标识符、准确时间、原始状态及联合排查所需数据。
验收
约定的场景列表、预期结果及负责验收签字的人员。
就绪检查清单
开发开始前的最低检查清单
在范围、数据交换规则、访问权限、测试环境及责任方达成一致后，即可开始集成规划。
集成范围已批准
产品、市场、系统、功能及上线阶段均已形成文档。
API 文档可用
端点、数据格式、状态、错误、通知及示例均已记录。
已发放测试访问权限
密钥已激活，允许的 IP 地址及通知端点均已确认。
安全方案已确认
身份验证方式、签名、角色、密钥存储及日志记录均已定义。
测试场景已准备
已具备成功、错误、重复及故障场景。
负责人已分配
已明确产品、开发、测试、安全及支持负责人。