Публичное 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.

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

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

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

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

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

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

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

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