Zoho crm Logo

更新班次时间

目的

通过 API 更新您组织的班次工时。

端点

  • PUT /settings/business_hours/shift_hours

请求详情

请求 URL

{api-domain}/crm/{version}/settings/business_hours/shift_hours

标题

授权:Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
X-CRM-ORG:{your_org_id}

范围

scope=ZohoCRM.settings.business_hours.ALL
(或)
scope=ZohoCRM.settings.business_hours.UPDATE

样本请求

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/business_hours/shift_hours"
-X PUT
-d "@update.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-CRM-ORG:{your_org_id}"

输入 JSON

  • id字符串,必填

    要更新的班次时段的唯一ID。请使用获取班次时段API来获取该ID。

  • timezonestring

    表示您想要设置班次时间的时区。

  • 名称字符串

    班次时段的名称。不得包含以下特殊字符:~ , ` , # , % , & , + , = , [ , ] , { , } , | , ; , < , > , ^

  • shift_daysJSON 数组

    您希望设置班次时间的星期几。请注意,您只能在企业运营的日期设置班次时间。

  • week_starts_onstring

    您的业务开始于一周的哪一天。可选值包括星期日到星期六。

  • same_as_everyday布尔值

    表示班次时间是否每天都相同。当该值为false时,JSON数组custom_timing为必填项。
    当该值为true时,JSON数组daily_timing为必填项。

  • custom_timingJSON 数组,在 same_as_everyday为 false 时为必填项

    在该数组的每个JSON对象中包含以下键:

    • _delete - 用于删除某个工作日班次的自定义时间。该键的值为null。
    • days - string(字符串) - 有自定义班次时间的星期几。例如:"days":"Monday"。
    • shift_timing - JSON 数组 - 该日的班次时间,格式为HH:MM。例如:"shift_timing":["10:00","17:00"]。
  • break_hoursJSON 数组

    在数组的每个 JSON 对象中包含以下键:

    • _delete - 用于删除班次中的特定休息时段。此键的值为 null。
    • same_as_everyday - 布尔值 - true 表示每天的休息时间相同,此时 daily_timing 为必填项。当该值为 false 时,custom_timing 数组为必填项。
    • break_days - JSON 数组 - 允许休息时段的星期几。
    • daily_timing(当 same_as_everyday 为 true 时) - JSON 数组 - 当天休息时间,格式为 HH:MM。例如:"daily_timing":["10:00","10:30"]。注意:每日休息时长不得超过两小时,并且一天最多只能有两次休息。
    • custom_timing(当 same_as_everyday 为 false 时) - JSON 数组 - 当天的休息时间,格式为 HH:MM。例如:"custom_timing":["11:00","01:00"]。注意:每日休息时长不得超过两小时,一天最多只能有两次休息。


      days - 字符串 - 自定义休息时段适用的班次日期。

  • holidaysJSON 数组, 可选 

    使用此数组可以在创建班次时间时关联一个已存在的假期或创建一个新的假期。
    此数组必须包含以下键:

    • name - 字符串,必填 - 假期的唯一名称。请注意,不允许使用特殊字符 ~ 、` 、# 、% 、& 、+ 、= 、[ 、] 、{ 、} 、| 、; 、< 、> 、^。
    • date - 字符串,必填 - 假期所在日期,格式为 YYYY-MM-DD。
    • id - 如需关联已存在假期时为必填 - 已创建假期的唯一 ID。请传递 获取假期 API 返回的假期 ID。
    • _delete - 如需从班次中删除假期时为必填 - 值为 null 时,将该假期从该班次中删除。
  • 用户JSON 数组

    要为其分配这些班次工时的用户ID。使用键 effective_from 将此班次从该日期分配给用户。格式为 YYYY-DD-MM。
    如果未指定该键,用户将立即被分配到该班次。

输入 JSON

Copied{
    "shift_hours": [
        {
            "id":"3652397000011137072",
            "holidays": [
                {
                    "id": "3652397000011137047",
                    "_delete": null
                }
            ],
            "users": [
                {
                    "id": "554023000002209087"
                }
            ]
        }
    ]
}

可能的错误

  • INVALID_DATAHTTP 400

    原因:

    • 以下数据中有一项或多项无效 —— 班次时间、时区、休息时间、开始生效日期。
    • 输入中包含超过两段休息时间。
    • 输入中包含超过七个班次天或休息天。
    • 班次名称包含特殊字符 ~ 、` 、# 、% 、& 、+ 、= 、[ 、] 、{ 、} 、| 、; 、< 、> 、^。
    • 休息时间有重叠。
    • 休息时间超出班次时间范围。
    • “开始生效日期”不是晚于当前日期。

    解决方法:
    请参阅响应中的“details”键,获取输入中有错误字段的API名称。

  • MANDATORY_NOT_FOUNDHTTP 400

    您没有在输入中指定要更新的班次时长的ID。
    解决方法:班次时长的ID为必填项。

  • DEPENDENT_FIELD_MISSINGHTTP 400

    您尚未指定一个或多个依赖字段。
    解决方法:

    • 对于自定义班次时段,days 为必填项。
    • 当 same_as_everyday=true 时,daily_timing 为必填项。
    • 当 same_as_everyday=false 时,custom_timing 为必填项。

    请参考示例输入,了解这些键的具体结构。

  • NOT_ALLOWEDHTTP 400

    您正在尝试在为您的组织设置营业时间之前设置轮班时间。
    解决方法: 只有添加了营业时间后,才能添加轮班时间。

  • NOT_ALLOWEDHTTP 400

    您尝试设置的休息时间超过了两小时。
    解决方法:每个班次的休息时间最长为两小时。

  • INVALID_URL_PATTERNHTTP 404

    请检查所尝试访问的URL是否正确
    解决方法:指定的请求URL不正确。请指定一个有效的请求URL。请参考上方的请求URL部分。

  • OAUTH_SCOPE_MISMATCHHTTP 401

    您没有访问此 API 的相应权限范围。
    解决方法:使用 ZohoCRM.settings.business_hours.ALL 或 ZohoCRM.settings.business_hours.UPDATE 范围创建新的令牌。

示例回复

Copied{
    "shift_hours": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "3652397000011137072"
            },
            "message": "Shift Hours updated successfully.",
            "status": "success"
        }
    ]
}