API 文档

Shifton 任务允许您通过开放的 API 把平台的工作自动化，并把它接入外部服务。通过 API 可以访问所有关键实体 — 任务、客户、员工、检查清单、库存、服务区域、财务文件文档和报告 — 因此 Shifton 可以与您的 HR、工资计算 和分析系统对接，也可以与公司的内部服务对接。

文档发布了两个版本：

🚀 新文档 — 参考手册的最新版本，结构已更新，包含最新的方法： 👉 https://api2.shifton.com/openapi/
📄 旧文档 — 上一个版本（对已有的集成仍然继续支持）： 👉 https://api2.shifton.com/docs/

两个版本都可以直接从应用中打开 — 在 Developer 部分的概览标签页上，用 “新文档” 和 “旧文档” 按钮打开。

文档提供两种语言。 在新文档页面的右上角有一个 EN / RU 切换开关 — 所选语言会被记住。

如何获取 API 密钥

API 密钥在应用中创建：

打开 Developer 部分。
切换到 API 密钥 标签页（“API 密钥”）。
点击 “创建 API 密钥”。

创建密钥时要填写什么

系统会打开 创建 API 密钥 侧边面板，其中包含以下字段：

标题 — 密钥的名称，必填字段。请按用途命名，以便日后清楚该停用哪一个：“导出到 1C”、“分析用报告”。
过期时间 — 该日期之后密钥将失效。如果留空，则有效期不受限制。
访问 — 密钥的权限范围：
Full access (act as me) — 密钥以您的身份、按您的权限工作。
受限权限 — 由您自己选择的有限权限集合。

点击添加以创建密钥，或点击取消关闭面板。

📷 *密钥创建面板的截图 — 需在生产环境截取*

密钥是 针对特定公司 创建的，只能操作该公司的数据。密钥随时可以撤销 — 撤销立即生效，之后使用该密钥的所有请求都会返回错误 401。

重要: 创建好的密钥 只显示一次。请立刻复制并保存在安全的地方 — 无法再次获取它。如果密钥丢失，请创建一个新的并撤销旧的。

授权

所有对 API 的请求都在请求头中用密钥签名：

Authorization: Bearer {your_API_key}

API 的基础地址：

https://api2.shifton.com/work/1.0.0

没有有效密钥的请求会返回 401 和响应体 {"message":"Unauthenticated."}。

第一个请求

例如，要获取公司的员工列表（把 {companyId} 替换成您自己的公司 ID）：

GET https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees
Authorization: Bearer {your_API_key}
Accept: application/json

用 curl 做同样的事：

curl -H "Authorization: Bearer {your_API_key}" \
     -H "Accept: application/json" \
     https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees

公司 ID 可以在应用的地址栏中看到：app.shifton.com/c/8397/... — 也就是 /c/ 后面的那个数字。

通过 API 可以访问什么

参考手册涵盖 360 多个方法。外出服务的主要部分有：

任务 — /companies/{companyId}/tasks：创建、修改、状态、任务文件。
待办事项列表 (To Do) — /companies/{companyId}/todo。
客户 — /companies/{companyId}/clients，以及客户的地址和自定义字段。
检查清单 — /companies/{companyId}/checklists。
服务区域 — /companies/{companyId}/tasks/service-areas。
技能 — /companies/{companyId}/skills。
员工 — /companies/{companyId}/employees：添加、编辑、解雇和恢复。
库存 — 物品、类别、套件以及仓库余量。
财务文件 — 报价单、工单、发票、收据、文件计数器和标志。
报告 — 导出工作和出勤数据。

此外，还可以访问排班和班次、假期和请假申请、出勤、计费和短信计费、通知以及模块。

Webhook

如果您不想定期轮询 API，而是希望在事件发生的那一刻就收到它，请使用 Webhook — 位于 Developer 部分的 Webhooks 标签页。当所需事件发生时，Shifton 会自己向您的地址发送请求；支持的事件列表由一个单独的方法返回。

错误代码

Shifton API 使用标准的 HTTP 状态码：

200 — 请求执行成功。
201 — 对象创建成功。
400 — 请求参数不正确。
401 — 授权错误：未传递密钥、密钥无效或已被撤销。
403 — 访问被拒绝。
404 — 未找到资源（最常见的原因是方法地址拼写有误）。
500 — 服务器错误。

使用建议

对于新的集成，请使用 新文档 — 旧文档保留是为了已经在运行的集成。
检验请求时可以方便地使用 Postman 或 curl — 它们让您不用写一行代码就能看到响应。
请不要在代码中以明文保存密钥，也不要把它交给第三方：密钥可以访问公司的数据。
请遵守 请求频率限制（rate limits）— 超出限制可能导致 API 访问被临时封禁。

常见问题

问题：在哪里获取 API 密钥？ 回答： 在应用中：Developer 部分 → API 密钥 标签页 → “创建 API 密钥” 按钮。密钥是为当前公司签发的。

问题：我关掉了窗口，没有复制密钥。在哪里能看到它？ 回答： 哪里都看不到 — 密钥只显示一次，不会再次签发。请创建一个新密钥，并撤销旧的。

问题：如果密钥落到了不该落的人手里，如何撤销它？ 回答： 请在 API 密钥 标签页中删除它。撤销立即生效：使用该密钥的所有请求会马上开始返回 401。

问题：“Full access”和“Restricted permissions”有什么区别？ 回答： Full access (act as me) 让密钥拥有和您相同的权限。受限权限 则可以只给密钥授予选定的权限集合 — 对于只需要访问部分数据的集成来说，这样更安全。

问题：可以限制密钥的有效期吗？ 回答： 可以，创建时使用 过期时间 字段。如果不填写，密钥就是永久有效的。

问题：一个密钥可以用于多家公司吗？ 回答： 不可以。密钥绑定在创建它的那家公司上，只能操作该公司的数据。对于另一家公司，请创建单独的密钥。

问题：API 的基础地址是什么？ 回答： https://api2.shifton.com/work/1.0.0。后面接方法的路径，例如 /companies/{companyId}/tasks。

问题：请求所需的公司 ID 从哪里获取？ 回答： 它就在应用地址栏中 /c/ 的后面 — 例如在 app.shifton.com/c/8397/tasks 中，公司标识符就是 8397。

问题：应该使用哪个版本的文档？ 回答： 新集成用新版（api2.shifton.com/openapi）。旧版（api2.shifton.com/docs）为已有的集成继续提供支持。

问题：有俄语版文档吗？ 回答： 有。在新文档页面的右上角有 EN / RU 切换开关。

问题：用什么来测试对 API 的请求？ 回答： 最方便的是 Postman 或 curl — 它们让您可以发送请求并查看响应，而无需编写代码。

问题：为什么我复制了密钥，却还是收到 401？ 回答： 请检查密钥是否放在 Authorization 请求头中并且前面带有 Bearer 这个词，以及密钥是否未被撤销、有效期是否未过。

问题：为什么会收到 404？ 回答： 最常见的原因是地址搞错了：基础部分应该是 https://api2.shifton.com/work/1.0.0，而方法路径中的 {companyId} 要填写正确。

问题：通过 API 可以自动化哪些工作？ 回答： 创建和修改任务、处理客户及其地址、检查清单、服务区域、技能、员工、库存、财务文件文档和报告导出，以及排班、班次和假期。

问题：可以从 Shifton 接收事件，而不是轮询 API 吗？ 回答： 可以，为此提供了 Webhook — 位于 Developer 部分的 Webhooks 标签页。

问题：更改密码会影响集成的运作吗？ 回答： 不会。集成使用 API 密钥工作，而不是账户密码。