接口集成
功能概述
什么是接口集成
接口集成是 BPMAX 平台提供的一项核心能力，允许您在流程中调用外部系统的 API 接口，实现与第三方系统的数据交互和业务协同。通过接口集成，您可以：
- 在流程执行过程中获取外部系统的数据
- 将流程数据推送到外部系统
- 实现跨系统的业务流程自动化
- 构建统一的业务处理平台
支持的接口类型
BPMAX 支持以下两种类型的接口：
1. HTTP 接口
标准的 HTTP/HTTPS 接口，支持：
- RESTful API
- SOAP Web Service
- 自定义 HTTP 接口
2. 平台内置接口
平台预置的常用第三方系统接口，包括：
- 企业微信：消息发送、用户管理、部门管理等
- 飞书：消息推送、日历事件、用户管理等
内置接口的优势：
- 无需了解接口技术细节
- 配置简单，只需设置实例参数
- 平台自动处理鉴权和请求封装
- 开箱即用，快速集成
接口集成的应用场景
- 数据同步：在流程中自动同步外部系统的数据
- 业务触发：流程执行时触发外部系统的业务操作
- 数据验证：调用外部接口验证表单数据的合法性
- 信息查询：实时查询外部系统的业务信息
- 消息通知：通过外部接口发送通知消息
核心概念
接口平台（API Platform）
接口平台是一组相关接口的集合，通常对应一个外部系统。例如：
- 企业微信平台：包含发送消息、获取用户信息等接口
- CRM 系统平台：包含客户查询、订单创建等接口
接口定义（API Definition）
接口定义描述了具体的 API 接口信息，包括：
- 请求方法（GET、POST、PUT、DELETE 等）
- 请求路径
- 请求参数结构
- 响应数据结构
接口实例（API Instance）
接口实例是接口平台的具体配置实例，包含：
- 基础 URL
- 鉴权信息
- 环境配置（开发、测试、生产等）
- 自定义参数
一个接口平台可以创建多个实例，用于不同的环境或不同的配置需求。
文档导航
本文档分为以下几个部分，您可以根据需要查阅：
📚 核心文档
- 内置接口使用指南 - 企业微信、飞书等内置接口的详细说明
- 自定义接口配置 - 如何配置和管理自定义 HTTP 接口
- 接口调用方法 - 在脚本和流程中调用接口的详细方法
- 鉴权方式详解 - 各种鉴权方式的配置和使用
- OpenAPI 集成 - OpenAPI 文档的导入和导出
- 调试与排查 - 错误排查、日志查看和调试技巧
🚀 快速开始
使用内置接口（推荐新手）
如果您需要集成企业微信、飞书等常见平台，建议直接使用内置接口：
配置自定义接口
如果您需要集成其他系统的 API：
导入 OpenAPI 文档
如果您的外部系统提供了 OpenAPI 文档：
- 查看 OpenAPI 集成
- 导入 OpenAPI 文档自动创建接口定义
- 配置接口实例
- 参考 接口调用方法 在流程中使用
使用接口集成
步骤 1：进入系统集成
在管理后台进入 系统集成。系统集成首页展示当前可用的集成平台、API 数量、实例数量和调用成功率，支持按系统名称搜索、按分类筛选、切换全局环境，以及创建自定义平台。
列表中的平台分为两类：
- 内置平台：系统预置的常用平台，通常已经带有 API 定义，只需要补充实例配置。
- 自定义平台：由管理员创建，用于接入企业内部系统或其他第三方 HTTP API。
步骤 2：设置全局环境
点击首页右上角的 环境配置，选择当前系统运行环境。环境配置会影响后续 API 调用选择哪个实例，例如生产环境会优先使用环境类型为 prod 的实例。
保存环境配置前，需要确认对应平台已经创建同环境类型的实例。否则脚本调用时可能找不到可用实例。
步骤 3：查看平台详情
点击平台卡片进入平台详情页。详情页包含 系统概览、实例管理、API接口、调用日志 四个标签页。
常用检查项：
- 在 系统概览 查看平台名称、分类、集成状态、API 数量、实例数量和成功率。
- 在 实例管理 维护不同环境的连接配置。
- 在 API接口 管理接口定义、导入或导出 OpenAPI 文档，并复制调用示例。
- 在 调用日志 查看请求、响应、耗时和错误信息。
步骤 4：配置接口实例
在平台详情页切换到 实例管理，点击 添加实例。
实例用于保存访问外部系统所需的环境级配置，包括实例名称、实例 Key、环境类型、基础 URL、超时时间、重试次数、认证类型、默认请求头、脚本配置和自定义参数。
配置时注意：
- 实例 Key 在全局范围内应保持唯一，建议能体现平台和环境，例如
crm_prod。 - 环境类型 应与首页的环境配置匹配，常用值包括
dev、test、pre、prod。 - 基础 URL 只填写外部系统的服务根地址，不要包含具体接口路径。
- 认证类型 根据外部系统要求选择；敏感凭证只写入实例配置，不要写入流程脚本或文档示例。
- 脚本配置 适合处理签名、Token 刷新、响应格式转换和统一错误处理。
详细步骤请参考：
步骤 5：管理 API 定义
在平台详情页切换到 API接口。该页面支持搜索 API、按请求方法筛选、导入 API、导出 OpenAPI、新建 API、打开接口文档和复制调用代码。
新建或编辑 API 时，需要配置接口名称、API Key、请求方法、API 路径、版本、状态、描述，以及 Header、Path、Query、Body 参数定义。页面右侧的调试区会根据当前配置预览请求信息，并支持选择调试环境后发送请求。
API Key 是脚本调用接口时使用的稳定标识。保存后，流程脚本可以通过 $proxy('平台标识').接口方法Key(...) 或链式调用方式执行接口。
步骤 6：在流程中调用接口
配置完成后，您可以在脚本或流程节点中调用接口：
// 直接调用接口
const result = await $proxy('平台标识').接口方法Key(参数);
// 使用链式调用
const result = await $proxy('平台标识')
.$api('接口方法名')
.$query({ 参数key: 'value' })
.$call();调用时可以通过 options.instance_key 指定实例；不指定时，系统会结合当前环境和平台配置选择实例。详细方法请参考：接口调用方法。
核心特性
多环境支持
BPMAX 支持为接口实例配置不同的环境类型（开发、测试、预发、生产），您可以为同一个接口平台创建多个实例，在调用时灵活切换。
详细说明请参考：自定义接口配置 - 环境配置
请求/响应脚本
接口实例支持配置请求前脚本、响应后脚本和错误处理脚本，用于在请求前后执行自定义逻辑，如动态修改参数、转换数据格式、记录日志等。
详细说明请参考：接口调用方法 - 高级用法
重试机制
系统支持自动重试失败的请求，采用指数退避策略，可配置最大重试次数和重试条件。
详细说明请参考：调试与排查 - 性能优化
日志记录
所有接口调用都会自动记录到 Elasticsearch 中，包括请求信息、响应信息、调用耗时、错误信息等，支持按多种条件查询和分析。
详细说明请参考：调试与排查 - 日志查看
错误处理
- 优雅降级：接口调用失败时提供备用方案，避免流程中断
- 重试策略：对临时性错误进行重试，使用指数退避策略
- 错误通知：对关键接口的失败进行告警，及时通知相关人员
详细说明请参考：调试与排查
常见问题
如何选择使用内置接口还是自定义接口？
接口调用失败如何排查？
- 查看接口调用日志，确认请求参数和响应信息
- 检查鉴权配置是否正确
- 在接口配置页面使用测试调用功能验证接口配置
- 检查网络连接和外部系统状态
详细排查方法请参考：调试与排查
支持哪些鉴权方式？
系统支持无鉴权、Basic Auth、Bearer Token、API Key、OAuth 2.0、自定义鉴权等多种方式。
详细说明请参考：鉴权方式详解
相关功能
实体映射
如果您需要将不同第三方接口的响应数据统一为标准格式，可以使用 实体映射 功能：
- 定义标准实体：为用户、订单等业务对象定义统一的数据结构
- 配置响应映射：将接口响应自动转换为标准实体格式
- 简化业务逻辑：上层业务只需适配一套标准结构