## Документация API api-assist.com проверка штрафов ГИБДД

Сервис поддерживает три типа запросов:

1. **Получение штрафов (российские номера)**
2. **Получение штрафов (иностранные номера)**
3. **Получение фотографий по штрафу**

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

---

### 1. Получение штрафов (российские номера)

```
https://service.api-assist.com/parser/fines_api/fines
```

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

- **regNumber** — государственный регистрационный знак (ГРЗ) транспортного средства
- **sts** — номер свидетельства о регистрации транспортного средства (СТС)

**Пример запроса по проверке штрафов:**

```
https://service.api-assist.com/parser/fines_api/fines?key=ВАШ_КЛЮЧ_ДОСТУПА&regNumber=Р276АС777&sts=5058794047
```

**Пример ответа:**

```json
{
  "success": 1, // флаг успешного выполнения запроса
  "fines": [
    {
      "enable_discount": true, // актуальна ли скидка при оплате
      "date_discount": "2018-03-16 23:59:59", // дата, до которой актуальна скидка
      "date_decision": "2018-02-24 17:00:00", // дата и время нарушения
      "koap_code": "12.9ч.2", // статья КоАП, по которой вынесено постановление
      "koap_text": "ПРЕВЫШЕНИЕ УСТАНОВЛЕННОЙ СКОРОСТИ ДВИЖЕНИЯ ТРАНСПОРТНОГО СРЕДСТВА НА ВЕЛИЧИНУ БОЛЕЕ 20, НО НЕ БОЛЕЕ 40 КМ/Ч", // текст статьи
      "num_post": "18810177180224390760", // номер постановления
      "kbk": "18811630020016000140", // КБК
      "sum": "500", // полная сумма штрафа, без скидки
      "division_name": "Управление ГИБДД ГУ МВД России по г. Москве", // наименование подразделения, вынесшего постановление
      "division_address": "г. Москва, ул. Садовая-Самотечная, д. 1", // адрес подразделения, вынесшего постановление
      "division_id": 1145000, // идентификатор подразделения, вынесшего постановление
      "date_post": "2018-02-24", // дата вынесения постановления
      "date_ssp": null, // дата передачи постановления приставам
      "photo_available": true, // доступно ли изображение
      "photo_token": "1c11d015f1981551371781b01471a618d15f14d1ec1f013a" // токен для получения изображения, действует в течении минуты
    }
  ]
}
```

### 2. Получение штрафов (иностранные номера)

```
https://service.api-assist.com/parser/fines_api/foreign
```

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

- **regNumber** — государственный регистрационный знак (ГРЗ) транспортного средства с иностранным номером (используются латинские буквы)

**Особенности:**
- Для иностранных номеров НЕ требуется параметр `sts`
- Номер указывается латинскими буквами (например, A123BC77)

**Пример запроса по проверке штрафов для иностранного номера:**

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

**Пример ответа:**

Формат ответа аналогичен запросу для российских номеров (см. раздел 1).

### 3. Получение фотографии по штрафу

```
https://service.api-assist.com/parser/fines_api/photo
```

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

- **photoToken** — токен, полученный в ответе на запрос штрафов (действует в течение минуты)
- **regNumber** — государственный регистрационный знак (ГРЗ) транспортного средства
- **numPost** — номер постановления
- **divisionId** — идентификатор подразделения, вынесшего постановление

**Пример запроса на получение фотографии:**

```
https://service.api-assist.com/parser/fines_api/photo?key=ВАШ_КЛЮЧ_ДОСТУПА&photoToken=ТОКЕН_ИЗ_ЗАПРОСА_СО_ШТРАФОМ&regNumber=Р276АС777&numPost=18810177180301014119&divisionId=1145000
```

**Пример ответа:**

```json
{
  "success": 1, // флаг успешного выполнения запроса
  "image_base64": "/9j/4AAQSkZJRgABAQAAAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQB//2Q==", // base64 encoded изображение
  "additional_images_base64": [ // дополнительные изображения
    "/9j/4AAQSkZJRgABAQAAAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQB//2Q==" // base64 encoded изображение
  ]
}
```

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

**Общие рекомендации:**
- Если поле `success` заполнено и `success = 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`.

**Возможные ошибки валидации:**

- `Empty regNumber` — не указан обязательный параметр `regNumber`
- `Empty sts` — не указан обязательный параметр `sts` (только для российских номеров)
- `Invalid regNumber format` — неверный формат регистрационного номера (только для российских номеров)
- `Empty numPost` — не указан параметр `numPost` при запросе фотографии
- `Empty divisionId` — не указан параметр `divisionId` при запросе фотографии
- `Empty photoToken` — не указан параметр `photoToken` при запросе фотографии

**Пример ответа:**
```json
{
  "error": "Empty regNumber",
  "error_code": 40001
}
```