Zoho crm Logo

更新预约偏好

目的

要更新您组织中的预约偏好设置。

端点

  • PUT /settings/appointment_preferences

请求详情

请求 URL

{api-domain}/crm/{version}/settings/appointment_preferences

标题

授权:Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

范围

scope=ZohoCRM.设置.模块.{operation_type}

可能的操作类型

全部 - 完全访问预约偏好数据
Update - Update预约偏好

示例请求

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/appointment_preferences"
-X PUT
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

请求 JSON 键

  • allow_booking_outside_service_availability布尔值,可选

    表示是否可以在服务可用时间之外创建预约。
    可能的取值:
    true:可以在服务可用时间之外创建预约。
    false:无法在服务可用时间之外创建预约。

  • allow_booking_outside_businesshours布尔值,可选

    表示是否允许在营业时间之外创建预约。只有在 allow_booking_outside_service_availability:true 时,才能配置此偏好。
    可能的取值:
    true:可以在营业时间之外创建预约。
    false:不能在营业时间之外创建预约。

  • when_duration_exceeds字符串,可选

    表示在服务时长结束后,由谁将预约标记为“已完成”。
    可能的取值:
    ask_appointment_provider_to_complete - 用户需要手动将预约标记为“已完成”。
    mark_as_complete - 预约会自动被标记为“已完成”。

  • show_job_sheet布尔值,可选

    表示在将预约标记为“已完成”时是否必须填写作业单。只有当 when_duration_exceeds: ask_appointment_provider_to_complete 时,您才能强制填写作业单。
    可选值:
    true:完成预约时必须填写作业单。
    false:完成预约时不需要强制填写作业单。

  • when_appointment_completed字符串,可选

    表示在预约完成时是否需要创建交易。
    可能的取值:
    create_deal - 当任何预约被标记为“已完成”时,创建交易。
    do_not_create_deal - 当任何预约被标记为“已完成”时,不创建交易。

  • deal_record_configurationJSON 对象,创建交易时必填

    包含用于“从预约中创建交易”模块中记录配置的字段映射和布局详细信息。当when_appointment_completed:create_deal时,此键为必填项。

    • layout(JSON 对象,必填) - 包含您想要映射预约字段的交易布局ID和布局名称。您可以从 布局元数据 API 获取这些详细信息。
    • 字段映射(JSON 数组,必填) - Contain the fields from Deals module which have to be mapped with Appointments and Services module fields to create deals automatically when an application is completed. This field mapping is bounded to the specified layout and you have to create a new field mapping for different layouts. 交易_Name,Account_Name,关闭日期,销售管道和阶段 fields are mandatory for field_mappings.
      • field(JSON 对象,必填) - 表示您希望使用来自“预约”模块的数据填写的“交易”模块中字段的API名称和ID。请参考 字段元数据 API 以获取模块中可用字段的列表。请确保不要输入无效的字段API名称或ID,否则会报错。
      • type(字符串,必填) - Deals 字段可以与 Appointments 字段合并,也可以设为静态字段。
        可能的取值:
        merge_field - Appointments 字段的值会映射到 Deals 字段的值。
        static - 此类型下填写的值将作为所有交易的标准值。
      • value(字符串,必填) - 表示交易字段的值。每种指定的类型对应的值都不同。
        merge_field 类型的 value:该值的数据类型为字符串。要合并任何模块中的字段,应按照以下格式指定:${module_api_Name.field_api_Name}。
        示例:${Appointments__s.Appointment_Name}
        static 类型的 value:该值的数据类型为JSON对象。它包含实体的Name和ID。
        当你需要提供引用其他模块的静态值时,请对相应模块进行一次GET API调用,并提供相关记录的ID和Name。你也可以直接提供用字符串括起来的标准文本值。

