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

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

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

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

В этой статье10 разделов

Прежде чем начать

На этой странице рассматривается вопрос о том, каким образом можно управлять ключами. Пути находятся под https://prd-api-manage.caseactive.com/v1/<hub id>.

Звонки

ВызовЧто это делает
GET /casesПеречисление случаев, связанных с вашим хабом; самые последние случаи первыми.
POST /casesСоздается определенная ситуация/ситуации.
GET /cases/<case_id>Читает один случай.
PUT /cases/<case_id>Изменение регистра букв
DELETE /cases/<case_id>Удаляется случай навсегда.
GET /stagesПеречислите этапы вашего хаба, чтобы определить их идентификационные номера.
GET /schemas?schema_type=casesЧитает поля, связанные с конкретными случаями вашего хаба.

Список дел

ПараметрЧто это делаетНеобходимыйПо умолчанию
type1 используется для открытых случаев, а 0 – для закрытых случаев. Несмотря на название, этот параметр фильтрует по статусу случая, а не по типу случая.Нет.Оба
limitСколько случаев может содержать одна страница – до 1000.Нет.20
start_keystartKey из предыдущей страницыНет.Первая страница
curl "https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases?type=1" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "data": {
    "items": [
      {
        "case_id": "cc-1a2b3c4d5e6f70",
        "host_id": "ca-7e6d5c4b3a2f10",
        "ref_id": "rear-end-2026",
        "title": "Jane Sample auto accident",
        "case_type": "general",
        "case_status": 1,
        "case_stage": "stage::20260927120000_8c1f0e2d3b4a59",
        "users": {
          "cu-7e6d5c4b3a2f10": "role::bots",
          "cu-4f1c2a9e8b7d60": "role::clients",
          "cu-9d8c7b6a5f4e30": "role::staff"
        },
        "created_on": "2026-10-02T14:05:09+00:00"
      }
    ],
    "currentItemCount": 1,
    "selfLink": "https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases?type=1"
  }
}
  • users Сопоставляет каждого человека в данной ситуации с его рольюРоль Набор разрешений, определяющий, что может видеть и делать тот или иной пользователь в рамках дела, например, сотрудники или клиенты.. В этом списке также указан Виртуальный помощникВиртуальный помощник Автоматизированный член команды, который публикует приветственные сообщения, проводит проверки и организует публикации для компании; его публикации отмечены значком виртуального помощника. вашего хаба, который обозначен как role::bots.
  • Хотя количество таких случаев ещё не превышает определенного предела, на этой странице также имеется значение nextLink – полная адресация следующей страницы. Также имеется значение startKey. Нужно вызвать значение nextLink или отправить значение startKey вместе с значением start_key, пока не появится страница, на которой эти значения отсутствуют.
  • Случаи, которые удалены, не учитываются в результатах поиска. Чтобы найти случай по его ID теговИдентификатор метки Постоянная метка, которую вы присваиваете делу, например, rear-end-2026, также отображается в качестве идентификатора ссылки и используется при импорте., смотрите раздел Поиск случаев и пользователей с помощью управляющего ключа.

Поля дела

POST /cases и PUT /cases/<case_id> рассматривают эти поля как данные в формате JSON. Поля, не указанные в списке, игнорируются.

ПолеЧто это делаетНеобходимыйПо умолчанию
ref_idID случая: буквы, цифры, знаки отрицания и символы, все это обозначается в нижнем регистре. Ни один из случаев в вашем хабе не может иметь одинаковый ID. Этот параметр устанавливается только при создании случая; его нельзя изменять.Да, можно создать.—
titleНазвание дела, которое показано всем присутствующим.Да, можно создать.—
descriptionОписание для сотрудников. Клиенты этого не видят. При изменении значения "" это значение удаляется.Нет.Ничего.
case_typegeneral, Или один из ваших хабов. Типы случаевТип дела Категория для конкретных случаев, например, «общие», используется для того, чтобы автоматизация выполнялась в нужных случаях., Написано так: настройки › Поля. После изменения настроек тип данных самого объекта также будет принимается в качестве дополнительного типа.Нет.general
case_status1 — для открытого состояния; 0 — для закрытого состояния.Нет.1
case_stageID его этап/фазаЭтап Этап, через который проходит дело, например, прием заявки или отправка запроса, который фирма обозначает и описывает и который отображается на странице дела., из GET /stages. Произошли изменения. "" Это снимает проблему с сцены.Нет.Никакой стадии
date_openedДата начала рассмотрения дела, например: 2026-03-15Нет.Сегодня, по времени UTC.
hidden_modulesСтраницы, которые нужно скрыть в данном случае: case, convos, events, forms, signs, invoices, notes, tasks и team. Направьте значение [], чтобы снова показать все эти страницы.Нет.Ничего не скрыто.
meta_dataЕго пользовательские поля – см. ниже.Нет.Ничего.

