Описание интерфейса программирования приложений в информационно-телекоммуникационной сети интернет для доступа к общедоступным сведениям банка данных в исполнительном производстве ФССП России (утв. ООО "Драйв Диджитал" и Управлением информационных технологий Федеральной службы судебных приставов 30, 31 января 2018 г.)

Версия документа - 1.0

Версия API - 1.0

Термины и сокращения

Термин/сокращение	Описание
API	Application Programming Interface, интерфейс программирования приложений
БДИП	Банк данных в исполнительном производстве
ИП	Исполнительное производство
CURL	Служебная программа командной строки, позволяющая взаимодействовать с сервером по различным протоколам с синтаксисом URL
JSON	Javascript Object Notation, основанный на синтаксисе Javascript формат обмена данными
HTTPS	HyperText Transfer Protocol Secure, расширение протокола HTTP с поддержкой шифрования
REST	Representational State Transfer, архитектурный стиль организации сетевого взаимодействия

1. Основание для разработки

Публичный API доступа к банку данных исполнительных производств разработан во исполнение пункта 7.4 Порядка создания и ведения банка данных в исполнительном производстве Федеральной службы судебных приставов, утвержденного приказом Федеральной службы судебных приставов от 12 мая 2012 г. N 248 (в редакции приказа от 27.12.2017 N 676).

2. Назначение интерфейса программирования приложений

Назначение интерфейса программирования приложений - обеспечение возможности получения отдельных видов сведений БДИП сторонними информационными системами. Возможно получение следующих сведений:

- Сведения об исполнительных производствах в отношении юридических лиц (по наименованию, региону, юридическому адресу);

- Сведения об исполнительных производствах в отношении физических лиц (по фамилии, имени и отчеству, дате рождения и региону);

- Сведения об исполнительном производстве (по его номеру).

3. Процедура регистрации

Для доступа к API требуется авторизация. Авторизация производится по ключу доступа, передаваемому в каждом запросе и получаемому пользователем API при регистрации.

Ссылка на форму регистрации пользователя API размещена на странице http://fssprus.ru/iss/ip. Форма защищена от автоматической регистрации.

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

Срок действия выданного ключа доступа - 1 год.

4. Общие сведения о работе API

Предоставляемый API доступа выполнен в архитектурном стиле REST, принимает HTTPS-запросы, возвращает результаты в формате JSON.

Адрес точки доступа к API: https://api-ip.fssprus.ru/api/v1.0/.

Предоставляемый API:

- требует авторизации пользователей;

- является асинхронным;

- предоставляет возможность групповых запросов.

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

Асинхронность API означает, что в ответ на подачу запроса пользователю передается идентификатор, по которому пользователь отдельными методами должен будет определить статус выполнения запроса и получить ответ.

Групповые (пакетные) запросы запросы, дающие возможность указать одновременно несколько наборов значений параметров ("подзапросов"). Устанавливается ограничение на количество подзапросов в групповом запросе.

5. Описание методов API

5.1. "Запрос на поиск сведений о физическом лице"

GEТ/search/physical

Параметр запроса	Описание параметра
token*	Ключ доступа к API, полученный при регистрации
region*	Код региона отдела судебных приставов, ведущего ИП, в соответствии со справочником регионов ФССП России
firstname*	Имя должника по исполнительному производству
secondname	Отчество должника по исполнительному производству
lastname*	Фамилия должника по исполнительному производству
birthdate	Дата рождения должника в формате "дд.мм.гггг"

CURL-пример запроса приводится в разделе 6.1.

В штатном режиме функционирования API возможны следующие ответы на запрос, выполненный методом /search/physical:

- Сообщение о недействительности ключа доступа;

- Сообщение об ошибках форматно-логического контроля (например, не указано значение обязательного параметра метода; в таблицах с описаниями параметров такие параметры помечены звездочкой "*");

- Сгенерированный API идентификатор запроса.

Примеры ответов для трех перечисленных случаев приведены ниже.

{    "status": "error",    "code": 401,    "exception": "invalid token",    "response": [] }

{    "status": "error",    "code": 400,    "exception": "invalid request params",    "response": [] }

{    "status": "success",    "code": 0,    "exception": "",    "response": {       "task": "ADAB49B2-F435-49CC-80DF-55F2F57D3057"    } }

Значение response.task в дальнейшем используется в качестве параметра вызовов методов 5.5 и 5.6.

5.2. "Запрос на поиск сведений о юридическом лице"

GET/search/legal

Параметр запроса	Описание параметра
token*	Ключ доступа к API, полученный при регистрации
region*	Код региона отдела судебных приставов, ведущего ИП, в соответствии со справочником регионов ФССП России
name*	Фрагмент названия должника - юридического лица
address	Фрагмент юридического адреса юридического лица

CURL-пример запроса приводится в разделе 6.2.

В штатном режиме функционирования API возможны следующие ответы на запрос, выполненный методом /search/legal:

- Сообщение о недействительности ключа доступа;

- Сообщение об ошибках форматно-логического контроля (например, не указано значение обязательного параметра метода; в таблицах с описаниями параметров такие параметры помечены звездочкой "*");

