Сервис сбора уведомлений из Госпочты

Сервис сбора уведомлений из Госпочты — решение для автоматического сбора и скачивания уведомлений(писем) и документов от государственных ведомств и органов управления.

Интеграция с Госпочтой позволяет пользователям быстро получать все типы уведомлений.

Сервис является частью платформы Агредатор. Перед изучением данной документации ознакомьтесь со следующими обязательными документами по интеграции с платформой:

• Общие принципы работы с API
• HTTP‑шлюз
• Файловый сервис Filator

Глоссарий

Общая схема работы

1. Ваша система настраивает подписку в сервисе по сбору уведомлений из Госпочты (rpa-full-state-mail) и указывает, по каким ведомствам нужно опрашивать Госпочту.
2. Сервис rpa-full-state-mail по расписанию опрашивает Госпочту, получает новые уведомления и:
   • сохраняет файлы уведомлений (feed и вложения) в файловом хранилище Filator,
   • регистрирует входящие события во внутреннем реестре входящих запросов (incomings) платформы Агредатор.
3. Для доступа к этим входящим запросам и файлам ваша система использует REST‑API HTTP‑шлюза Агредатора по эндпоинтам /api/v1/<service-name>/incomings….

Таким образом, сам сервис rpa-full-state-mail не предоставляет внешний REST‑API, а публикует входящие данные, к которым вы обращаетесь через HTTP-Шлюз Агредатора (Модели получения уведомлений).

Модели получения уведомлений

Получать уведомления Госпочты можно двумя способами:

1. Pull‑модель (опрос через API) Ваша система периодически опрашивает HTTP‑шлюз Агредатора:
   • GET /api/v1/<service-name>/incomings.json - список входящих запросов;
   • GET /api/v1/<service-name>/incomings/{id} - детали одного входящего запроса;
   • GET /api/v1/<service-name>/incomings/{id}/attachments/{uuid} - получение файла feed или вложения из уведомления.
2. Push‑модель (callback/push со стороны Агредатора) HTTP‑шлюз Агредатора может по настройке отправлять HTTP POST‑запросы на указанный вами callback‑URL при появлении новых входящих запросов или изменении их статуса. Формат данных в таком callback‑уведомлении соответствует структуре сущности Incoming (см. раздел Структура входящего запроса (Incoming)) либо описанию в разделе Callback/Push общей документации Агредатора.

Доступ к уведомлениям через HTTP-Шлюз Агредатора

HTTP‑шлюз Агредатора предоставляет REST‑API для доступа к уведомлениям, которые сервис сбора уведомлений из Госпочты публикует во внутренний реестр входящих запросов. Название сервиса во входящих запросах (часть пути после /api/v1/, например rpa-full-state-mail-in) зависит от настроек конкретного клиента и может отличаться. Актуальное имя сервиса для вашей организации уточняйте у службы поддержки Агредатора.

Все запросы выполняются через HTTP‑шлюз Агредатора и требуют базовой авторизации:

curl -u "$USER_IDENTIFICATOR:$USER_SECRET" ...

USER_IDENTIFICATOR и USER_SECRET клиент получает у службы поддержки Агредатора.

Базовый URL (пример тестового контура):

http://agredator.ru/api/v1/<service-name>

где <service-name> - код сервиса входящих запросов вашего клиента (например, rpa-full-state-mail-in). Конкретное значение <service-name> уточняйте у поддержки Агредатора. Для продуктивного контура URL отличается доменом (уточняйте у службы поддержки Агредатора).

Структура входящего запроса (Incoming)

Основной сущностью при работе с уведомлениями через HTTP-Шлюз Агредатора является объект Incoming - один входящий запрос, полученный в Агредатор от сервиса по сбору уведомлений из Госпочты (rpa-full-state-mail), содержащий данные об уведомлении.

