## Документация API api-assist.com ФССП

### Основные запросы

Основные запросы к сервису позволяют выполнять поиск по различным типам данных. Все запросы требуют указания ключа доступа (`key`). Параметр `regionID` (ID региона) является необязательным — если он не указан, поиск будет выполнен по всем регионам. Список регионов можно получить с помощью справочного запроса (см. раздел **Справочные запросы**).

#### 1. Простой текстовый поиск

```
https://service.api-assist.com/parser/fssp_api/search_simple?key=ВАШ_КЛЮЧ_ДОСТУПА&name=ТЕКСТ_ДЛЯ_ПОИСКА
```

**Параметры:**
- **name** - текст для поиска (обязательный).
- **regionID** - ID региона поиска (необязательный).

#### 2. Поиск по данным физического лица

```
https://service.api-assist.com/parser/fssp_api/search_fiz?key=ВАШ_КЛЮЧ_ДОСТУПА&lastName=ФАМИЛИЯ&firstName=ИМЯ&dob=ДАТА_РОЖДЕНИЯ
```

**Параметры:**
- **lastName** - фамилия (обязательный).
- **firstName** - имя (обязательный).
- **dob** - дата рождения, формат `dd.mm.YYYY` или `YYYY-mm-dd` (обязательный).
- **patronymic** - отчество (необязательный).
- **regionID** - ID региона поиска (необязательный).

#### 3. Поиск по наименованию юридического лица

```
https://service.api-assist.com/parser/fssp_api/search_ur_by_name?key=ВАШ_КЛЮЧ_ДОСТУПА&name=ТЕКСТ_ДЛЯ_ПОИСКА
```

**Параметры:**
- **name** - наименование (обязательный).
- **address** - адрес (необязательный).
- **regionID** - ID региона поиска (необязательный).

#### 4. Поиск по ИНН юридического лица

```
https://service.api-assist.com/parser/fssp_api/search_ur_by_inn?key=ВАШ_КЛЮЧ_ДОСТУПА&inn=ИНН
```

**Параметры:**
- **inn** - ИНН (обязательный).
- **address** - адрес (необязательный).
- **regionID** - ID региона поиска (необязательный).

#### 5. Поиск по номеру исполнительного производства

```
https://service.api-assist.com/parser/fssp_api/search_ip?key=ВАШ_КЛЮЧ_ДОСТУПА&ipNumber=НОМЕР_ИСПОЛНИТЕЛЬНОГО_ПРОИЗВОДСТВА
```

**Параметры:**
- **ipNumber** - номер исполнительного производства (обязательный).
- **regionID** - ID региона поиска (необязательный).

#### 6. Поиск по номеру исполнительного документа

```
https://service.api-assist.com/parser/fssp_api/search_id?key=ВАШ_КЛЮЧ_ДОСТУПА&idNumber=НОМЕР_ДОКУМЕНТА&idType=ID_ТИПА_ДОКУМЕНТА
```

**Параметры:**
- **idNumber** - номер исполнительного документа (обязательный).
- **idType** - ID типа исполнительного документа (обязательный). Список типов документов можно получить с помощью справочного запроса (см. раздел **Справочные запросы**).
- **idIssuer** - наименование органа, выдавшего исполнительный документ (необязательный).
- **regionID** - ID региона поиска (необязательный).

---

### Результат основного запроса

В теле ответа на запрос содержится JSON следующего формата:

