Триггеры
Триггеры - это специальный механизм, позволяющий приложениям получать HTTP-уведомления от сервера ГосПлан (или webhook) по факту наступления определенных событий.
Например, Вы можете через API дать команду серверу выполнить определенный запрос при изменении состояния закупки. В случае публикации в ЕИС нового документа или изменения состояния закупки по наступлении определенного времени, сервер может уведомить Ваше приложение POST-запросом.
В зависимости от того, какие закупки планируете отслеживать, запросы выполняются на соответствующие сервер: триггеры по 44-ФЗ - https://fz44.gosplan.info, триггеры по 223-ФЗ - https://223.gosplan.info.
В настоящее время реализован только один вид событий - изменение состояния закупки. В планах - изменение состояния плана-графика закупок.
ВНИМАНИЕ. Данная функция находится в состоянии бета-тестирования. В случае не ожидаемого поведения просим сообщить в Телеграм-группу ГосПлан API

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

Общая схема

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

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

Перед началом использования триггеров Вам необходимо задать адрес Вашего приложения на странице приложения https://dev.gosplan.info
Страница редактирования приложения
Необходимо указать такой домен приложения, в котором будет обрабатываться запросы от API-сервера.
В зависимости от того, какие закупки планируете отслеживать, запросы выполняются на соответствующие сервер: триггеры по 44-ФЗ - https://fz44.gosplan.info, триггеры по 223-ФЗ - https://223.gosplan.info.
Содание триггера для 44-ФЗ
Swagger UI
POST /api/v1/purchases/events
Содание триггера для 223-ФЗ
Swagger UI
POST /api/v1/purchases/events
В случае, если при создании триггера получен статус 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 раза.

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

В случае, если события триггера более не актуальны рекомендуется удалить триггер:
Триггер для 44-ФЗ
Swagger UI
DELETE /api/v1/purchases/events/{number}
Триггер для 223-ФЗ
Swagger UI
DELETE /api/v1/purchases/events/{number}
В не зависимости от существования триггера, HTTP-статус ответа - 204. Тело ответа отсутствует.
Зачем удалять триггеры?
Количество триггеров для каждого приложение ограничено. Если не удалять триггеры, то рано или поздно Вы не сможете создать новые. Лимиты на создание триггеров приведены на странице профиля https://dev.gosplan.info/dashboard.

Получить триггеры

Для просмотра существующих триггеров, Вы можете воспользоваться запросами для получения списка активных триггеров и получения триггера по номеру закупки.
Триггер для 44-ФЗ
Swagger UI
GET /api/v1/purchases/events
Триггер для 223-ФЗ
Swagger UI
GET /api/v1/purchases/events

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

Триггер для 44-ФЗ
Swagger UI
GET /api/v1/purchases/events/{number}
Триггер для 223-ФЗ
Swagger UI
GET /api/v1/purchases/events/{number}
Тело ответа совпадает с ответом на запрос создания триггера.