{
  "id": 204248,
  "external_id": "2000011282946175",
  "status": 100,
  "client": "ff239af9a4c9c8a0bd40f7020e2ca5ea",
  "service": "<service-name>",
  "created_at": "2026-03-25T18:14:06.638+03:00",
  "identifier": "43ed39ae-285d-11f1-b99f-3a53c2299f30-18501fec1dcd8ecd",
  "request": {
    "feed": {
      "uuid": "dd43cc2e56590902700fc41e7a10ad217e039f540f16daa48d1",
      "checksum": "060619159a2b63552f80b2eb705e19e31c36a04198e2e5c41fc6b6c9f19ece2e",
      "filename": "feed.json",
      "delete_at": "2026-04-24T15:14:06.014+00:00",
      "mime_type": "application/json"
    },
    "client": "test_client",
    "client_id": "6311196251",
    "attachments": [
      {
        "uuid": "14bfffd0973b952ba52720a0320cae62f5a89f2645f4052a0922596d2403b516",
        "checksum": "60859dd925161e8b437e08639e5ae09eed8f54be75a052773b39ddfdbd626ac8",
        "filename": "piev_75451091143077.pdf",
        "delete_at": "2026-04-24T15:14:04.589+00:00",
        "mime_type": "application/pdf",
        "external_id": 16600414739
      }
      // ...
    ]
  },
  "histories": [],
  "responses": []
}

Ключевые элементы:

• Incoming - «карточка» входящего уведомления (идентификаторы, статус, даты).
• request - данные, которые пришли от сервиса Cбор уведомлений из Госпочты по данному уведомлению.
• request.feed - ссылка на файл feed.json с полным описанием уведомления (метаданные ведомства, статусы доставки, текст письма и т.п.).
• request.attachments - ссылки на PDF/XML‑файлы прикрепленные к уведомлению в Госпочте.
• histories - история изменения статуса Incoming в Агредаторе.
• responses - попытки отправки callback‑уведомлений (если настроены).

Дальнейшие разделы детализируют элементы этого объекта: параметры запросов к API, структуры Feed и AttachmentInfo, статусы и histories/responses.

Принимаемые параметры

Параметры для настройки подписки (сервис сбора уведомлений из Госпочты)

Сервис принимает запросы для конфигурации опроса писем. Для создания/изменения подписки используются сообщения типа create. Для отключения/прекращения опроса по сервисам используются сообщения типа cancel.

В списке services допустимо указание специального значения ALL, которое позволяет отписаться от всех сервисов или подписаться на все сразу.

Режим сбора with_chain

Параметр задаёт, что именно попадает в уведомления по этой подписке:

• true (по умолчанию) — сбор с цепочкой: уведомление содержит всю цепочку сообщений письма, включая сообщения, полученные в ЕПГУ до создания подписки;
• false — сбор без цепочки: из письма передаются только сообщения, полученные в ЕПГУ начиная с даты старта подписки. Более ранние сообщения и их вложения не передаются; если в письме таких сообщений не осталось, уведомление по нему не отправляется.

Дата старта подписки определяется сервисом в момент обработки запроса create — отдельным параметром она не передаётся.

Параметр допускает только логические значения true/false. Строковое представление ("true"), число или null — ошибка валидации: подписка не создаётся и не изменяется. Если параметр не передан, используется true, поэтому поведение действующих подписок не меняется.

В запросе cancel параметр не требуется и не обрабатывается.

Изменить режим у действующей подписки нельзя. Для смены режима нужно отменить подписку (cancel), дождаться успешного ответа и создать новую (create) с нужным значением with_chain — у неё будет новая дата старта. Ранее переданные уведомления повторно не отправляются.

Параметры запросов к HTTP-Шлюзу Агредатора для работы с уведомлениями

Список входящих запросов содержащих информацию об уведомлениях

GET /api/v1/<service-name>/incomings.json

Эндпоинт поддерживает два режима работы с пагинацией:

1. Пагинация по last_id (рекомендовано для потоковой обработки)

Также поддерживается режим постраничного обхода через last_id:

• last_id - идентификатор последнего обработанного входящего запроса. При указании last_id сервис вернёт следующую «страницу» данных после этого идентификатора.

Пример:

curl -u "$USER_IDENTIFICATOR:$USER_SECRET" \
  "http://agredator.ru/api/v1/<service-name>/incomings.json?last_id=204248" \
  > inc_after_204248.json

Поле last_id в ответе отражает идентификатор последнего входящего запроса в текущей выборке.

1. Постраничная пагинация

Вы можете явно указать номер страницы:

• page - номер страницы (целое число, начиная с 1).

Пример:

curl -u "$USER_IDENTIFICATOR:$USER_SECRET" \
  "http://agredator.ru/api/v1/<service-name>/incomings.json?page=2" \
  > inc_page_2.json

Информация о текущей странице дополнительно возвращается в полях ответа: current_page, per_page, has_next.

Фильтрация

