YouDo Business API 技能

本技能提供与YouDo Business API交互所需的知识和指南。

基础URL

• - 生产环境: https://business-api.youdo.com/api/v1
• 沙箱/测试环境: https://business-api.public-test.youdo.sg/api/v1
• Swagger文档: https://business-api.youdo.com/api/doc/index.html

身份认证

所有请求均使用RS256非对称算法签名的JSON Web Token (JWT)。

• - JWT必须在请求头中发送：Authorization: Bearer
• 头部: {alg: RS256, typ: JWT, kid: <密钥ID>}
• 载荷: {iss: <签发者ID>, cid: <公司ID>}

请求签名

某些方法（如/api/v1/Task/{taskId}/pay）需要请求签名。您必须包含以下请求头：

• - Date: 当前时间，遵循RFC 7231格式（例如：Tue, 19 Feb 2019 08:43:02 GMT）
• Content-SHA256: 请求体的SHA256十六进制哈希值（GET请求为空字符串）
• Signature: 请求字符串的RS256签名十六进制字符串

待签名字符串格式：

大写(请求方法) + \n
请求路径 + \n
请求查询参数 + \n // 按字母顺序排序，URL编码
已签名请求头 + \n // 按字母顺序排序，键名小写
SHA256十六进制(请求载荷)

关键端点

员工（Исполнители）

• - 创建: POST /Employee

• - 获取信息: GET /Employee/{id}
• 搜索: POST /Employe/search (请求体: projectIds, employeeName, inns, phones, itemsPerPage, page)
• 按手机号查找: GET /Employe/byPhone/{phone}
• 添加到项目: POST /Employee/addToProject
• 从项目移除: DELETE /Employee/{id}/deleteFromProject/{projectId}
• 重新绑定: PUT /Employee/{id}/binding/restart

项目（Проекты）

• - 获取项目列表: GET /Project/Projects

任务与支付（Задания и выплаты）

• - 创建内部任务: POST /Task/internal
• 创建外部任务: POST /Task/external
• 获取任务: GET /Task/{taskId}
• 更新任务: PUT /Task/{taskId}
• 支付任务: POST /Task/{taskId}/pay (需要请求签名)
• 重新发送邀约: PUT /Task/{taskId}/resendOffer

文档（Документы）

• - 下载文档: GET /Documents/{documentId}
• 下载证书: GET /Documents/{documentId}/certificate

支付报告（Отчет агента）

• - 列出支付记录: POST /Payments (请求体: from, to, inn, taskIds, ids)

框架协议（Рамочные соглашения）

• - 获取协议: GET /FrameworkAgreements/employees/{employeeId}/projects/{projectId}
• 创建: POST /FrameworkAgreements
• 终止: POST /FrameworkAgreements/{agreementId}/stop

预付款发票（Счета на предоплату）

• - 创建: POST /prepaymentInvoices (请求体: companyId, amount)
• 获取: GET /prepaymentInvoices/{id}

余额（Баланс）

• - 按公司查询: GET /Balance/byCompany?companyId={id}
• 按项目查询: GET /Balance/byProject?projectId={id}

Webhooks

• - 订阅: POST /WebHook/subscribe (请求体: type, url, headers)
• 取消订阅: DELETE /WebHook/{type}/unsubscribe