Описание интерфейса программирования приложений в информационно-телекоммуникационной сети интернет для доступа к общедоступным сведениям банка данных в исполнительном производстве ФССП России

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

Термин / сокращение Описание
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 г. № 248 (в редакции приказа от 27.12.2017 № 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. «Запрос на поиск сведений о физическом лице»

GET /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 /result

Параметр запроса Описание параметра
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 № ВС 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 № ВС 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.