Публичное API и вебхуки

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

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

Данный функционал доступен всем клиентам в течение пробного периода, на тарифе PREMIUM, а также в качестве подключаемой опции в индивидуальных тарифах.

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

• Получение данных проверки по ID

• Создание проверки

• Получение задачи по ID

• Создание задачи

• Получение информации об объекте проверки по ID

• Получение информации о пользователе по ID

• Создание шаблона чек-листа

• Другое

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

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

События вебхуков:

• Создание проверки

• Изменение статуса проверки

• Создание задачи

• Изменение статуса задачи

• Удаление проверки в архив

• Удаление задачи в архив
  ​

Использование API

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

Для выполнения запросов вам понадобится ключ, для получения событий — настройка вебхуков на необходимые события.
​
​

ВНИМАНИЕ! Не передавайте ключ API посторонним лицам, так как они смогут получить доступ к вашим данным
​

Ознакомьтесь с документацией swagger, она расположена по адресу:
​

https://ваш-домен.checkoffice.ru/documentation/api/public

Для выполнения запросов в swagger необходимо ввести ваш ключ API:
​
​

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

После выполнения запроса будет сгенерирован пример запроса для curl.
​

ID для получения задачи также можно узнать при открытии задачи в сервисе:
​

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

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

Использование вебхуков

Добавьте на странице Настройки > Публичное API вебхук, укажите URL, на который будут отправляться запросы, необходимые заголовки, и выберите события, которые вас интересуют. Вы можете создать несколько различных вебхуков под ваши потребности.
​

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

Пример: Перед вставкой URL пробелы в тексте сообщения нужно заменять на плюсы
​

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

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

• event — тип сработавшего события — создание проверки inspection.create, изменение статуса проверки inspection.changeStatus, создание задачи task.create, изменение статуса задачи task.changeStatus

Схему данных, отсылаемых в поле data, можно посмотреть в документации swagger: https://ваш-домен.checkoffice.ru/documentation/api/public, отсылаются объекты Task и Inspection.
​
​

​

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

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

При создании вебхуков доступно добавление заголовков:
​

Заголовок передается в запрос вебхука. Что именно вводить — зависит от принимающей стороны, таким образом, предусмотрен произвольный ввод. Заголовки нужны в том случае, если принимающая запрос сторона для чего-либо их требует, или в качестве дополнительной возможности для различения или аутентификации запросов. Например, принимающая сторона может потребовать наличие заголовка KEY с определенным значением и т.д. Если потребности что-либо передать в заголовках нет, их не следует заполнять.

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

Публичное API имеет версию, актуальную версию можно узнать в разделе «Администрирование» > вкладка «Публичное API».
​
​

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

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

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