Центр поддержкиИнтеграции

Для: Администраторы

Читайте и обновляйте сведения о деле с помощью ключа центрального узла.

Прочитайте подробности обращения и информацию о команде, а также измените параметры, которые администратор разрешает изменять роли виртуального помощника, например, этап или пользовательское поле.

В этой статье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_status0 Чтобы закрыть дело, необходимо использовать специальный ключ. Без этого ключа дело невозможно закрыть.Нет.Не изменилось.
case_stageID этапа от 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Почему
400SchemaFieldsExceptionЭто некорректное поле. Например, пустой элемент типа title, отправленный пустым значением необходимое поле или поле, которого у вашего хаба нет. Название этого поля – errors.
403CaseFieldNotWritableExceptionПоле, которое вы отправили, не является ключом. Название этого поля – reason.
403CaseClosedExceptionДело закрыто.
403HostModuleDisabledExceptionДетали этого дела или информация о команде, работающей над ним, скрыты в этом разделе. Или же эта информация отключена для вашего хаба.
403CaseModulePermissionDeniedExceptionРоль ботов может заключаться в том, что они не будут читать детали дела или информацию о команде.
404CaseNotFoundExceptionЭтот случай не существует. Он может принадлежать другому хабу или же его удаляют.

Что касается текста ошибок и остальных кодов, см. раздел Управление ошибками API и статусными кодами.

Статьи по теме

Разберитесь, что может делать API.Узнайте, к чему могут иметь доступ ключ управления и ключ концентратора, почему каждый ключ действует как виртуальный помощник и где находится полный технический паспорт.ИнтеграцииНайдите дела с ключом от центрального узла.Составьте список дел в вашем центре, открытых или закрытых, выполните поиск по идентификатору тега или названию, а также найдите идентификатор дела в своем собственном программном обеспечении.ИнтеграцииИзмените возможности данной роли.Изменяйте права доступа роли, поля дела, которые она может читать или изменять, а также ограничения на загрузку данных, включая встроенные роли.Безопасность и учетные записи · 5 minОбработка ошибок и кодов состояния API.Прочитайте текст ошибки, что означают коды 400, 401, 403, 404, 500 и 503, и почему элемент, который ваш ключ не видит, выдает ошибку 404.Интеграции