Триггеры

Триггеры - это специальный механизм, позволяющий приложениям получать HTTP-уведомления от сервера ГосПлан (или webhook) по факту наступления определенных событий.

Например, Вы можете через API дать команду серверу выполнить определенный запрос при изменении состояния закупки. В случае публикации в ЕИС нового документа или изменения состояния закупки по наступлении определенного времени, сервер может уведомить Ваше приложение POST-запросом.

В зависимости от того, какие закупки планируете отслеживать, запросы выполняются на соответствующие сервер: триггеры по 44-ФЗ - https://fz44.gosplan.info, триггеры по 223-ФЗ - https://223.gosplan.info.

В настоящее время реализован только один вид событий - изменение состояния закупки. В планах - изменение состояния плана-графика закупок.

ВНИМАНИЕ. Данная функция находится в состоянии бета-тестирования. В случае не ожидаемого поведения просим сообщить в Телеграм-группу ГосПлан API

Принцип работы

Общая схема

Схема взаимодействия при использовании триггеров
  1. Ваше (клиентское) приложение выполняет POST-запрос на сервер ГосПлан API и указывает в параметрах номер закупки, состояние которой необходимо отслеживать, и URL на который необходимо выполнить запрос.

  2. В случае, если сервер ГосПлан API фиксирует изменение состояния закупки (например, при синхронизации с ЕИС или при наступлении контрольного времени), выполняется POST-запрос на URL, который был указан в п. 1. При следующем изменении состоянии закупки запрос будет выполнен повторно (на рис. - шаг 2')

  3. Для завершения отслеживания состояния закупки, клиентское приложение отправляет DELETE-запрос на удаление триггера.

Создание триггера

Перед началом использования триггеров Вам необходимо задать адрес Вашего приложения на странице приложения https://dev.gosplan.info

Страница редактирования приложения

Необходимо указать такой домен приложения, в котором будет обрабатываться запросы от API-сервера.

В зависимости от того, какие закупки планируете отслеживать, запросы выполняются на соответствующие сервер: триггеры по 44-ФЗ - https://fz44.gosplan.info, триггеры по 223-ФЗ - https://223.gosplan.info.

Формат запроса для создания триггера

POST /api/v1/purchases/events

Тело запроса

{
"event": {
"purchase_number": "123123",
"callback_url": "https://my.app1.com/callback",
"state": "secret"
}
}

Наименование параметра

Описание

purchase_number

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

Обязательный параметр.

callback_url

URL клиентского приложения, на который API-сервер выполнит POST-запрос при изменении состояния закупки. callback_url должен совпадать или начинаться с URL-а, указанного в настройках приложения.

Адрес приложения https://my.app1.com, то callback_url может иметь значения https://my.app1.com , https://my.app1.com/some/thing/else , но не https://subdomain.my.app1.com или https://my.app2.com .

Обязательный параметр.

state

Параметр состояния. Данный параметр будет передан в теле webhook-а при срабатывании триггера. Может использоваться как параметр для авторизации.

Опциональный параметр.

Параметры ответа

Статус 201
Статус 200
Статус 403
Статус 201

Статус 201 - триггер создан

Тело ответа:

{
"id": 1,
"type": "PurchaseEvent",
"api_key": "123",
"number": "123123",
"state": "secret",
"callback_url": "https://my.app1.com/callback",
"created_at": "2021-03-04T23:38:02.377+03:00",
"updated_at": "2021-03-04T23:38:02.377+03:00"
}

Наименование параметра

Описание

id

Ид-р триггера. Не используется в API

type

Тип триггера. PurchaseEvent - триггер на закупку. Пока единственный тип, в перспективе номенклатура типов событий будет расширяться

api_key

API-ключ приложения, которое создало триггер

number

Номер закупки.

Внимание, при создании использовалось поле purchase_number, а в ответе это же поле называется number . Это обусловлено тем, что ответ на создание триггера будет универсальным для всех типов триггеров.

В перспективе, запрос на создание триггера будет допускать использование либо number , либо purchase_number

state

Параметр состояния, переданный в одноименном поле при создании триггера.

callback_url

URL клиентского приложения, на который API-сервер выполнит POST-запрос при изменении состояния закупки.

created_at

Дата/время создания триггера.

updated_at

Дата/время обновления триггера.

Триггер данного типа не может быть обновлен, поэтому значение поля совпадает со значением в created_at.

Статус 200

Статус 200 - триггер для указанной закупки уже существует

Ответ аналогичен статусу 201.

Статус 403

Статус 403 - некорректный запрос

Тело ответа

{
"error": "Текст ошибки"
}

Ошибка при установке триггера может быть связанна со следующими моментами:

  • в настройках приложения на https://dev.gosplan.info/ не задан URL Вашего приложения. Если URL задан, а ошибка сохраняется, попробуйте обновить ключ доступа к API-серверу;

  • заданный callback_url не соответствует URL-у в настройках приложения;

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

В случае, если при создании триггера получен статус 200 или 201, то API сервер сохранил необходимые данные и может выполнять HTTP-запросы к Вашему приложению.

Webhook

События, связанные с триггерами, возникают на API-сервере в момент синхронизации с ЕИС, либо в момент срабатывания контрольного времени.

В ЕИС для закупок 223-ФЗ изменение состояние закупки в "работа комиссии" в большинстве случаев осуществляется по факту наступления времени окончания подачи заявок. Для 44-ФЗ аналогичный переход осуществляется по факту публикации документа.

Поэтому для API-сервера 223-ФЗ реализован автоматический переход в "работа комиссии" (срабатывание контрольного времени) с генерацией вебхука.

API-сервер 44-ФЗ не выполняет автоматический переход и генерирует вебхуки только по факту публикации документов.

Формат запроса Webhook-а

POST https://my.app1.com/callback

Тело запроса

{
"type": "PurchaseEvent",
"number": "123123",
"scope": "fz44",
"state": "secret"
}

Наименование параметра

Описание параметра

type

Тип триггера. PurchaseEvent - триггер на закупку. Пока единственный тип, в перспективе номенклатура типов событий будет расширяться

number

Номер закупки.

Внимание, при создании использовалось поле purchase_number, а в ответе это же поле называется number . Это обусловлено тем, что ответ на создание триггера будет универсальным для всех типов триггеров.

В перспективе, запрос на создание триггера будет допускать использование либо number , либо purchase_number

scope

Содержит значение fz44 или fz223 в зависимости от того, какие API-сервером сгенерирован вебхук. Параметр может оказаться полезным, если вебхуки с обоих серверов заведены на один callback_url

state

Параметр состояния, переданный в одноименном поле при создании триггера.

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

В случае, если HTTP статус ответа на запрос вебхука отличается от 2XX, то запрос повторяется еще 2 раза.

Удаление триггера

В случае, если события триггера более не актуальны рекомендуется удалить триггер:

Формат запроса на удаление триггера

DELETE /api/v1/purchases/events/:purchase_number

В не зависимости от существования триггера, HTTP-статус ответа - 204. Тело ответа отсутствует.

Зачем удалять триггеры?

Количество триггеров для каждого приложение ограничено. Если не удалять триггеры, то рано или поздно Вы не сможете создать новые. Лимиты на создание триггеров приведены на странице профиля https://dev.gosplan.info/dashboard.

Просмотр триггеров

Для просмотра существующих триггеров, Вы можете воспользоваться запросами для получения списка активных триггеров и получения триггера по номеру закупки.

Получение списка триггеров

GET /api/v1/purchases/events?page=1&per=20

Параметры запроса в URL-е

Наименование параметра

page

Номер страницы с записями. Список триггеров выводится в постраничном режиме

per

Количество записей на страницу

Тело ответа

[
{
"callback_url": "https://my.app1.com/callback",
"purchase_number": "123123",
"state": "secret"
},
...
]

Заголовки ответа

Наименование

Описание

X-Page

Текущая страница ответа

X-Total

Общее количество записей, удовлетворяющих запросу

X-TotalPages

Всего страниц записей, удовлетворяющих запросу

Получение триггера по номеру

GET /api/v1/purchases/events/:purchase_number

Тело ответа совпадает с ответом на запрос создания триггера.