```json-toggle
{
  "done": 1, // флаг успешности выполнения запроса, 1/0
  "url": "ссылка на поиск, с которого была взята информация",
  "total_rows_count": "общее число найденных записей",
  "total_pages_count": "общее число страниц в результатах поиска",
  "result": [ // массив результатов поиска, каждый элемент - исполнительное производств
    {
      "debtor_name": "фио или наименование должника",
      "debtor_address": "адрес должника",
      "debtor_dob": "дата рождения (для физ лиц, YYYY-mm-dd)",
      "process_title": "исполнительное производство",
      "process_date": "дата возбуждения исполнительного производства",
      "process_total": "сводное исполнительное производство",
      "document_title": "полные реквизиты исполнительного документа",
      "document_organization": "орган, выдавший исполнительный документ",
      "document_claimer_inn": "ИНН взыскателя-организации",
      "document_type": "тип документа",
      "document_date": "дата принятия",
      "document_num": "номер документа",
      "stop_date": "дата окончания или прекращения исполнительного производства (YYYY-mm-dd)",
      "stop_reason": "причина окончания или прекращения исполнительного производства",
      "subjects": [
        {
          "title": "название",
          "sum": "сумма задолженности"
        }
      ],
      "department_title": "наименование отдела судебных приставов",
      "department_address": "адрес отдела судебных приставов",
      "officer_name": "судебный пристав-исполнитель, ФИО",
      "officer_phones": ["контактные телефоны пристава"],
      "payment_available": 1 // доступна ли кнопка "Оплатить", 1/0
    }
  ]
}
```

---

### Справочные запросы

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

#### 1. Получение списка регионов

```
https://service.api-assist.com/parser/fssp_api/get_regions?key=ВАШ_КЛЮЧ_ДОСТУПА
```

Сокращенный пример ответа:

```json
{
  "1": "Республика Адыгея",
  "2": "Республика Башкортостан",
  "3": "Республика Бурятия",
}
```

#### 2. Получение типов исполнительных документов

```
https://service.api-assist.com/parser/fssp_api/get_id_types?key=ВАШ_КЛЮЧ_ДОСТУПА
```

Сокращенный пример ответа:

```json
{
  "1": "Исполнительный лист",
  "2": "Нотариально удостоверенное соглашение об уплате алиментов",
  "3": "Акт по делу об административном правонарушении",
}
```

---

### Интерпретация ответа и обработка ошибок

**Общие рекомендации:**
- Если поле `done` заполнено и `done = 1` — перед вами успешный ответ, с которым можно работать. Только такие запросы учитываются в статистике и расходуют оплаченный лимит.
- Иначе, если поле `error` заполнено — запрос требует вашего внимания. Текст ошибки рекомендуется сохранить или отправить для дальнейшего анализа.
- Иначе, если поле `error` не заполнено — это ошибка, связанная со стабильностью источника. В таком случае мы рекомендуем игнорировать ответ и повторить запрос.

В данном разделе описаны возможные коды ответов сервиса и их значения. Каждый код ответа сопровождается пояснением и примером JSON-ответа.

#### 1. Код ответа - 200

- Поле `success = 1` - удалось получить информацию от источника. Такие и только такие запросы можно запускать в дальнейшую обработку. Пример ответа см. в разделе **Результат основного запроса**.
- Поле `success = 0` - не удалось получить информацию от источника. Запрос не будет учтен в статистике. Необходимо повторить запрос.

#### 2. Код ответа - 403

Выдается сервисом в случае невозможности обработки запроса из-за ограничения доступа: закончилась подписка, превышен лимит и так далее. Причины ошибок отражены в поле `error` ответа. Ниже приведен список возможных ошибок с их описанием и кодами:

- **Invalid access key**  
  `error_code = 40301`  
  Указанный ключ доступа недействителен или отсутствует.

- **The subscription period has expired**  
  `error_code = 40302`  
  Доступ к сервису истек, требуется продление.

- **Invalid IP**  
  `error_code = 40303`  
  Запрос выполнен с IP-адреса, который не разрешён для доступа.

- **Day limit of requests exceeded**  
  `error_code = 40304`  
  Достигнут оплаченный лимит запросов на день.

- **Month limit of requests exceeded**  
  `error_code = 40305`  
  Достигнут оплаченный лимит запросов на месяц.

**Пример ответа:**
```json
{
  "error": "Invalid access key",
  "error_code": 40301
}
```

#### 3. Код ответа - 400

Выдается сервисом в случае невозможности обработки запроса из-за ошибки валидации запроса, неверного или отсутствующего значения какого-либо поля. Поле `error_code` всегда равно `40001`, подробности доступны в поле `error`.

**Пример ответа:**
```json
{
  "error": "Missing firstName in input params",
  "error_code": 40001
}
```