Нельзя добавлять людей при создании нового случая. Только виртуальный помощник может быть добавлен в новый случай. Добавляйте людей с помощью символа POST /cases/permissions. Подробнее о добавлении и удалении членов случая смотрите в разделе Добавление и удаление членов случая с помощью клавиши управления.

Создание дела

curl -X POST https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ref_id": "rear-end-2026", "title": "Jane Sample auto accident", "case_type": "general", "date_opened": "2026-10-02"}'

Это ответ на вопрос 201 с использованием идентификатора нового случая.

{"data": {"case_id": "cc-1a2b3c4d5e6f70", "selfLink": "https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases"}}

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

Чтение кейса

GET /cases/<case_id> Отвечает на вопросы дела. case_id, host_id, ref_id, title, description, case_type, case_status, case_stage, date_opened, hidden_modules, meta_data, users_ct Сколько людей участвуют в этом проекте, включая виртуального помощника. created_on и updated_on. Чтобы узнать, кто участвует в этом, используйте соответствующую функцию. GET /cases/permissions?case_id=<case_id>.

Изменение дела

Функция PUT /cases/<case_id> принимает любые из полей типа “case”, но не ref_id. Она изменяет только те значения, которые вы передаете. Функция 204 не возвращает ничего в качестве результата.

  • Перемещение открытого случая в другую стадию добавляет соответствующий этап в истории проекта. Если у вашего центра управления есть такой функционал, то Виртуальный помощник будет использоваться для обработки данного этапа. Добавляйте сообщения автоматически, когда дело достигает определенной стадии.. Ничего другого не сообщается или не отправляется: закрытие дела или изменение его характера никому не сообщается.
  • meta_data заменяет все пользовательские поля, которые имеются в данном случае.
  • Закрытый случай все же можно изменить. Поэтому синхронизация может снова открыть этот случай с использованием команды "case_status": 1.

Этапы и пользовательские поля

GET /stages указывает на этапы работы вашего хаба. Эти этапы устанавливаются администратором под настройки › Этапы. Каждый этап имеет соответствующие значения: stage_id, name, description и order. Ключ может прочитать информацию о этих этапах, но не может их изменять.

GET /schemas?schema_type=cases использует пользовательские поля вашего хаба, расположенные под настройки › Поля, в виде списка страниц. На каждой странице указаны ключи полей, их названия и типы данных. Параметр meta_data представляет собой список объектов, каждый из которых содержит значения по ключу поля.

{"meta_data": [{"policy_number": "PN-5521", "insurer": "Northwind Mutual"}]}

Значение должно соответствовать типу поля, в котором оно используется; в противном случае запрос будет отклонен. необходимые проверяется только в формах управления на панели администрирования и в лобби. Поэтому поля, которые вы создаете или обновляете здесь, могут оставаться пустыми.

Удаление дела

DELETE /cases/<case_id> отвечает на вопросы 204. После этого данный случай удаляется окончательно – вместе с сообщениями, файлами, формами, электронными документами, счетами-фактурами, событиями, задачами и записями. Это действие невозможно отменить, и никто об этом не узнает. ID тегов после удаления становится свободным снова.

Если звонок отклонен

СтатусmessageПочему
400SchemaFieldsExceptionЭто поле отсутствует или является некорректным; его именует errors. Неизвестный тип случая или стадия находится в этом поле; его именует FieldValidatorFailedException.
400CaseReferenceIdExistsExceptionЕщё один случай имеет такой ID-номер; даже один из этих случаев все ещё удаляется. reason хранит данные этого случая в формате case_id.
404ItemNotFoundExceptionЭтот случай не существует. Он может принадлежать другому хабу или же его удаляют.
403ManageBillingInactiveExceptionУправляющий панель вашего хаба заблокирована после неудачного платежа.

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

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

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