Для ограничения выборки по статусу или сервису доступны следующие параметры:

• filter[status] - фильтрация по полю status объекта Incoming (целое число, например 100 или 500);
• filter[service] - фильтрация по полю service (строка, например rpa-full-state-mail-in).

Примеры:

# Все успешно обработанные входящие (status = 100)
curl -u "$USER_IDENTIFICATOR:$USER_SECRET" \
  "http://agredator.ru/api/v1/<service-name>/incomings.json?filter[status]=100" \
  > inc_ok.json

# Входящие только по сервису rpa-full-state-mail-in
curl -u "$USER_IDENTIFICATOR:$USER_SECRET" \
  "http://agredator.ru/api/v1/<service-name>/incomings.json?filter[service]=rpa-full-state-mail-in" \
  > inc_by_service.json

Детали одного входящего запроса содержащий информацию об уведмолении

GET /api/v1/<service-name>/incomings/{id}

Получение файла feed или вложения из уведомления

GET /api/v1/<service-name>/incomings/{id}/attachments/{uuid}

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

Ответ на запрос с данными о подписке (от сервиса по сбору уведомлений из Госпочты)

Данные о полученном уведомлении (общая структура сообщений)

Сервис периодически, на основании данных о подписках, проверяет наличие новых писем (уведомлений) в Госпочте. При получении новых уведомлений или обновлений сервис отправляет сообщения следующей структуры во внутренние системы Агредатора и внешний адаптер (если используется):

Структура элемента Feed

Элемент feed всегда расположен внутри поля request объекта Incoming. Содержит данные об уведомлении ведомства (само «письмо»/уведомление и связанные сообщения). Данные уведомления загружаются в файловое хранилище Агредатора.

Структура элемента AttachmentInfo

Каждый элемент массива attachments[] внутри request объекта Incoming описывает один файл, связанный с уведомлением (PDF/XML и т.п.).

Формат ответов по входящим запросам

Список входящих запросов

Ответ содержит массив объектов Incoming в поле collection:

{
  "has_next": true,
  "current_page": 1,
  "per_page": 15,
  "collection": [
    {
      "id": 203942,
      "external_id": "6000008156654115",
      "status": 100,
      "client": "ff239af9a4c9c8a0bd40f7020e2ca5ea",
      "info": null,
      "service": "rpa-full-state-mail-in",
      "created_at": "2026-02-13T15:41:21.342+03:00",
      "identifier": "9bb70684-08d6-11f1-9ab6-04d4c4928ed2-06ed2c860a832c9f",
      "request": {
        "feed": {
          "uuid": "dd43cc2e56590902700fc41e7a10ad217e039f540f16daa48d1",
          "checksum": "2139cc4767b8ff02a30adef8d32f9524cc907ec84004f42b52d6c9",
          "filename": "feed.json",
          "delete_at": "2026-03-15T12:22:05.207+00:00",
          "mime_type": "application/json"
        },
        "client": "test_client",
        "client_id": "23123123196251",
        "attachments": [
          {
            "uuid": "aa773f59d4770fcfa4c19a34ab210fc0f849688c47287ace551cd9",
            "checksum": "ff1270f379f4ceae34f4480fb5a50020b855ca9872206",
            "filename": "piev_2341358.xml",
            "delete_at": "2026-03-15T12:21:54.831+00:00",
            "mime_type": "application/xml",
            "external_id": 22221571112
          }
          // ...
        ]
      },
      "histories": [],
      "responses": []
    }
    // ...
  ],
  "last_id": 204248
}

Ключевые поля объекта Incoming перечислены в разделе Структура входящего запроса (Incoming).

Детали одного входящего запроса

Ответ по GET /incomings/{id} возвращает один объект Incoming (см. Структура входящего запроса (Incoming)).

Ответ при получении файла

По GET /incomings/{id}/attachments/{uuid} тело ответа - содержимое файла по указанному uuid, Content-Type соответствует mime_type файла в request.feed или request.attachments. Для uuid из request.feed будет возвращён JSON вида feed_example.json с полной структурой уведомления ведомства (метаданные, статусы доставки, сообщения, вложения и т.п.).

Статусы, histories и responses

Поле status объекта Incoming отражает текущий статус обработки входящего запроса в платформе Агредатор.

Часто используемые значения (по данным примеров):

Конкретный перечень статусов может быть расширен; при интеграции рекомендуется:

