Общие принципы работы с API

API-шлюз предоставляет доступ к сервисам «Агредатора» по протоколу HTTP. При этом существуют различные модели взаимодействия: Pull, Push и их комбинации. Каждый сервис, с которым может происходить взаимодействие, предоставляет возможность отправлять запрос в какую-то информационную систему (например в ФНС) или принимать запрос из какой-то информационной системы (например из СМЭВ). В этом разделе представлена общая схема взаимодействия с поставщиками данных (ФНС, ЦБ, СМЭВ) с использованием API-шлюза.

Схема API

Определите тип запроса (исходящий/входящий без вложений, исходящий/входящий с вложением). В этом вам поможет описание конкретного сервиса из каталога. Если ваша организация указана в списке Потребителей сервиса - запрос будет исходящий, если в списке Поставщиков - запрос будет входящий. Возможна ситуация, когда один сервис работает с входящими и исходящими запросами, например сервис ФССП.
Требования по наличию вложения определены также в описании каждого сервиса: обращайте внимание на наличие элемента Attachment.
Посмотрите на схеме, какие методы API необходимо использовать при вашем типе запроса.
Выполните методы в установленном порядке. Получение логов возможно в любой момент после отправки или получения запроса.

Исходящий запрос (request) без вложения

Актуальность логов

При получении логов запросов (например XML-логов взаимодействия со СМЭВ) в их состав будут входить только существующие на данный момент файлы. То есть если ответ от поставщика еще не получен, то XML-файл с ответом будет отсутствовать.

Запрос отправляется в соответствии с документацией API-шлюза "Создание запроса". При обращении к API указывается выбранный сервис из каталога и тело запроса. Пример: в случае работы с сервисом ФНС указывается сервис fns-so, а тело запроса формируется по правилам, указанным на странице соответствующего сервиса в разделе Принимаемые параметры.

Запросив метод "Просмотр состояния запроса", можно узнать состояние запроса: отправлен ли запрос, получен ли ответ и какой, или обработка запроса завершилась ошибкой.

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

Исходящий запрос (request) с вложением

Первым шагом сформируйте необходимое вложение и загрузите его хранилище методом "Загрузка файла вложений в систему". В JSON-ответе будет получен uuid, который необходимо указать при формировании запроса.

Далее отправка запроса аналогична порядку, описанному в разделе Исходящий запрос без вложения.

Входящий запрос (incoming) без вложения

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

После получения запроса (например сохранения его в надёжную БД) в обязательном порядке необходимо подтвердить успешность получения. Для этого воспользуйтесь методом "Подтверждение о принятии входящего запроса".

Внимание

Если для запроса не будет выполнено подтвержение (acknowledge), то он останется в состоянии "новый" и опять будет присутствовать в "списке входящих запросов".

После подготовки ответа на запрос, направьте его методом "Создание ответа на входящий запрос", при этом тело ответа формируется в соответствии с правилами конкретного сервиса.

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

Методом "Просмотр состояния ответа на входящий запрос" можно посмотреть статус отправки конкретного ответа: отправлен ли он, получен или его обработка завершилась ошибкой.

Получение логов запросов опционально при необходимости сохранения логов взаимодействия, может быть выполнено в любой момент после получения запроса.

Входящий запрос (incoming) с вложением

Внимание

Некоторые поставщики данных имеют отложенную проверку при обработке ответов, таким образом успешно отправленный ответ через некоторое время может перейти в состояние "ошибка" даже после того, как ранее уже перешёл в состояние "успех". Чтобы не пропустить такие изменения, следует использовать механизм Push-уведомлений об изменениях статусов ответов.

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