预约APIs
预约模块包含客户详细信息,服务信息,基于客户选择和可用性的预约日期和时间。每次联系人请求您的公司提供服务时,销售代表都会预约一次。预约API允许您获取,创建,更新和删除它们。它们还允许您根据各种业务需求设置预约偏好。
获取预约
目的
获取符合您搜索条件的预约数据。
端点
- GET /Appointments__s
- GET /Appointments__s/{appointment_id}
Request 详细信息
Request URL
{api-domain}/crm/{version}/Appointments__s
标题
Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
范围
scope=ZohoCRM.modules.appointments.{operation_type}
Possible operation types
ALL - 对预约数据的完全访问
READ - 获取预约数据
参数
- fields string, mandatory when fetching all appointments data
列出所有与您在此参数中指定的字段相关的预约数据。请注意,您可以在此参数中包含最多50个字段API名称。 GET Fields API将为您提供预约模块中现有的字段API名称。
可能的值:多个字段API名称,用逗号分隔。例如:Last_Name,Email。 - cvid long, optional
获取在此键中指定的自定义视图中存在的预约列表。您可以从GET Custom Views API获取自定义视图ID。您不能将此参数与"sort_by"参数一起使用。
可能的值:{custom_view_id}。 - page_token string,如果要通过分页获取超过2000个预约,则必须使用
您可以使用"page"参数获取最多2000个预约,无需使用"page_token"。要获取超过2000个预约,您必须在请求中包含"page_token"参数。此参数的值来自第一次GET预约调用的响应中的"next_page_token"键的值。此令牌值是用户特定的,如果您使用其他用户的令牌,系统将抛出错误。
页面令牌与参数绑定,并在24小时后过期。此外,您不能将此参数与"page"参数一起使用。 - page integer,optional
从相应的页面获取预约列表。默认值为1。请注意,您不能将此参数与"page_token"参数一起使用。
可能的值:仅限正整数值。 - per_page integer, optional
获取每页可用的预约列表。默认值和可能的最大值是200。
可能的值:仅正整数值。 - sort_order string,optional
对可用的预约列表进行升序或降序排序。
可能的值:asc - 升序,desc - 降序。默认值为'desc'。 - sort_by string,optional
根据字段id,Created_Time和Modified_Time对预约进行排序。请注意,您不能将此参数与"cvid"参数一起使用。默认字段是'id'。
注意
- sort_order 适用于给定的 sort_by 字段。
- 如果你的需求是获取少于2000个预约,使用"page"和"per_page"参数(page=1到10,per_page=200)。
- 如果你想要分页获取超过2000个预约,使用你在第一次响应中收到的"page_token"参数。你将需要传递从响应中收到的页面令牌,参数 page=10 来获取从2001到2200的记录。如果还有更多的预约,API响应将有"next_page_token"和"previous_page_token"以便于分页。
使用连续请求中的页面令牌,你可以导航并获取多达 100,000 个预约。 - 在上述两种情况下,每个请求的最大预约数量只能是200。
- 在检索多个预约时,将不会检索子表单数据。你必须在请求URL中指定单个预约ID以获取子表单中的数据。
- 只有在通过API限制数据访问选项在合规性设置中被禁用时,才能检索到带有敏感健康数据的字段的值。如果该选项被启用,值将为null。请参阅HIPAA合规性以获取更多详情。
样本请求
可能的错误
- AMBIGUITY_DURING_PROCESSINGHTTP 400
您不能同时使用cvid和sort_by,以及page和page_token
解决方案:在请求中使用" cvid "或" sort_by "参数。同样,使用" page "或" page_token "参数。 - DISCRETE_PAGINATION_LIMIT_EXCEEDEDHTTP 400
您只能在不使用page_token参数的情况下获取前2000条记录。
解决方案:如果您想获取超过2000条的记录,您必须使用"page_token"参数。 - EXPIRED_VALUEHTTP 400
您的页面令牌已过期。
解决方案: page_token仅在生成后的24小时内有效。 - INVALID_DATAHTTP 400
您使用了无效的 page_token 或由其他用户生成的 page_token。
解决方案: page_token 是特定于用户的。请使用您的 API 调用生成的 page_token。 - INVALID_MODULEHTTP 400
您在请求URL中给出了无效的模块名称。
解决方案:您只能在请求URL中使用Appointments__s。 - INVALID_REQUEST_METHODHTTP 400
您给出了无效的HTTP请求方法类型。
解决方案:在请求URL中只使用GET方法来访问此API。 - LIMIT_EXCEEDEDHTTP 400
您超过了字段限制。
解决方案:在"fields"参数中,您只能包含最多50个字段API名称。 - TOKEN_BOUND_DATA_MISMATCHHTTP 400
您要么指定了无效的page_token,要么添加、修改或删除了输入参数。
解决方案:page_token与请求中使用的参数绑定。不要更改参数,并使用响应中的页面令牌。 - PAGINATION_LIMIT_EXCEEDEDHTTP 400
使用page_token参数,您只能获取最多100,000条记录。
解决方案:您可以使用GET appointments API响应中的page_token参数获取最多100,000条记录。 - REQUIRED_PARAM_MISSINGHTTP 400
您未在参数中指定字段API名称或页面令牌。
解决方案:当您想获取所有预约的数据时,必须指定字段API名称。如果预约超过2000个,必须提供页面令牌。 - INVALID_TOKENHTTP 401
您使用了无效的oauth令牌。
解决方案:您使用的访问令牌已过期。请刷新您的令牌并重试。 - OAUTH_SCOPE_MISMATCHHTTP 401
您使用了错误的oauth范围创建了授权令牌。
解决方案: 使用ZohoCRM.modules.appointments.READ或ZohoCRM.modules.appointments.ALL范围来创建一个新的有效授权令牌。 - NO_PERMISSIONHTTP 403
您没有权限获取任何预约的数据。
解决方案:联系您的系统管理员。 - INVALID_URL_PATTERNHTTP 404
检查您是否正在尝试访问正确的URL。
解决方案:您给出了一个无效的请求URL。请参考上述端点部分。 - INTERNAL_ERRORHTTP 500
内部服务器错误
解决方案:服务器中出现意外和未处理的异常。请联系我们的支持团队。