Для: Администраторы
Читайте и обновляйте сведения о деле с помощью ключа центрального узла.
Прочитайте подробности обращения и информацию о команде, а также измените параметры, которые администратор разрешает изменять роли виртуального помощника, например, этап или пользовательское поле.
В этой статье8 разделов
Прежде чем начать
На этой странице рассматривается процесс чтения и изменения параметров одного случая с использованием ключа hub. Пути для доступа к этим параметрам указаны под https://prd-api-app.caseactive.com/v1/<hub id>/<case id>.
Звонки
| Вызов | Что это делает |
|---|---|
GET /case | Читает подробности дела. |
PUT /case | Изменяются детали, связанные с ключом. Возможно, ключ может измениться. |
GET /whoami | В документе указано, какие детали могут изменяться в данном случае, а также какие разделы документа имеют значение. |
GET /team | Список людей, связанных с данным делом. |
GET /placeholders | Читает значения, которые заполняются в кодах ваших шаблонов в данном случае. |
Какие данные может прочитать и изменить хаб-ключ, зависит от функций самого хаба. Виртуальный помощникВиртуальный помощник Автоматизированный член команды, который публикует приветственные сообщения, проводит проверки и организует публикации для компании; его публикации отмечены значком виртуального помощника., боты. По умолчанию программа считывает стандартные данные о случае. Никаких изменений в этих данных невозможно внести до тех пор, пока администратор этого не разрешит.
Позволить ключу изменить детали
В разделе Настройки › Роли можно изменить параметры роли ботов. В разделе Дело необходимо отметить опцию Обновление всех полей случая, указанных в роли. Также можно указать, какие именно поля будут обновляться: заглавие, Описание, Дата открытия, Статус, Этап или пользовательские поля. Чтобы бот мог читать пользовательские поля, необходимо отметить этот параметр в разделе Чтение всех полей случая, указанных в роли. Подробнее о изменении возможностей роли смотрите в разделе Изменение возможностей роли.
GET /whoami Ответы на ключевые вопросы в данном случае связаны с ролью ключа. case_read_fields и case_write_fields, Детали могут отличаться в зависимости от контекста. case_write_fields Этот параметр остается неиспользованным, поскольку он может не изменяться. В разделе настроек указано, что этот параметр отсутствует. meta_data.<field key>. Это также ответ на вопрос. case_modules, В данном случае указаны все разделы, которые имеются в документе; также не указаны никакие скрытые разделы. Запрос на доступ к отсутствующим разделам отклоняется.
Чтение кейса
curl https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/case \
-H "Authorization: Bearer YOUR_API_KEY"
{
"data": {
"case_id": "cc-1a2b3c4d5e6f70",
"host_id": "ca-7e6d5c4b3a2f10",
"ref_id": "rear-end-2026",
"title": "Jane Sample auto accident",
"description": "Rear-end collision on Route 9. Waiting on the insurer's estimate.",
"case_type": "general",
"case_status": 1,
"case_stage": "stage::20260927120000_8c1f0e2d3b4a59",
"date_opened": "2026-03-05",
"meta_data": {
"schema": [{"schema": {"type": "object", "properties": {"policy_number": {"type": "string", "title": "Policy number"}}}}],
"content": [{"policy_number": "PN-5521"}]
},
"selfLink": "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/case"
}
}
- По умолчанию ключ считывается как таковой.
case_id,ref_id(Это…) ID теговИдентификатор метки Постоянная метка, которую вы присваиваете делу, например, rear-end-2026, также отображается в качестве идентификатора ссылки и используется при импорте.),case_status,date_opened,title,description,case_typeиcase_stage. В этом случае не упоминается какой-либо деталь. case_stage– это идентификатор этапаЭтап Этап, через который проходит дело, например, прием заявки или отправка запроса, который фирма обозначает и описывает и который отображается на странице дела.;GET /v1/<hub id>/stages– список их имен.meta_data.contentхранит значения пользовательских полей. Один объект соответствует одному полю на странице с данными по этому полю. Однако доступны только те поля, которые могут быть прочитаны по ключу. По умолчанию это поле не содержит никаких значений; поэтому первая страница будет пустой. В примере администратор разрешил этому полю считывать номер политики.meta_data.schemaописывает поля, отображаемые на каждой странице.- В таблице
hidden_modulesперечислены разделы, которые в данном случае скрыты. Если таких разделов имеется, то они указаны в этом списке.
Изменение дела
PUT /case принимает любые из этих полей в формате JSON и изменяет только те из них, которые вы указали.
| Поле | Что это делает | Необходимый | По умолчанию |
|---|---|---|---|
title | Название дела, которое показано всем присутствующим. | Нет. | Не изменилось. |
description | Описание для сотрудников: отправьте "", чтобы удалить его. | Нет. | Не изменилось. |
date_opened | Дата начала рассмотрения дела, например: 2026-03-15 | Нет. | Не изменилось. |
case_status | 0 Чтобы закрыть дело, необходимо использовать специальный ключ. Без этого ключа дело невозможно закрыть. | Нет. | Не изменилось. |
case_stage | ID этапа от GET /v1/<hub id>/stages. Отправьте "", чтобы убрать этот этап из списка доступных этапов. | Нет. | Не изменилось. |
meta_data | Значения пользовательских полей: список, состоящий из одного объекта на каждой странице с полем. В каждом объекте содержатся значения соответствующих полей. Можно изменять только первую страницу, а также только те поля, которые вы указываете. Для удаления значений поля используйте "" или null. Необходимые поля не могут быть удалены. | Нет. | Не изменилось. |
curl -X PUT https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/case \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"case_stage": "stage::20260927120000_8c1f0e2d3b4a59", "meta_data": [{"policy_number": "PN-5521"}]}'
Это ответ. 200 Если какое-либо поле, которое вы отправляете, не соответствует требованиям, то ключ может измениться, а его значение будет отличаться от значения этого поля. В таком случае весь запрос будет отклонен с кодом 403, и ничего не изменится. reason Название полей – это произвольное название. meta_data.<field key>. Поле, содержащее значение, которое уже имеется в данном случае, не требует каких-либо изменений. Следовательно, это поле не отклоняется, а также не записывается. Кроме того, звонок, не вносящий никаких изменений, остается без ответа. 204.
- Перемещение открытого дела на другую стадию добавляет соответствующий этап в истории проекта. Если у вас есть виртуальный помощник, то это также будет отображаться в его истории. См. Добавляйте сообщения автоматически, когда дело достигает определенной стадии.. Ничего другого не сообщается или не отправляется: закрытие дела или изменение его деталей никому не сообщается.
- Как только дело закрывается, любые изменения, произведенные с помощью хаб-ключа, отклоняются. Возможность возобновления работы дела также исключается. Для возобновления работы дела необходимо использовать административный панель или специальный ключ для управления дэтом. См. раздел Закрытие или возобновление дела.
- ID тегов и тип случая не могут быть изменены здесь. Только специальный ключ может изменить этот параметр.
Команда
В таблице GET /team перечислены все участники данного дела – включая Виртуального помощника и людей с ограниченными возможностями. В одном деле может быть не более 20 человек. Такое количество было подсчитано самой Виртуальной помощницей.
{
"data": {
"items": [
{
"case_id": "cc-1a2b3c4d5e6f70",
"user_id": "cu-4f1c2a9e8b7d60",
"case_role_id": "role::clients",
"case_designation": "primary",
"case_notify": 1,
"host_user_status": 1,
"given_name": "Jane",
"family_name": "Sample",
"locale": "en",
"zoneinfo": "America/New_York"
}
],
"currentItemCount": 1,
"selfLink": "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/team"
}
}
case_role_idобозначает роль человека в данном случае, аcase_designation– его названиеОбозначение Обозначение должности, занимаемой сотрудником по делу, например, ведущий юрист, помощник юриста или опекун., напримерprimary.host_user_statusравно0для тех людей, которые имеют инвалидность в вашем центре.- Имена каждого человека, язык…
locale) И часовой пояс.zoneinfo) Возвращение происходит по умолчанию. Адреса электронной почты и номера телефонов никогда не возвращаются. - Ключ “hub” не позволяет добавлять или удалять людей из списка участников. Все звонки, совершаемые с использованием этого ключа, отвечают на номерах 403
HostAddCaseUserNotEnabledExceptionиHostRemoveCaseUserNotEnabledException. Для управления участниками используйте соответствующий ключ; см. раздел Добавление и удаление участников с помощью управляющего ключа.
Значения шаблона
GET /placeholders Ответы, ниже. placeholders, Значение, которое каждый код в ваших шаблонах принимает в данном случае, например: clients.primary.full_name, clients.primary.email, case_ref_id и company.phone. Код для обозначения лица, не имеющего отношения к данному делу, не указан. Если раздел „Команда“ отключен или скрыт на данном деле, то все коды команд не указываются; остальные коды все равно будут использоваться. См. Заполняйте поля формы с уже имеющимися данными о случаях..
Если звонок отклонен
| Статус | message | Почему |
|---|---|---|
| 400 | SchemaFieldsException | Это некорректное поле. Например, пустой элемент типа title, отправленный пустым значением необходимое поле или поле, которого у вашего хаба нет. Название этого поля – errors. |
| 403 | CaseFieldNotWritableException | Поле, которое вы отправили, не является ключом. Название этого поля – reason. |
| 403 | CaseClosedException | Дело закрыто. |
| 403 | HostModuleDisabledException | Детали этого дела или информация о команде, работающей над ним, скрыты в этом разделе. Или же эта информация отключена для вашего хаба. |
| 403 | CaseModulePermissionDeniedException | Роль ботов может заключаться в том, что они не будут читать детали дела или информацию о команде. |
| 404 | CaseNotFoundException | Этот случай не существует. Он может принадлежать другому хабу или же его удаляют. |
Что касается текста ошибок и остальных кодов, см. раздел Управление ошибками API и статусными кодами.