客服 API、事件与批量导出
集成需要的客服模块能力都在这里：工单、消息串、SLA、队列、服务目录、服务保障和满意度调查的接口；带签名、重试与重放的事件订阅；可按游标续读的事件流；工单和消息的批量导出；以及从另一套服务台幂等导入历史工单。每一个接口在 MCP 服务器上都有对应的工具。
客服模块一直都可以通过通用记录 API 访问：工单就是一条记录，所以列出和创建工单本来就能用。行不通的是工单旁边那些不属于记录的东西。消息串、SLA 计时、队列、服务目录、服务保障余额和满意度调查，此前完全没有接口，于是集成能开出工单，却无法回复它。
本文介绍客服接口、MCP 服务器上对应的工具、带重试与重放的事件订阅、可续读的事件流，以及如何把另一套服务台的工单历史导进来。
从哪里开始 - 在“设置 › API 与开发者”里创建一个 API 密钥。密钥会确定你的账户，并把一切限定在这个账户内。 - 每次调用的鉴权方式与 API 其余部分相同：Authorization: Bearer 后面跟你的密钥。 - 本文涉及的一切都位于 /api/v1/service 下，并限定在 ticket 对象上。仅限其他对象的密钥无法访问。 - 每个接口在 MCP 服务器上都有对应的工具，所以接入 SellioCRM 的 AI 智能体能做完全一样的事情。
工单 - GET /api/v1/service/tickets 以扁平行的形式列出工单，可按状态、优先级、队列、负责人或全文筛选。用 updated_since 加时间戳只拉取上次同步之后发生变化的部分，用 limit 和 offset 翻页。 - GET /api/v1/service/tickets/{id} 返回一张工单以及 SLA 计时：到期时间、是否已暂停、首次响应目标和下次响应目标。这个计时正是这个接口存在的理由；通用记录接口返回的是字段，不是时限。 - POST /api/v1/service/tickets 走和工作台一样的通道开单，所以工单编号、SLA 目标、路由规则和出站 Webhook 都会照常发生。 - PATCH /api/v1/service/tickets/{id} 修改状态、优先级、分类、队列和负责人。指派和改状态是同一个动作，所以没有单独的接口。 - GET 和 POST /api/v1/service/tickets/{id}/messages 读写消息串。kind 为 public 时回复客户并发出邮件；kind 为 internal 时留下只有坐席看得到的备注。 - POST /api/v1/service/tickets/merge 合并两张工单：次要工单被主工单吸收，其消息一并转移。
工单周边 - GET /api/v1/service/queues 列出队列及其每位坐席的容量、工作时间和默认优先级。做路由之前先读它：创建接口需要的正是队列名称。 - GET 和 POST /api/v1/service/catalog 读取服务目录并申请其中的服务项。一次申请会开出一张真实工单，带该服务项的队列和优先级；请自行传入 idempotencyKey，这样重试会返回已存在的申请，而不是再开一张工单。 - GET /api/v1/service/entitlements 按账户或合同返回支持服务保障及其剩余余额。 - GET /api/v1/service/surveys 返回满意度调查邀请及其状态和回答日期。匿名调查永远不会返回受访者身份。
事件：实时推送与游标续读 集成需要实时的两半：事情发生的那一刻被通知到，以及在自己宕机期间漏掉的内容能补回来。前者靠订阅，后者靠事件流。
- POST /api/v1/service/subscriptions 登记一个 URL 和你关心的事件。events 接受精确的事件类型，或者 ticket.* 这样的族通配符。未知事件会按名称被拒绝，因为一个永远不会触发的订阅比一个报错更糟。密钥只返回一次，请复制保存。
- 每次投递都是一个 POST，带三个请求头：x-sellio-event 是事件名，x-sellio-delivery 是这次投递尝试的 id，x-sellio-signature 的形式是 sha256 加上用你的密钥对原始报文计算出的校验码。请在你那一侧重新计算并比对；不一致就丢弃这次调用。
- 投递失败会按递增的间隔重试，大约是 1 分钟、5 分钟、30 分钟、2 小时和 6 小时。之后标记为失效，并保留在日志里。
- GET /api/v1/service/deliveries 是“这个事件到底送到了没有”的可查询答案。每一行都带有尝试次数、最后一次的状态码、错误信息和下一次计划重试的时间。
- POST /api/v1/service/deliveries/{id}/replay 重发某一次投递。它重放的是存下来的报文，与第一次发出的逐字节相同。此刻重新拼装报文，等于把今天的状态配上昨天的时间戳发出去。
- GET /api/v1/service/events 是事件流。传入上一次返回的游标，你只会拿到那个位置之后发生的事件。即使这一页为空，nextCursor 也会返回，而它正是你要存下来的东西。请把游标当作不透明字符串：拿它做运算，正是集成日后无声出错的原因。
- GET /api/v1/service/event-types 列出产品能发出的每一个事件、三个 Webhook 登记表中哪些可以订阅它，以及要送达客服订阅是否需要你的账户开启事件总线。创建订阅之前先读它。
导出工单与消息 GET /api/v1/service/export 接受 entity 为 tickets 或 messages，format 为 json 或 csv。消息导出正是这个接口存在的理由：消息串不是记录，所以没有别的入口能批量取出它。可以按 since、status、queue、ticketId 或 kind 筛选，用 limit（最多 500）和 offset 翻页。json 响应会带 hasMore，让你知道后面还有一页。
从另一套服务台导入历史 POST /api/v1/service/import 每次调用最多接受 500 行。每一行需要 externalKey（也就是你正在迁出的那套工具里的工单编号）和 subject。它还可以带 body、报障人的 email、name 和 phone，以及 priority、category、queue、channel、status 和 createdAt。
- 导入按 externalKey 幂等。同一个文件导入两次会把这些行报告为“已存在”，而不是重复创建，所以失败的批次可以放心重跑。
- 工单会带着来源系统的日期和状态诞生。否则一万五千张已关闭的工单会以今天的日期作为新工单落地，淹没正在干活的人的队列，并让每一份按周期统计的报表都失真。
- 传 dryRun 为 true，可以在不写入任何数据的情况下看看会发生什么。
- 校验不通过的行会作为一条记录进入 problems，并带上它在这一批中的位置，这一批的其余部分照常写入。三行日期格式有问题，不会逼你从头再来。