• ориентироваться на status = 100 как на «успех»;
• анализировать histories и responses для диагностики ошибок при статусах 500.

Поле histories

histories содержит историю изменения статусов входящего запроса в Агредаторе. Каждый элемент включает:

• from / to - исходный и новый статус,
• message - текст пояснения (например, Unable to send response),
• created_at / updated_at - время изменения,
• historyable_type, historyable_id - ссылки на сущность (Incoming или IncomingResponse).

Используйте histories, чтобы:

• понять, сколько раз и когда пытались отправить ответ,
• диагностировать причины ошибок (например, сторонний endpoint не принимает callback).

Поле responses

responses описывает попытки отправки callback‑ответов по входящему запросу (если для клиента настроен callback‑URL). Элемент responses обычно содержит:

• id - идентификатор попытки ответа,
• status - статус попытки (например, 500 при ошибке доставки),
• info - текстовое описание (например, Unable to send response),
• callback_incoming_url - URL, на который пытались отправить ответ,
• вложенный histories - история изменения статуса попытки ответа.

Это поле удобно использовать для мониторинга интеграции:

• убедиться, что ваша система корректно принимает callback‑уведомления,
• отслеживать, не «падает» ли внешний endpoint.

Примеры

Примеры запросов к сервису по сбору уведомлений из Госпочты (подписка)

Создание подписки

{
  "client_id": "client_id",
  "type": "create",
  "services": [
    "ALL"
  ]
}

Подписка без цепочки сообщений — передаются только сообщения, полученные в ЕПГУ начиная с даты старта подписки:

{
  "client_id": "client_id",
  "type": "create",
  "services": [
    "ALL"
  ],
  "with_chain": false
}

Отключение подписки

{
  "client_id": "client_id",
  "type": "cancel",
  "services": [
    "ALL"
  ]
}

Ответ на изменение/отключение подписки

{
  "status": "ok"
}

Пример сообщения с данными об уведомлении (от сервиса по сбору уведомлений из Госпочты)

{
  "client": "test_client",
  "client_id": "client_id_rnds",
  "feed": {
    "uuid": "dd43cc2e56590902700fc41e7a10ad217e039f540f16daa48d1",
    "checksum": "cb7ca899d4a652e0f82a21e604c910eaaf5f90c49df6f6e668476a5ae39b4623",
    "filename": "feed.json",
    "delete_at": "2025-10-31T13:23:07.302+00:00",
    "mime_type": "application/json"
  },
  "attachments": [
    {
      "uuid": "674d819845ab7a7715c5185a40c8223ffc55bf70fdea",
      "checksum": "840175c3e48a16a9d28cdaead3e95b7e6fccfd61b5cd1eeaa6cccf39ad777927",
      "filename": "piev_45221591027240.pdf",
      "delete_at": "2025-10-31T13:23:04.593+00:00",
      "mime_type": "application/pdf",
      "external_id": 14704181678
    },
    {
      "uuid": "485dcaa476b8357cbf1a27cfeb8eb93cec84201bd3d87dfa63fa3",
      "checksum": "10b5d838b5e10e7901530d0985ff9d831f54dc8380dd2b8d5777983e4c5244b9",
      "filename": "piev_45221591027240.xml",
      "delete_at": "2025-10-31T13:23:07.286+00:00",
      "mime_type": "application/xml",
      "external_id": 14704181677
    }
  ]
}

Пример файла вложения с данными уведомления - реальные данные изменены и могут быть невалидными; задача файла - показать структуру данных уведомления, отправленного от ведомства ФССП в Госпочте.

Примеры запросов для работы с уведомлениями

Список входящих запросов содержащих информацию об уведомлениях

curl -u "$USER_IDENTIFICATOR:$USER_SECRET" \
  "http://agredator.ru/api/v1/<service-name>/incomings.json" \
  > inc.json

Детали одного входящего запроса содержащий информацию об уведмолении

curl -u "$USER_IDENTIFICATOR:$USER_SECRET" \
  "http://agredator.ru/api/v1/<service-name>/incomings/204248" \
  > inc_request.json

Получение файла feed.json из уведомления

curl -u "$USER_IDENTIFICATOR:$USER_SECRET" \
  "http://agredator.ru/api/v1/<service-name>/incomings/204248/attachments/dd43cc2e56590902700fc41e7a10ad217e039f540f16daa48d1" \
  > inc_request_request_feed_attach.json