Триггеры

ГосПлан API
Search…
ГосПлан API
Описание
Таблица кодов регионов
Триггеры
Триггеры - это специальный механизм, позволяющий приложениям получать 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.
Формат запроса для создания триггера
1
POST /api/v1/purchases/events
Copied!
Тело запроса
1
{
2
    "event": {
3
        "purchase_number": "123123",
4
        "callback_url": "https://my.app1.com/callback",
5
        "state": "secret"
6
    }
7
}
Copied!
Наименование параметра
Описание
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 - триггер создан
Тело ответа:
1
{
2
    "id": 1,
3
    "type": "PurchaseEvent",
4
    "api_key": "123",
5
    "number": "123123",
6
    "state": "secret",
7
    "callback_url": "https://my.app1.com/callback",
8
    "created_at": "2021-03-04T23:38:02.377+03:00",
9
    "updated_at": "2021-03-04T23:38:02.377+03:00"
10
}
Copied!
Наименование параметра
Описание
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 - триггер для указанной закупки уже существует
Ответ аналогичен статусу 201.
Статус 403 - некорректный запрос
Тело ответа
1
{
2
    "error": "Текст ошибки"
3
}
Copied!
Ошибка при установке триггера может быть связанна со следующими моментами:
в настройках приложения на https://dev.gosplan.info/ не задан URL Вашего приложения. Если URL задан, а ошибка сохраняется, попробуйте обновить ключ доступа к API-серверу;
заданный callback_url не соответствует URL-у в настройках приложения;
превышено максимальное количество триггеров данного приложения для данного API-сервера.
В случае, если при создании триггера получен статус 200 или 201, то API сервер сохранил необходимые данные и может выполнять HTTP-запросы к Вашему приложению.
Webhook
События, связанные с триггерами, возникают на API-сервере в момент синхронизации с ЕИС, либо в момент срабатывания контрольного времени.
В ЕИС для закупок 223-ФЗ изменение состояние закупки в "работа комиссии" в большинстве случаев осуществляется по факту наступления времени окончания подачи заявок. Для 44-ФЗ аналогичный переход осуществляется по факту публикации документа.
Поэтому для API-сервера 223-ФЗ реализован автоматический переход в "работа комиссии" (срабатывание контрольного времени) с генерацией вебхука.
API-сервер 44-ФЗ не выполняет автоматический переход и генерирует вебхуки только по факту публикации документов.
Формат запроса Webhook-а
1
POST https://my.app1.com/callback
Copied!
Тело запроса
1
{
2
    "type": "PurchaseEvent",
3
    "number": "123123",
4
    "scope": "fz44",
5
    "state": "secret"
6
}
Copied!
Наименование параметра
Описание параметра
type
Тип триггера. PurchaseEvent - триггер на закупку. Пока единственный тип, в перспективе номенклатура типов событий будет расширяться
number
Номер закупки.
Внимание, при создании использовалось поле purchase_number, а в ответе это же поле называется number . Это обусловлено тем, что ответ на создание триггера будет универсальным для всех типов триггеров.
В перспективе, запрос на создание триггера будет допускать использование  либо number , либо purchase_number
scope
Содержит значение fz44 или fz223   в зависимости от того, какие API-сервером сгенерирован вебхук. Параметр может оказаться полезным, если вебхуки с обоих серверов заведены на один callback_url
state
Параметр состояния, переданный в одноименном поле при создании триггера.
Вебхук не содержит какую-либо информацию о содержании закупки или изменений в ней, а лишь уведомляет о факте каких-то изменений. Для получения изменений необходимо выполнить запрос этой закупки через соответствующий API и выполнить сравнение на стороне клиентского приложения.
В случае, если  HTTP статус ответа на запрос вебхука отличается от 2XX, то запрос повторяется еще 2 раза.
Удаление триггера
В случае, если события триггера более не актуальны рекомендуется удалить триггер:
Формат запроса на удаление триггера
1
DELETE /api/v1/purchases/events/:purchase_number
Copied!
В не зависимости от существования триггера, HTTP-статус ответа - 204. Тело ответа отсутствует.
Зачем удалять триггеры?
Количество триггеров для каждого приложение ограничено. Если не удалять триггеры, то рано или поздно Вы не сможете создать новые. Лимиты на создание триггеров приведены на странице профиля https://dev.gosplan.info/dashboard.
Просмотр триггеров
Для просмотра существующих триггеров, Вы можете воспользоваться запросами для получения списка активных триггеров и получения триггера по номеру закупки.
Получение списка триггеров
1
GET /api/v1/purchases/events?page=1&per=20
Copied!
Параметры запроса в URL-е
Наименование параметра
​
page
Номер страницы с записями. Список триггеров выводится в постраничном режиме
per
Количество записей на страницу
Тело ответа
1
[
2
    {
3
        "callback_url": "https://my.app1.com/callback",
4
        "purchase_number": "123123",
5
        "state": "secret"
6
    },
7
    ...
8
]
Copied!
Заголовки ответа
Наименование 
Описание
X-Page
Текущая страница ответа
X-Total
Общее количество записей, удовлетворяющих запросу
X-TotalPages
Всего страниц записей, удовлетворяющих запросу
Получение триггера по номеру
1
GET /api/v1/purchases/events/:purchase_number
Copied!
Тело ответа совпадает с ответом на запрос создания триггера.
​
​
223-ФЗ
Таблица кодов регионов
Last modified 7mo ago
Copy link
Contents