美洽单点登录怎么设置？企业内部系统一键登录美洽方法

美洽单点登录主要用于让客服从企业内部系统直接进入美洽工作台。先在美洽后台获取 Access Token，再保证内部系统用户邮箱与美洽客服邮箱一致。企业服务器通过接口提交客服邮箱，获取临时登录地址，再把这个地址放到内部系统的登录按钮中。客服点击后即可跳转登录美洽，无需再次输入账号密码。核心就是：获取 Token，匹配客服邮箱，生成临时登录地址，一键跳转登录。

美洽单点登录需要准备什么

美洽单点登录接入前，先准备 Access Token、客服邮箱和企业内部系统。最关键的是内部用户邮箱必须和美洽客服邮箱保持一致。

先准备账号和接口信息

• Access Token： 管理员进入美洽工作台的设置、开发者、APIs，获取接口调用需要的 Access Token。

• 客服邮箱： 企业内部系统里的用户邮箱，要和美洽对应客服账号邮箱一致，否则无法正确生成登录地址。

• 内部系统入口： 企业需要在自己的OA、CRM或其他内部系统里准备一个跳转入口，让客服点击后直接进入美洽。

再确认技术对接条件

• 服务器端调用： 临时登录地址需要通过服务端接口获取，不建议把 Access Token 直接放在前端页面。

• 邮箱一一匹配： 每个内部账号都要对应正确的美洽客服邮箱，避免客服登录到错误账号。

• 临时地址及时使用： 美洽返回的单点登录 URL 有效期为 2 分钟，生成后应立即跳转使用。

美洽Access Token在哪里获取

Access Token 在美洽工作台的开发者设置里获取。单点登录和 API 调用都会用到这个凭证。

先进入开发者设置

• 打开APIs页面： 使用企业管理员账号登录美洽工作台，进入设置，再打开开发者里的 APIs。

• 获取Access Token： 在 APIs 页面获取当前工作台的 Access Token，后续单点登录接口需要使用这个 Token。

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

再安全使用Token

• 放在服务器端： Access Token 不要写进网页前端或公开代码，应由企业服务器保存和调用。

• 接口带上Token： 请求单点登录地址时，需要在 Authorization 中使用 Bearer 方式携带 Access Token。

• 修改后同步更新： 如果重新获取了 Token，企业内部系统也要同步更新，否则旧 Token 会导致接口调用失败。

企业系统怎么生成美洽临时登录地址

企业内部系统要实现一键登录，本质就是服务器拿客服邮箱去请求美洽接口，换回一个临时登录 URL，再让用户直接跳转。

先由服务器请求登录地址

• 提交客服邮箱： 企业服务器调用美洽单点登录接口时，需要传入对应客服的 agent_email，而且这个邮箱必须和美洽客服账号一致。

• 带上Access Token： 请求头里使用 Bearer 方式携带 Access Token，用来完成接口鉴权。

• 获取临时URL： 请求成功后，美洽会返回一个临时登录地址，企业系统直接读取返回的 url 即可。

再让客服一键跳转登录

• 放到登录按钮： 企业OA、CRM或内部系统里的美洽入口，点击后先请求临时 URL，再立即跳转。

• 不要提前生成： 美洽官方说明，临时登录 URL 有效期只有 2 分钟，所以最好点击时实时生成。

• 失败先查邮箱和Token： 返回 401 通常先检查 Access Token，返回客服邮箱不存在时，就核对内部系统邮箱和美洽客服邮箱是否一致。

美洽客服邮箱怎么和内部账号匹配

单点登录能不能成功，关键就是企业内部账号邮箱和美洽客服邮箱必须一致。美洽官方明确要求两边使用相同邮箱。

先统一客服邮箱

• 邮箱保持一致： 企业OA、CRM或内部系统里的用户邮箱，要和美洽客服账号登录邮箱完全相同。

• 避免填写错账号： 同一个员工如果有多个邮箱，要提前确定哪一个作为美洽登录邮箱，避免接口找不到客服。

• 新增员工及时同步： 新客服加入后，先创建并激活美洽客服账号，再把内部系统对应邮箱同步一致。

再做好账号映射

• 按邮箱查找客服： 企业系统生成临时登录地址时，把当前用户邮箱作为 agent_email 提交给美洽接口。

• 不存在就先检查邮箱： 如果接口提示客服邮箱不存在，优先检查大小写、拼写和账号是否已经创建。

• 不要多人共用邮箱： 每个客服最好使用自己的独立账号和邮箱，方便单点登录后准确进入对应客服身份。

美洽单点登录失败怎么排查

单点登录失败，先查 Access Token、客服邮箱和临时登录 URL。官方常见报错主要就是 Token 无效或客服邮箱不存在。

先检查接口参数

• Access Token无效： 接口返回 401 时，先确认当前使用的 Token 是否正确。重新获取 Token 后，旧 Token 会失效，企业系统也要同步更新。

• 客服邮箱不存在： 返回客服邮箱不存在时，检查内部系统传入的 agent_email 是否和美洽客服邮箱完全一致。

• 请求格式错误： 确认 Authorization 使用 Bearer Token，并正确提交 agent_email，不要漏掉必要参数。

再检查临时登录地址

• URL已经过期： 美洽临时登录 URL 只有 2 分钟有效期，最好用户点击登录按钮时实时生成。

• 不要重复使用旧链接： 临时地址过期后重新请求新的 URL，不要长期保存同一个登录链接。

• 逐项重新测试： Token、邮箱和 URL 都确认无误后，再从企业内部系统点击一次登录入口，确认能正常跳转美洽工作台。

常见问题