Перейти на сайт

Public API и вебхуки

Настройка Public API и вебхуков CheckOffice для интеграции с внешними системами

Public API используется для интеграции CheckOffice с внешними системами через REST API.

Вебхуки позволяют отправлять POST-запросы при событиях в CheckOffice: создании проверки, изменении статуса проверки, создании задачи, изменении статуса задачи, удалении проверки в архив и удалении задачи в архив.

Настройки Public API и вебхуков доступны в разделе:

Боковое меню слева > «Администрирование» > «Публичное API»

Ограничения использования

Функционал доступен всем клиентам в течение пробного периода, а также в коммерческих тарифах.

Лимит количества запросов к серверу — 500 запросов в час по умолчанию.

Для выполнения запросов понадобится ключ API.

Не передавайте ключ API посторонним лицам, т. к. они смогут получить доступ к вашим данным.

Возможности API

С помощью Public API можно выполнять действия с данными CheckOffice, например:

  • получить данные проверки по ID;
  • создать проверку;
  • получить задачу по ID;
  • создать задачу;
  • получить информацию об объекте проверки по ID;
  • получить информацию о пользователе по ID;
  • создать шаблон чек-листа.

Актуальный список доступных методов смотрите в документации Swagger:

https://название-вашей-площадки.checkoffice.ru/documentation/api/public

Как использовать API

Перейдите в раздел:

Боковое меню слева > «Администрирование» > «Публичное API»

Скопируйте ключ API.

Откройте документацию Swagger:

https://название-вашей-площадки.checkoffice.ru/documentation/api/public

Для выполнения запросов в Swagger введите ваш ключ API.

Например, для получения данных проверки потребуется указать ID проверки. Его можно посмотреть в CheckOffice при открытии проверки.

ID задачи можно посмотреть при открытии задачи в CheckOffice.

Ниже приведен пример выполнения запроса через Swagger и пример curl-запроса с использованием API-Key.

В параметре inspectionId указывается ID проверки.

В заголовке API-Key необходимо передать ваш ключ API.

Для выполнения запроса из внешней системы передайте ключ API в заголовке:

API-Key: [Ваш-ключ-API]

Возможности вебхуков

Вебхуки позволяют отправлять запросы во внешнюю систему при наступлении выбранных событий в CheckOffice.

Доступные события вебхуков:

  • создание проверки;
  • изменение статуса проверки;
  • создание задачи;
  • изменение статуса задачи;
  • удаление проверки в архив;
  • удаление задачи в архив.

Запросы отправляются методом POST.

Как настроить вебхук

Перейдите в раздел:

Боковое меню слева > «Администрирование» > «Публичное API»

Добавьте вебхук.

Укажите:

  • URL, на который будут отправляться запросы;
  • необходимые заголовки;
  • события, по которым должен срабатывать вебхук.

Можно создать несколько вебхуков под разные задачи.

Примечание: если в URL есть пробелы, их нужно заменить на +.

Какие данные отправляются в вебхуке

При наступлении выбранного события CheckOffice отправляет POST-запрос на указанный адрес.

В теле запроса передаются два поля:

  • data — данные о задаче или проверке в зависимости от события;
  • event — тип события.

Примеры типов событий:

  • inspection.create — создание проверки;
  • inspection.changeStatus — изменение статуса проверки;
  • task.create — создание задачи;
  • task.changeStatus — изменение статуса задачи.

Схему данных поля data можно посмотреть в Swagger:

https://название-вашей-площадки.checkoffice.ru/documentation/api/public

В поле data отправляются объекты Task и Inspection.

Важное ограничение вебхуков

CheckOffice не обрабатывает ответы на запрос вебхука.

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

Заголовки для вебхуков

При создании вебхуков можно добавить заголовки.

Заголовок передается в запросе вебхука.

Что именно указывать в заголовках, зависит от принимающей стороны.

Заголовки могут использоваться:

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

Например, принимающая сторона может потребовать заголовок KEY с определенным значением.

Если необходимости передавать заголовки нет — их не нужно заполнять.

Политика версионности API

Публичное API имеет версию.

Актуальную версию можно посмотреть в разделе:

Боковое меню слева > «Администрирование» > «Публичное API»


При развитии CheckOffice новые данные добавляются в актуальную версию API.

Если изменения несовместимы с текущей версией, создается новая версия.

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

Если в настройках вебхука указана удаляемая версия API, вебхук будет автоматически перенастроен на самую свежую версию.

Рекомендуем периодически обновлять интеграции до актуальной версии API.

FAQ 

API и вебхуки: в чем разница

Public API используется, когда внешняя система должна самостоятельно получать, создавать или изменять данные в CheckOffice через API-запросы.

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

Иными словами:

— API > внешняя система обращается к CheckOffice
— Вебхук > CheckOffice отправляет событие во внешнюю систему

Если вебхук не приходит

Проверьте:

— правильно ли указан URL вебхука;
— доступен ли сервер принимающей системы;
— выбраны ли необходимые события;
— не блокируются ли запросы firewall или прокси;
— корректно ли принимаются POST-запросы на стороне внешней системы.

Безопасность

При подозрении на компрометацию API-Key рекомендуем:
— сгенерировать новый ключ;
— обновить настройки интеграции;
— отключить старый API-Key.

Инструкция: https://help.checkoffice.ru/article/28572

👆 На этом пока всё