## Документация API api-assist.com ras.arbitr.ru (Судебные акты)

Сервис предоставляет доступ к поиску судебных актов арбитражных судов и скачиванию PDF документов.

Все запросы требуют указания ключа доступа (`key`).

---

### 1. Поиск документов

Для поиска судебных актов используйте следующий запрос:

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

**Параметры поиска:**

- **caseNumber** — номер дела (например, `15АП-20855/2018`)
- **inn** — участник дела, ИНН, ФИО участника или название организации
- **text** — текст документа (в том числе можно указывать VIN и гос. номера автомобилей)
- **court** — наименование суда (точно в той форме, в какой оно перечислено в справочнике, например `АС Московского округа`, `15 арбитражный апелляционный суд`, `Суд по интеллектуальным правам`).
- **dateFrom** — дата, с которой начинается поиск (формат `YYYY-MM-DD`)
- **dateTo** — дата, по которую ведется поиск (формат `YYYY-MM-DD`)
- **page** — номер страницы в выдаче (по умолчанию 1)
- **disputeType** — вид спора (регистронезависимо). Допустимые значения:
  - `дисциплинарные споры`
  - `о несостоятельности (банкротстве) организаций и граждан`
  - `о признании и приведении в исполнение решений иностранных судов и иностранных арбитражных решений`
  - `об административных правонарушениях`
  - `об оспаривании решений трет. судов и о выдаче исп. листов на принудительное исполнение решений трет. судов`
  - `об установлении фактов, имеющих юридическое значение`
  - `экономические споры по административным правоотношениям`
  - `экономические споры по гражданским правоотношениям`
- **disputeCategory** — номер категории спора (например, `7.1`, `26.2`, `20.2.6.1`). Значение должно соответствовать одному из номеров категорий, используемых на источнике.

**Обязательно должен быть указан хотя бы один параметр:** `caseNumber`, `inn`, `text`, `court`, `disputeType` или `disputeCategory`.

**Примеры поисковых запросов:**

Поиск документов по номеру дела:
```
https://service.api-assist.com/parser/ras_arbitr_api/search?key=ВАШ_КЛЮЧ_ДОСТУПА&caseNumber=15АП-20855/2018
```

Поиск документов по ИНН, ФИО участника или названию организации:
```
https://service.api-assist.com/parser/ras_arbitr_api/search?key=ВАШ_КЛЮЧ_ДОСТУПА&inn=Газпром
```

Поиск документов по тексту (включая VIN автомобилей):
```
https://service.api-assist.com/parser/ras_arbitr_api/search?key=ВАШ_КЛЮЧ_ДОСТУПА&text=SALLMAMH4CA388911
```

Поиск документов по тексту с указанием периода публикации:
```
https://service.api-assist.com/parser/ras_arbitr_api/search?key=ВАШ_КЛЮЧ_ДОСТУПА&text=SALLMAMH4CA388911&dateFrom=2018-01-01&dateTo=2019-01-01
```

Поиск документов по виду спора и категории спора:
```
https://service.api-assist.com/parser/ras_arbitr_api/search?key=ВАШ_КЛЮЧ_ДОСТУПА&disputeType=дисциплинарные споры&disputeCategory=7.1
```

**Пример ответа на поисковый запрос:**

Ответ на поисковый запрос возвращается в формате JSON. Пример ответа:

```json-toggle
{
  "done": 1, // запрос выполнен успешно
  "count": 1, // число найденных документов
  "pages": 1, // общее число страниц, доступных для загрузки
  "page": 1, // текущая выданная страница
  "items": [ // массив с документами
    {
      "CaseId": "c9babcc7-e797-429c-b6e4-6287b5d7334a", // уникальный идентификатор дела
      "CaseUrl": "https://kad.arbitr.ru/Card/c9babcc7-e797-429c-b6e4-6287b5d7334a", // ссылка на дело на kad.arbitr.ru
      "RegistrationDate": "21.12.2018", // дата регистрации документа
      "InstanceNumber": "15АП-20855/2018", // номер инстанции
      "CaseNumber": "А53-30848/2015", // номер дела
      "FileName": "А53-30848-2015__20181221.pdf", // название файла
      "FileUrl": "https://kad.arbitr.ru/Document/Pdf/c9babcc7-e797-429c-b6e4-6287b5d7334a/b6e2f927-00ea-4dee-8fca-532a805c7362/А53-30848-2015__20181221.pdf", // ссылка на файл
      "InstanceLevel": 2, // уровень инстанции
      "Court": "15 арбитражный апелляционный суд", // название суда
      "Type": "Постановление апелляционной инстанции", // тип документа
      "ContentTypes": [ // уточненные типы документа
        "Оставить без изменения определение первой инстанции, а жалобу - без удовлетворения (ст.272 АПК)"
      ]
    }
  ]
}
```

---

### 2. Скачивание PDF документов

Для скачивания PDF файлов судебных документов используйте следующий запрос:

```
https://service.api-assist.com/parser/ras_arbitr_api/pdf_download?key=ВАШ_КЛЮЧ_ДОСТУПА&url=URL_PDF_ФАЙЛА
```

**Параметры:**

- **url** — полный URL PDF документа с сайта kad.arbitr.ru (обязательный)

**Пример запроса:**

```
https://service.api-assist.com/parser/ras_arbitr_api/pdf_download?key=ВАШ_КЛЮЧ_ДОСТУПА&url=https://kad.arbitr.ru/Document/Pdf/c9babcc7-e797-429c-b6e4-6287b5d7334a/b6e2f927-00ea-4dee-8fca-532a805c7362/А53-30848-2015__20181221.pdf
```

**Ответ при успешной загрузке PDF:**

При успешном выполнении запроса в теле ответа возвращается JSON с base64-кодированным содержимым PDF файла:

```json
{
  "done": 1,
  "pdfContent": "JVBERi0xLjQKJeLjz9MKMy..." // содержимое PDF в формате base64
}
```

**Пример использования pdfContent:**

Для получения PDF файла необходимо декодировать поле `pdfContent` из base64:

```php
$response = json_decode($apiResponse, true);
if ($response['done'] == 1 && !empty($response['pdfContent'])) {
    $pdfBinary = base64_decode($response['pdfContent']);
    file_put_contents('document.pdf', $pdfBinary);
}
```

```python
import json
import base64

response = json.loads(api_response)
if response['done'] == 1 and response.get('pdfContent'):
    pdf_binary = base64.b64decode(response['pdfContent'])
    with open('document.pdf', 'wb') as f:
        f.write(pdf_binary)
```

**Привер ответа, когда PDF не найден:**

```json
{
  "done": 1,
  "pdfContent": null
}
```

---

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

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

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

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

- Поле `done = 1` - удалось получить информацию от источника. Такие и только такие запросы можно запускать в дальнейшую обработку. Примеры ответов см. выше.
- Поле `done = 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": "Empty request. Please provide caseNumber, inn, text, court, disputeType or disputeCategory",
  "error_code": "40001"
}
```

Невалидный URL PDF:
```json
{
  "error": "Invalid pdf url",
  "error_code": "40001"
}
```

Невалидный вид спора:
```json
{
  "error": "Invalid disputeType. Allowed values: дисциплинарные споры, о несостоятельности (банкротстве) организаций и граждан, ...",
  "error_code": "40001"
}
```

Невалидная категория спора:
```json
{
  "error": "Invalid disputeCategory",
  "error_code": "40001"
}
```

Невалидное наименование суда:
```json
{
  "error": "Invalid court name",
  "error_code": "40001"
}
```