注意

  • 系统定义的字段映射如下所示。此映射不可更改,并且为只读字段。
    • 金额 - 商机模块中的金额字段与服务模块中的价格字段进行映射。
    • 关闭日期 - 商机模块中的关闭日期字段与预约模块中的预约开始时间字段进行映射。
  • "when_duration_exceeds":"ask_appointment_provider_to_complete" 是任何组织的默认预约偏好设置。
  • 部分字段已设置默认字段映射,具体如下。
    • 所有者 - 组织的超级Admin。
    • 货币 - 你组织配置的本位币。
    • 销售流程 - 指定布局的标准流程。
    • 商机_Name - 预约模块中的预约_Name字段。
  • 只有在从选项列表中选择超级Admin或Users时,“所有者”字段的类型才为静态。对于'成员'、'预约创建者'和'预约修改者'选项,类型应为合并字段。

示例输入

Copied{
    "appointment_preferences": {
        "allow_booking_outside_businesshours": false,
        "deal_record_configuration": {
            "layout": {
                "name": "Standard",
                "id": "5545974000000091023"
            },
            "field_mappings": [
                {
                    "field": {
                        "api_name": "Owner",
                        "id": "5545974000000002555"
                    },
                    "type": "static",
                    "value": {
                        "name": "James Smith",
                        "id": "5545974000001170042"
                    }
                },
                {
                    "field": {
                        "api_name": "Deal_Name",
                        "id": "5545974000000002559"
                    },
                    "type": "merge_field",
                    "value": "${!Appointments__s.Appointment_Name}"
                },
                {
                    "field": {
                        "api_name": "Account_Name",
                        "id": "5545974000000002563"
                    },
                    "type": "static",
                    "value": {
                        "name": "Printing Dimensions",
                        "id": "5545974000000407008"
                    }
                },
                {
                    "field": {
                        "api_name": "Stage",
                        "id": "5545974000000002565"
                    },
                    "type": "static",
                    "value": "Closed Won"
                },
                {
                    "field": {
                        "api_name": "currency",
                        "id": "5545974000000050013"
                    },
                    "type": "static",
                    "value": {
                        "name": "SAR",
                        "id": "5545974000000407008"
                    }
                },
                {
                    "field": {
                        "api_name": "Pipeline",
                        "id": "5545974000000193001"
                    },
                    "type": "static",
                    "value": {
                        "name": "Service Pipeline",
                        "id": "5545974000000407008"
                    }
                }
            ]
        },
        "show_job_sheet": true,
        "when_duration_exceeds": "ask_appointment_provider_to_complete",
        "when_appointment_completed": "create_deal",
        "allow_booking_outside_service_availability": false
    }
}

可能的错误

INVALID_DATAHTTP 400

