标准业务流程

本章节详细阐述了通过V1接口完成一次典型业务操作（如社保增员）所需遵循的标准交互流程。开发者应按照以下步骤顺序调用API，以确保业务的顺利执行。

业务流程图示

流程步骤详解

步骤一：获取可执行的功能列表

API端点: GET /api/open/getfunctions

目的: 动态发现系统当前所有可用、已启用的业务功能及其对应的唯一标识 functionId。

描述: 在开始任何业务操作前，必须先调用此接口。返回结果将按功能名称（如“社保增员”）组织，并列出支持该功能的城市及各自的 functionId。请根据您的业务需求，选择并记录下正确的 functionId。

步骤二：获取任务数据模板 (推荐)

API端点: GET /api/open/example

目的: 获取指定功能所需的数据结构模板（JSON Schema）。

描述: 将上一步获取的 functionId 作为路径参数传入。接口将返回一个结构化的JSON对象，其中包含了执行该功能所需的所有字段。以 * 开头的字段为必填项。强烈建议基于此模板来构造您的任务数据，以避免字段错误或遗漏。

步骤三：构造数据并新增任务

API端点: POST /api/open/jobAdd

目的: 提交业务数据，创建一个新的自动化任务。

描述: 基于步骤二的模板，填写真实的业务数据。强烈建议在任务数据中提供一个有效的 callbackUrl，以便在任务完成后接收异步通知。将构造完成的JSON对象作为请求体（Request Body）提交。成功后，接口将返回此次任务的唯一记录编号 recordnumber，此编号可用于日志追踪或在未使用回调时进行手动查询。

步骤四：获取任务结果 (推荐使用回调)

获取任务结果主要有两种方式：异步回调（推荐）和主动轮询（备选）。

方式一：通过回调地址接收结果 (推荐)

机制: 在步骤三提交任务时，在请求体中提供一个公网可访问的 callbackUrl。当任务执行完毕（无论成功或失败），社保士兵服务端会自动向该URL发送一个 POST 请求，请求体中包含了完整的任务结果数据。

优点:

高效实时: 无需客户端轮询，结果实时推送。

资源友好: 避免了大量无效的轮询请求，节省了客户端和服务器的资源。

客户端要求:

提供一个稳定、可公网访问的HTTP(S)端点用于接收 POST 请求。

接收到回调后，建议立即返回 HTTP 200 OK 响应，表示已成功接收，避免服务端重试。后续的业务处理应异步进行。

方式二：通过轮询查询结果 (备选)

API端点: GET /api/open/jobGet

适用场景: 当客户端环境无法提供公网回调地址，或仅需一次性查询特定任务结果时使用。

描述: 使用步骤三返回的 recordnumber 作为路径参数，主动向服务端查询任务状态。您需要自行实现轮询逻辑（例如，每隔30秒查询一次），直到任务状态变为“成功”、“失败”或“已终止”。

注意: 频繁的轮询会增加服务器负载，请合理设置轮询间隔。

业务流程图示#

流程步骤详解#

步骤一：获取可执行的功能列表#

步骤二：获取任务数据模板 (推荐)#

步骤三：构造数据并新增任务#

步骤四：获取任务结果 (推荐使用回调)#

方式一：通过回调地址接收结果 (推荐)#

方式二：通过轮询查询结果 (备选)#