接口集成
功能概述
什么是接口集成
接口集成是 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：创建接口平台
接口平台是一组相关接口的集合。对于内置接口（如企业微信），系统已预置好接口平台，您可以直接使用。
对于自定义接口，需要先创建接口平台：
- 进入系统管理后台
- 导航至 **能力增强 > 集成管理 **
- 点击"添加平台"创建接口平台
详细步骤请参考：自定义接口配置
步骤 2：配置接口实例
接口实例包含了访问外部系统所需的具体配置信息：
- 进入系统管理后台
- 导航至 能力增强 > 集成管理 > 点击某平台 > 实例管理
- 点击"添加实例"
- 填写配置信息（URL、鉴权信息、实例标识等）
- 保存（实例标识不能与其他平台实例重复）
详细步骤请参考：
步骤 3：在流程中调用接口
配置完成后，您可以在脚本或流程节点中调用接口：
脚本调用示例：
// 调用接口
const result = await $proxy('平台标识').接口方法Key(参数);
// 或使用链式调用
const result = await $proxy('平台标识')
.$api('接口方法名')
.$query({ 参数key: 'value' })
.$call();详细方法请参考：接口调用方法
核心特性
多环境支持
BPMAX 支持为接口实例配置不同的环境类型（开发、测试、预发、生产），您可以为同一个接口平台创建多个实例，在调用时灵活切换。
详细说明请参考：自定义接口配置 - 环境配置
请求/响应脚本
接口实例支持配置请求前脚本、响应后脚本和错误处理脚本，用于在请求前后执行自定义逻辑，如动态修改参数、转换数据格式、记录日志等。
详细说明请参考：接口调用方法 - 高级用法
重试机制
系统支持自动重试失败的请求，采用指数退避策略，可配置最大重试次数和重试条件。
详细说明请参考：调试与排查 - 性能优化
日志记录
所有接口调用都会自动记录到 Elasticsearch 中，包括请求信息、响应信息、调用耗时、错误信息等，支持按多种条件查询和分析。
详细说明请参考：调试与排查 - 日志查看
错误处理
- 优雅降级：接口调用失败时提供备用方案，避免流程中断
- 重试策略：对临时性错误进行重试，使用指数退避策略
- 错误通知：对关键接口的失败进行告警，及时通知相关人员
详细说明请参考：调试与排查
常见问题
如何选择使用内置接口还是自定义接口？
接口调用失败如何排查？
- 查看接口调用日志，确认请求参数和响应信息
- 检查鉴权配置是否正确
- 在接口配置页面使用测试调用功能验证接口配置
- 检查网络连接和外部系统状态
详细排查方法请参考：调试与排查
支持哪些鉴权方式？
系统支持无鉴权、Basic Auth、Bearer Token、API Key、OAuth 2.0、自定义鉴权等多种方式。
详细说明请参考：鉴权方式详解
相关功能
实体映射
如果您需要将不同第三方接口的响应数据统一为标准格式，可以使用 实体映射 功能：
- 定义标准实体：为用户、订单等业务对象定义统一的数据结构
- 配置响应映射：将接口响应自动转换为标准实体格式
- 简化业务逻辑：上层业务只需适配一套标准结构
相关资源
其他开发文档
技术支持
如果您在使用接口集成功能时遇到问题，欢迎联系我们：
- 官方网站：https://www.bpmax.cn
- 在线文档：https://docs.bpmax.cn
- 技术支持：support@bpmax.cn