您输入的字段 key 的字段 ID 无效。
解决方案:请调用 获取字段元数据 API,并提供有效的字段 ID。

  • API_NOT_SUPPORTEDHTTP 400

    该 API 在此版本中不受支持。
    解决方案:此 API 仅从第 3 版开始支持。

  • DEPENDENT_FIELD_MISSINGHTTP 400

    您已指定布局 ID,但未指定字段映射。
    解决方案:每当您更改交易模块的布局 ID 时,都需要配置新的字段映射。

  • DEPENDENT_FIELD_MISSINGHTTP 400

    您为 deal_record_configuration 键提供了空值。
    解决方案:如果 when_appointment_completed 键的值为 create_deal,则 deal_record_configuration 键不能为空。

  • DEPENDENT_MISMATCHHTTP 400

    您已尝试启用 allow_booking_outside_businesshours 键,但未启用 allow_booking_outside_service_availability 键。
    解决方法:必须先将 "allow_booking_outside_service_availability" 设置为 true,才能启用 allow_booking_outside_businesshours 键。

  • DEPENDENT_MISMATCHHTTP 400

    您正在尝试强制要求填写工作单,但未指定 ask_appointment_provider_to_complete 的值。
    解决方案: 要在预约偏好中强制要求填写工作单,when_duration_exceeds 键必须设置 ask_appointment_provider_to_complete 的值。

  • INVALID_DATAHTTP 400

    您在 fields_mappings 键中映射了两个不同的数据类型字段。
    解决方法: 在交易记录配置的 field_mappings 中,只能映射相同数据类型的字段。

  • INVALID_DATAHTTP 400

    您为 when_appointment_completed 键或 when_duration_exceeds 键指定了无效的值。
    解决方法:when_appointment_completed 键的可选值:'create_deal' 和 'do_not_create_deal'。
    when_duration_exceeds 键的可选值:'ask_appointment_provider_to_complete' 和 'mark_as_complete'。

  • INVALID_DATAHTTP 400

    您为字段映射中的 type 键指定了无效的值。
    解决方案:唯一可用的值是 'merge_field' 和 'static'。

  • INVALID_DATAHTTP 400

    您已强制要求作业单,但未在服务Preferences中启用作业单。
    解决方案: 如果未为服务启用作业单,则无法强制要求作业单。请调用 Update服务Preferences API 接口,以为服务启用作业单。

  • INVALID_DATAHTTP 400

    您提供了无效的布局 ID。
    解决方法:请调用 获取布局 API,并提供有效的布局 ID。

  • INVALID_DATAHTTP 400

    您在 field_mappings 中为 static 类型指定了 Date、DateTime 或 Unique 字段值。
    解决方案: static 类型不支持 Date、DateTime 和 Unique 字段。请使用 merge_field 类型。

  • INVALID_MAPPINGHTTP 400

    您指定的值长度超过了 Deals 字段的最大长度。
    解决方法: 在静态类型中,值的长度应小于或等于 Deals 字段的最大长度。

  • INVALID_REQUEST_METHODHTTP 400

    您提供了无效的 HTTP 请求方法类型。
    解决方法: 仅在请求输入中使用 PUT 方法访问此 API。

  • MAPPING_MISMATCHHTTP 400

    您指定了一个在布局中不存在的不同流程。
    解决方案:请使用请求正文中提到的正确布局 ID 发起 GET Pipelines API 调用。

  • MAPPING_MISMATCHHTTP 400

    您指定了一个不在给定流程中的阶段。
    解决方案: 进行一次 GET Pipelines API 调用,并提供一个有效的阶段。

  • REQUIRED_DATA_NOT_FOUNDHTTP 400

    您未能在 deal_record_configuration 键中映射必填字段。
    解决方案:在 deal_record_configuration 键的字段映射中,Name、AccountName、关闭日期、销售渠道和阶段字段都是必填项。

  • INVALID_TOKENHTTP 401

    您使用了无效的 oauth 令牌。
    解决方案: 您使用的访问令牌已过期。请刷新您的令牌并重试。

  • OAUTH_SCOPE_MISMATCHHTTP 401

    您使用了错误的 OAuth 范围创建授权令牌。
    解决方法:请使用 ZohoCRM.settings.modules.UPDATE 或 ZohoCRM.settings.modules.ALL 范围来创建新的有效授权令牌。

  • NO_PERMISSIONHTTP 403

    您没有权限更新预约首选项。
    解决方法: 请联系您的系统管理员。

  • NOT_ALLOWEDHTTP 403

    您尝试将 Closing_Date 或 Amount 键映射到其他字段。
    解决方案:Closing_Date 和 Amount 键分别与 Appointment_Start_Time 和 Price 字段有系统定义的字段映射。您不能将它们重新映射到其他字段。

  • NOT_ALLOWEDHTTP 403

    您尝试在流程中指定一个新的阶段。
    解决方法: 只有已赢单的阶段才允许与阶段字段进行映射。

  • NOT_ALLOWEDHTTP 403

    您试图从 deal_record_configuration 键中移除 Amount 或 Closing_Date 字段。
    解决方案: Amount 和 Closing_Date 字段的映射无法被移除。

  • INTERNAL_ERRORHTTP 500

    服务器内部错误
    解决方案:服务器发生了意外且未处理的异常。请联系我们的支持团队。

示例响应

Copied{
    "appointment_preferences": {
        "code": "SUCCESS",
        "details": {},
        "message": "Appointments preferences updated successfully",
        "status": "success"
    }
}