吉客云观远数据连接器接入与接口授权说明
1. 适用范围
本文用于指导客户在观远数据连接器中创建“吉客云”数据账户，并完成连接测试。根据观远连接器平台配置，吉客云数据账户采用自研应用密钥方式验证，需要填写 appKey 和 appSecret。
吉客云开放平台面向外部系统提供 API 接口、业务接入指南和联调用例等能力。客户需要先在吉客云开放平台开通开放平台服务、创建自研类型应用，并确认待同步业务接口已完成订阅或授权后，再在观远连接器中创建数据账户。
2. 申请吉客云对接资质
2.1 登录吉客云开放平台
使用具备管理权限的吉客云账号进入 吉客云开放平台。如果页面提示暂未开通开放平台服务，请先按吉客云官方流程开通开放平台服务；未开通时通常无法使用开放平台 API、应用管理和接口订阅能力。
进入开放平台后，打开“应用列表”。如果当前账号无法看到“创建应用”、应用列表或“API接口订阅”等入口，请联系企业内吉客云管理员或吉客云官方支持确认账号权限。
如图，进入“应用列表”后点击左侧“创建应用”创建自研应用；创建完成后，在列表的 AppKey 列定位应用编号。截图来自吉客云官方公开应用列表，未登录时不显示真实应用数据。
2.2 创建自研应用并获取密钥
在“应用列表”中点击“创建应用”，按页面提示完成自研应用创建。应用创建后，列表会显示该应用的 AppKey；在同一行“操作”列点击“查看”，打开“应用信息”弹窗，即可查看并复制 AppKey 与 AppSecret。请只在受控环境中保存 AppSecret，不要将其发送到群聊、工单或截图中。
如图，创建应用时填写“应用名称”并保存即可，AppKey 无需手工填写，由吉客云系统自动生成。保存后回到“应用列表”，通过目标应用所在行的“操作”→“查看”打开“应用信息”，获取 AppKey 和 AppSecret。
“应用信息”弹窗含有真实密钥，无法从未登录的公开页面取得。请以该路径定位字段：应用列表 → 目标应用 → 操作 → 查看 → 应用信息 → AppKey / AppSecret。如需在最终版文档中展示该步骤，请提供一张已将密钥值打码的弹窗截图。
吉客云公共请求参数中包含 appkey、sign 等字段；官方接口说明中也注明自研应用不需要传 token，ISV 应用才需要先完成商家授权并获取 token。观远吉客云连接器按自研应用密钥方式创建数据账户，因此客户侧需要准备应用编号/密钥对应的 appKey 和 appSecret。
2.3 订阅或确认 API 接口权限
在“应用列表”中找到目标应用，在同一行“操作”列点击“API接口订阅”，确认观远需要同步的业务接口已经开通。若只创建应用但未订阅接口，连接测试可能成功，但后续同步某些业务数据时仍可能因接口未授权或接口权限不足而失败。
2.4 需要保存的资质字段
| 资质字段 | 获取位置 | 用途 |
|---|
| appKey | “应用列表”中目标应用所在行的 AppKey 列，或“操作”→“查看”→“应用信息”弹窗 | 填写到观远连接器吉客云数据账户，用于识别调用方应用 |
| appSecret | “应用列表”中目标应用所在行的“操作”→“查看”→“应用信息”弹窗 | 填写到观远连接器吉客云数据账户，用于接口签名或密钥校验，请妥善保管 |
3. 创建观远连接器数据账户
3.1 打开数据账户创建页面并选择平台
在观远数据连接器中进入数据账户管理，点击新增数据账户，在“所属平台”中选择“吉客云”。选择平台后，表单会展示账号名称、appKey 和 appSecret 等字段。
3.2 字段映射关系
| 吉客云开放平台字段 | 观远连接器字段 | 是否必填 | 说明 |
|---|
| appKey / appkey / 应用编号 | appKey | 是 | 填写从吉客云自研应用中获取的应用编号或 AppKey。不同页面大小写展示可能不同，填写时以连接器字段 appKey 为准。 |
| appSecret / 应用密钥 | appSecret | 是 | 填写从吉客云自研应用中获取的应用密钥。请避免多复制空格、换行或无关字符。 |
3.3 填写、测试连接并保存
填写账号名称、appKey 和 appSecret 后，点击“测试连接”。测试成功后保存数据账户。若测试失败，请先核对密钥是否完整、是否属于当前吉客云企业和当前应用，再确认开放平台服务、应用状态和接口权限是否已生效。
4. 已支持的接口范围
观远吉客云连接器已配置的接口覆盖销售、库存、商品、客户、订单、采购、出入库和售后等业务主题。实际可同步的数据范围仍受吉客云开放平台接口订阅、应用权限和客户业务数据权限影响。
| 业务主题 | 已配置接口示例 |
|---|
| 渠道与基础资料 | 销售渠道查询、开放平台仓库查询、供应商查询、客户档案列表 |
| 商品与价格 | 分页查询货品信息、查询组合装、货品价目查询、开放平台供应商货品价目查询按需 |
| 库存与调拨 | 库存分页查询、调拨查询、出库查询（规格模式） |
| 销售与订单 | 销售单查询、销售单查询-游标、销售单查询-归档、查询发货单（分页）、网店订单列表详情 |
| 采购与出入库 | 采购单查询、入库查询、分页查询出库申请单、分页查询出库单 |
| 售后与财务相关 | 分页查询退换补发单（新）、分页查询补偿退款单（新）、客户报价单主单查询、客户报价单商品查询 |
5. 常见问题
| 问题 | 处理建议 |
|---|
| 不知道在哪里获取 appKey 或 appSecret | 请登录吉客云开放平台，进入“应用列表”。AppKey 显示在目标应用所在行；点击该行“操作”中的“查看”，在“应用信息”弹窗中查看 AppKey 和 AppSecret。若入口不可见，请确认开放平台服务和账号权限。 |
| 测试连接提示认证失败 | 检查 appKey 和 appSecret 是否填反、缺少字符或包含多余空格；确认应用状态正常，且密钥属于当前需要接入的吉客云企业。 |
| 测试连接成功，但部分接口同步失败 | 继续核对对应 API 是否已在吉客云开放平台订阅或授权，并确认当前应用具备访问该业务数据的权限。 |
| 接口返回数据为空 | 确认吉客云侧对应业务模块存在数据，并检查同步任务的时间范围、店铺/仓库/渠道等过滤条件是否覆盖目标数据。 |
| 密钥泄露或人员变更 | 请在吉客云开放平台按官方流程重置或更换应用密钥，并及时更新观远连接器数据账户中的 appSecret。 |
| 