- Сгенерированный API идентификатор запроса.

Примеры ответов для трех перечисленных случаев приведены ниже.

{    "status": "error",    "code": 401,    "exception": "invalid token",    "response": [] }

{    "status": "error",    "code": 400,    "exception": "invalid request params",    "response": [] }

{    "status": "success",    "code": 0,    "exception": "",    "response": {       "task": "BDAB49B2-F435-49CC-80DF-55F2F57D3057"    } }

Значение response.task в дальнейшем используется в качестве параметра вызовов методов 5.5 и 5.6.

5.3. "Запрос на поиск сведений об исполнительном производстве"

GET/search/ip

Параметр запроса	Описание
token*	Ключ доступа к API, полученный при регистрации
number*	Номер исполнительного производства в формате "n_n/yy/dd/rr" или "n_n/yy/ddddd-ИП", где: - n_n - собственная часть номера; - yy - последние две цифры года возбуждения ИП; - ddddd - полный номер отдела судебных приставов; - dd - последние две цифры номера отдела; - rr - номер региона отдела судебных приставов по справочнику регионов ФССП России

CURL-пример запроса приводится в разделе 6.3.

В штатном режиме функционирования API возможны следующие ответы на запрос, выполненный методом /search/ip:

- Сообщение о недействительности ключа доступа;

- Сообщение об ошибках форматно-логического контроля (например, не указано значение обязательного параметра метода; в таблицах с описаниями параметров такие параметры помечены звездочкой "*");

- Сгенерированный API идентификатор запроса.

Примеры ответов для трех перечисленных случаев приведены ниже.

{    "status": "error",    "code": 401,    "exception": "invalid token",    "response": [] }

{    "status": "error",    "code": 400,    "exception": "invalid request params",    "response": [] }

{    "status": "success",    "code": 0,    "exception": "",    "response": {       "task": "CDAB49B2-F435-49CC-80DF-55F2F57D3057"    } }

Значение response.task в дальнейшем используется в качестве параметра вызовов методов 5.5 и 5.6.

5.4. "Групповой запрос на поиск информации в БДИП"

POST/search/group

Групповой запрос подается HTTP-методом POST. Тело запроса содержит JSON-объект с двумя полями: token и request.

Значением token является ключ доступа к API, передавать его как GET-параметр при групповом запросе не следует.

Значением request является массив объектов, соответствующих отдельным запросам, каждый такой объект имеет два поля: request[].type и request[].params.

Значение request[] .type указывает тип запроса:

- 1 - запрос на поиск сведений о физическом лице;

- 2 - запрос на поиск сведений о юридическом лице;

- 3 - запрос сведений об исполнительном производстве.

Значением request[].params должен быть набор пар ключ-значение, где ключами являются названия параметров соответствующих запросов 5.1-5.3, а значениями - значения этих параметров.

Пример тела группового запроса на поиск информации приводится ниже.

{    "token": "yourapikey",    "request": [       {          "type": 1,          "params": {             "firstname": "Сергей",             "lastname": "Иванов",             "region": 66          }       },       {          "type": 2,          "params": {             "name": "Ромашка",             "region": 66          }       },       {          "type": 3,          "params": {             "number": "6860/12/61/66"          }       }    ] }

CURL-пример запроса приводится в разделе 6.4.

В штатном режиме функционирования API возможны следующие ответы на запрос, выполненный методом /search/group:

- Сообщение о недействительности ключа доступа;

- Сообщение об ошибках форматно-логического контроля (например, не указано значение обязательного параметра метода; в таблицах с описаниями параметров такие параметры помечены звездочкой "*");

- Сгенерированный API идентификатор запроса.

Примеры ответов для трех перечисленных случаев приведены ниже.

{    "status": "error",    "code": 401,    "exception": "invalid token",    "response": [] }

{    "status": "error",    "code": 400,    "exception": "invalid request params",    "response": [] }

{    "status": "success",    "code": 0,    "exception": "",    "response": {       "task": "DDAB49B2-F435-49CC-80DF-55F2F57D3057"    } }

Значение response.task в дальнейшем используется в качестве параметра вызовов методов 5.5 и 5.6.

5.5. "Проверка статуса поданного запроса"

GET/status

Параметр запроса	Описание параметра
token*	Ключ доступа к API, полученный при регистрации
task*	Идентификатор отправленного запроса

CURL-пример запроса приводится в разделе 6.5.

В штатном режиме функционирования API возможны следующие ответы:

- Сообщение об ошибке при обработке текущего запроса;

- Сообщение о статусе обработки прежде поданного запроса сведений БДИП.

В последнем случае ответ сервиса имеет вид как в примере ниже.

{    "status": "success",    "code": 0,    "exception": "",    "response": {       "status": 0,       "progress": "1 of 1"    } }

В приведенном ответе:

- response.status - статус обработки прежде поданного запроса сведений БДИП, возможные значения:

- 0 - обработка завершена, с помощью метода /result можно получить результаты;

- 1 - обработка начата, с помощью метода /result можно получить частичные результаты группового запроса;

- 2 - обработка не начиналась, запрос находится в очереди;

