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

Технические возможности интеграции сервиса CheckOffice с другими системами для бизнеса

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

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

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

Тариф

Пробный период

BASE

EXPERT

PREMUIM

Индивидуальный

API доступно

да

нет

нет

да

опционально

Лимит количества запросов

500 в час

500 в час

настраивается


Возможности 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.


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