美洽API怎么对接？对话客户与工单数据接口使用指南

美洽 API 对接先在后台开发者设置里获取 Access Token，再按业务调用对应接口。需要同步聊天记录就用对话接口，需要读取或更新客户资料就用顾客相关接口，需要创建和查询售后任务就用工单 API。数据要实时同步到自己的 CRM、ERP 或业务系统时，还可以结合 Webhooks 接收对话、顾客和工单变化。核心就四步：获取 Token，选择接口，完成鉴权调用，测试数据同步。

美洽API接口在哪里获取和配置

美洽 API 对接先获取 Access Token，再按业务选择对应接口。官方入口在设置里的开发者和 APIs。

先获取API访问凭证

• 获取Access Token： 进入美洽后台的设置、开发者、APIs，获取工作台 Access Token，后续接口请求会用到。

• 注意Token失效： 美洽官方说明，重复获取新的 Access Token 会让上一次获取的 Token 失效，正式系统不要频繁重置。

• 妥善保存凭证： Access Token 属于接口访问凭证，不要写在公开网页或前端代码里，建议由服务器端统一保存和调用。

再选择对应API接口

• 对话API： 需要拉取客服聊天、来源页、着陆页等对话信息时，使用对话相关 API。

• 客户API： 需要读取客户资料、同步客户信息时，使用顾客相关接口。美洽 APIs V2.0 支持查询顾客数据。

• 工单API： 需要创建、查询或同步工单时，使用独立的工单开放 API，不要和普通对话接口混用。

美洽对话数据API怎么调用

对话 API 主要用来读取客服聊天记录和来源信息。调用时先完成鉴权，再按对话 ID 或时间范围查询数据。

先确认要查询哪类对话

• 单个对话： 已经知道对话 ID 时，可以直接查询对应会话，适合查看某一条客户聊天记录和来源信息。

• 批量对话： 需要同步一段时间内的客服对话时，可以使用批量查询接口，再按分页继续拉取。

• 来源数据： 对话模型里还能拿到来源页、着陆页、对话页和搜索引擎等信息，方便同步到自己的 CRM 或数据系统。

再做好分页和数据同步

• 设置时间范围： 批量查询时先明确开始和结束时间，不要一次拉取过大的数据范围。

• 处理分页： V2.0 使用 page_token 继续查询，每次最多拉取 20 条对话，直到 next_page_token 为空为止。

• 保存唯一ID： 对话同步到自己的系统后，保留对应对话 ID，后续更新和排查时更容易避免重复导入。

美洽客户资料API怎么读取和更新

客户 API 主要用来查询和同步客户资料。先用客户唯一标识和时间范围读取数据，再根据业务需要同步到自己的 CRM 或客户系统。美洽 APIs V2.0 支持按创建时间或最后更新时间查询顾客数据。

先读取客户资料

• 查询客户数据： 可以读取姓名、电话、微信、邮箱、备注和客户唯一标识等已有资料。

• 按时间批量查询： 需要同步大量客户时，可以按创建时间或最后更新时间分批查询，避免每次全量拉取。

• 处理分页数据： 批量查询需要根据返回的分页 Token 继续请求，直到全部客户数据获取完成。

再做好客户数据同步

• 保留客户唯一ID： 同步到 CRM 后保存对应客户标识，避免同一个客户被重复创建。

• 更新客户资料： 企业需要把自己的客户数据同步到美洽时，应按官方顾客中心服务端接口方案对接，不要直接修改接口返回数据。

• 监听客户变化： 如果需要客户资料发生变化后自动同步，可以结合 Webhooks 接收 client.created 和 client.updated 事件。

美洽工单API怎么创建和查询

工单 API 主要用来让自己的系统创建、查询和同步美洽工单。先获取 Access Token，再读取工单模板，最后按模板字段创建工单。

先准备工单创建信息

• 获取工单模板： 创建工单前先查询模板列表，拿到 templateId 和对应字段，避免提交时字段不匹配。

• 填写工单内容： 创建时至少要准备工单标题和模板 ID，还可以填写优先级、负责人、客户信息、截止时间和附件。

• 避免重复创建： 可以使用 requestId 作为同一条工单的唯一请求标识，用来减少重复保存。

再做好工单查询和同步

• 查询工单数据： 美洽工单开放 API 支持创建工单和获取工单数据，适合把售后任务同步到自己的业务系统。

• 保留工单标识： 工单进入自己系统后，保存对应 ID，后续查询、更新和关联客户时更容易匹配。

• 需要实时同步： 如果希望工单发生变化后自动通知自己的服务器，可以继续结合 Webhooks 接收工单事件。

美洽API与Webhooks怎么做数据同步

API适合主动查询数据，Webhooks适合数据变化后自动推送。两者一起用，更适合对接CRM、ERP或内部业务系统。

先分清API和Webhooks用途

• API主动查询： 需要查询对话、客户或工单数据时，由自己的系统主动调用美洽API获取。

• Webhooks自动推送： 对话创建、客户资料更新、工单状态变化后，可以通过Webhooks把变化主动推送到自己的服务器。

• 按业务组合使用： 历史数据用API查询，实时变化用Webhooks接收，不需要频繁全量拉取数据。

再做好同步安全和去重

• 校验请求来源： 接收Webhook数据时要按官方规则校验签名，避免把异常请求当成真实业务数据。

• 保存唯一标识： 对话、客户和工单同步后保留对应ID，避免同一数据被重复写入自己的系统。

• 异常做好补偿： Webhook处理失败时，可以再通过API查询对应数据补齐，保证CRM或业务系统里的记录完整。

常见问题