- 3 - обработка завершена, имели место ошибки, с помощью метода /result можно получить частичные результаты;

- progress - доля успешно обработанных подзапросов группового запроса, результаты которых можно получить методом /result.

5.6. "Получение результатов поданного запроса"

GET/status

Параметр запроса	Описание параметра
token*	Ключ доступа к API, полученный при регистрации
task*	Идентификатор отправленного запроса

CURL-пример запроса приводится в разделе 6.6.

В штатном режиме функционирования API возможны следующие ответы:

- Сообщение об ошибке при обработке текущего запроса;

- Сообщение, содержащее результаты обработки прежде поданного запроса сведений БДИП.

Для группового запроса ответ выглядит как в примере ниже.

{ "status": "success",    "code": 0,    "exception": "",    "response": {       "status": 0,       "task_start": null,       "result": [          {             "status": 0,             "result": [                {                   "name": "ИВАНОВ СЕРГЕЙ ПЕТРОВИЧ 09.06.1982",                   "exe_production": "6860/12/61/66 от 16.04.2012",                   "details": "Исполнительный лист от 20.03.2012 N ВС 049652131",                   "subject": "Коммунальные платежи",                   "department": 66061,                   "bailiff": "НИТОЧКИНА B. И. 73434246653",                   "ip_end": "2015-06-30, 46, 1, 4"                }             ]          },          {             "status": 3,             "result": {                "code": 0,                "message": "Undefined index: address"             }          },          {             "status": 0,             "result": [                {                   "name": "ИВАНОВ СЕРГЕЙ ПЕТРОВИЧ 09.06.1982",                   "exe_production": "6860/12/61/66 от 16.04.2012",                   "details": "Исполнительный лист от 20.03.2012 N ВС 049652131",                   "subject": "Коммунальные платежи",                   "department": 66061,                   "bailiff": "НИТОЧКИНА B. И. 73434246653",                   "ip_end": "2015-06-30, 46, 1, 4"                }             ]          }       ]    } }

Порядок результатов в response.result соответствует порядку запросов в групповом запросе (см. раздел 5.4).

Для единичных запросов (см. разделы 5.1-5.3) response.result содержит единственный элемент.

6. Примеры запросов

Дополнительные справочные материалы по использованию методов API размещены на официальном интернет-сайте ФССП России. Способ размещения этих материалов дает пользователю API возможность подавать к API тестовые запросы.

Ниже приводятся примеры запросов к методам API с помощью утилиты командной строки CURL. Во всех примерах ниже значение параметра token ("yourapikey") следует заменить на полученный при регистрации ключ доступа.

6.1. "Запрос на поиск сведений о физическом лице"

curl -G https://api-ip.fssprus.ru/api/v1.0/search/physical\    --data-urlencode "region=66"\    --data-urlencode "lastname=Иванов"\    --data-urlencode "firstname=Иван"\    --data-urlencode "token=yourapikey"

6.2. "Запрос на поиск сведений о юридическом лице"

curl -G https://api-ip.fssprus.ru/api/v1.0/search/legal\    --data-urlencode "region=66"\    --data-urlencode "name=Ромашка"\    --data-urlencode "token=yourapikey"

6.3. "Запрос на поиск сведений об исполнительном производстве"

curl -G https://api-ip.fssprus.ru/api/v1.0/search/ip\    --data-urlencode "region=66"\    --data-urlencode "lastname=Иванов"\    --data-urlencode "firstname=Иван"\    --data-urlencode "token=yourapikey"

6.4. "Групповой запрос на поиск информации в БДИП"

curl -X POST https://api-ip.fssprus.ru/api/v1.0/search/group\ -H "Content-Type: application/json"\ -d @- << EOF {    "token": "yourapikey",    "request": [       {          "type": 1,          "params": {             "firstname": "Сергей",             "lastname": "Иванов",             "region": 66          }       },       {          "type": 2,          "params": {             "name": "Ромашка",             "region": 66          }       },       {          "type": 3,          "params": {             "number": "6860/12/61/66"          }       }    ] } EOF

6.5. "Проверка статуса поданного запроса"

curl -G https://api-ip.fssprus.ru/api/v1.0/status\    --data-urlencode "task=ADAB49B2-F435-49CC-80DF-55F2F57D3057"\    --data-urlencode "token=yourapikey"

6.6. "Получение результатов поданного запроса"

curl -G https://api-ip.fssprus.ru/api/v1.0/result\    --data-urlencode "task=BDAB49B2-F435-49CC-80DF-55F2F57D3057"\    --data-urlencode "token=yourapikey"

7. Иные условия предоставления доступа к API

Максимальное число подзапросов в групповом запросе - 100 (если требуется отправить больше число, следует разбивать запрос на несколько).

Срок хранения результатов запроса (промежуток между обращениями к методам/search/и методу/result) - 24 часа.

Контакты технической поддержки:

- Телефон: +7 (495) 870-95-96 (с 9:00 до 18:00).

- Электронная почта: admin@fssprus.ru.

Генеральный директор ООО "Драйв Диджитал"

Д.Е. Власов

Начальник Управления информационных технологий Федеральной службы судебных приставов

Н.В. Звягина