# Работа с GPS-Мониторингом

Открытое API GPS-устройств позволяет зарегистрировать GPS-оборудование в нашей системе, сохранять и просматривать данные о местоположении на карте АТИ Водителя.

#### Работа с GPS-устройствами

Для начала работы c API нужно зарегистрировать GPS-устройство в системе ATI.SU.

1. [Зарегистрировать новое устройство или обновить существующее](#post-v1-driver-public-gps-device)
2. [Удалить устройство](#delete-v1-driver-public-gps-device)
3. [Получить устройство по device_id](#get-v1-driver-public-gps-device_info)
4. [Получить все мои устройства](#get-v1-driver-public-gps-all_devices)

#### Отправка координат

Когда заказ находится в исполнении, появляется возможность сохранять координаты с GPS-устройства в системе ATI.SU.

- [Сохранить GPS-координаты](#post-v1-driver-public-gps-coordinates)

#### Получение истории заказа

По мере выполнения заказа можно следить за передвижением водителя через карту, прикрепленную к заказу на сайте ATI.SU. Но также можно запросить эти данные методами, описанными в разделе АТИ Водитель. Данные методы возвращают информацию по всем GPS-устройствам, участвующим в сделке, включая приложение «АТИ Водитель».

1. [Получение информации о пройденном маршруте АТИ Водителя](#get-v1.2-orders-carrier-map_route-by_deal)
2. [Получение истории](#get-v1.2-orders-carrier-map-history)

## Методы для работы с Заказами с участием АТИ Водителя

#### Регистрация и обновление GPS-устройства

Регистрирует новое устройство в системе. Информация об этом устройстве будет отображаться на карте заказа, по которому устройство вело записи.

<a id="post-v1-driver-public-gps-device"></a>

Добавить или обновить gps устройство

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

```bash
curl 'https://api.ati.su/v1/driver/public/gps/device' \
  -X 'POST' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "Моё gps устройство",
  "description": "Лежит в машине Х000ХY178",
  "device_id": "2fb965f2-85e9-4213-90e7-f396e47219e7"
}'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/orders/gps-open-api.openapi.json)

**Описание полей запроса**
- `name` — Название для GPS устройства
- `description` — Описание вашего устройства
- `device_id` — Идентификатор устройства. Если не задан, генерируется самостоятельно

**Пример ответа (4XX)**

```json
{
  "error_code": "validation_error",
  "reason": "Ошибка валидации полей phone и device_id"
}
```

**Описание полей ответа**
- `error_code` — Код ошибки
- `reason` — Описание ошибки для разработчиков


#### Удаление GPS-устройства

Удаляет ранее зарегистрированное устройство. Это устройство больше не будет возвращаться в список ваших устройств. Все существующие записи, сделанные удаленным устройством, сохранятся.

<a id="delete-v1-driver-public-gps-device"></a>

Удалить gps устройство

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

```bash
curl 'https://api.ati.su/v1/driver/public/gps/device?deviceId=string' \
  -X 'DELETE' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/orders/gps-open-api.openapi.json)

**Пример ответа (4XX)**

```json
{
  "error_code": "validation_error",
  "reason": "Ошибка валидации полей phone и device_id"
}
```

**Описание полей ответа**
- `error_code` — Код ошибки
- `reason` — Описание ошибки для разработчиков


#### Получение устройства по device_id

Получить устройство по device_id

<a id="get-v1-driver-public-gps-device_info"></a>

Получить gps устройство по device_id

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

```bash
curl 'https://api.ati.su/v1/driver/public/gps/device_info?deviceId=string' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/orders/gps-open-api.openapi.json)

**Пример ответа (404)**

```json
{
  "error_code": "validation_error",
  "reason": "Ошибка валидации полей phone и device_id"
}
```

**Описание полей ответа**
- `error_code` — Код ошибки
- `reason` — Описание ошибки для разработчиков


#### Получение всех моих устройств

Получить все мои устройства. Метод для получения всех устройств, принадлежащих вашему аккаунту.

<a id="get-v1-driver-public-gps-all_devices"></a>

Получить все gps устройства контакта

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

```bash
curl 'https://api.ati.su/v1/driver/public/gps/all_devices' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/orders/gps-open-api.openapi.json)

**Пример ответа (4XX)**

```json
{
  "error_code": "validation_error",
  "reason": "Ошибка валидации полей phone и device_id"
}
```

**Описание полей ответа**
- `error_code` — Код ошибки
- `reason` — Описание ошибки для разработчиков


#### Сохранение GPS-координат устройства

Сохраняет GPS-координаты устройства. Во входящих параметрах необходимо указать, по какому Заказу ведутся записи. При этом указанная сделка должна находиться в статусе «В исполнении».

<a id="post-v1-driver-public-gps-coordinates"></a>

Записать координаты

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

```bash
curl 'https://api.ati.su/v1/driver/public/gps/coordinates' \
  -X 'POST' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "deal_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "device_id": "string",
  "coordinates": [
    {
      "lon": 0.5,
      "lat": 0.5,
      "location_date": "1970-01-01T00:00:00.000Z"
    }
  ]
}'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/orders/gps-open-api.openapi.json)

**Пример ответа (4XX)**

```json
{
  "error_code": "validation_error",
  "reason": "Ошибка валидации полей phone и device_id"
}
```

**Описание полей ответа**
- `error_code` — Код ошибки
- `reason` — Описание ошибки для разработчиков


### Получение информации о пройденном маршруте и истории событий

#### Получение информации о пройденном маршруте

Возвращает информацию о маршруте, пройденном водителем с использованием приложения, датчиков Wialon или GPS-устройств, добавленных с помощью API, а также о начальной, конечной и промежуточных точках маршрута. Ответ метода можно использовать, например, для отображения маршрута на карте.

<a id="get-v1.2-orders-carrier-map_route-by_deal"></a>

Получение информации о пройденном маршруте АТИ Водителя

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

```bash
curl 'https://api.ati.su/v1.2/orders/carrier/map_route/by_deal?deal_id=3fa85f64-5717-4562-b3fc-2c963f66afa6&south_west_lat=0.5&south_west_lng=0.5&north_east_lat=0.5&north_east_lng=0.5&zoom=0.5' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/orders/gps-open-api.openapi.json)

**Пример ответа (200)**

```json
[
  {
    "goals": [
      {
        "longitude": 0.5,
        "latitude": 0.5,
        "events": [
          {
            "type": {},
            "tag": "string",
            "date": "1970-01-01T00:00:00.000Z",
            "date_to": "1970-01-01T00:00:00.000Z",
            "time": "string",
            "time_to": "string",
            "location_name": {
              "country": "string",
              "region": "string",
              "city": "string",
              "address": "string"
            }
          }
        ],
        "ordinal_id": 0,
        "trace": false
      }
    ],
    "traces": [
      {
        "car": {
          "driver_phone": "string",
          "car_status": {}
        },
        "first_action": "1970-01-01T00:00:00.000Z",
        "last_action": "1970-01-01T00:00:00.000Z",
        "points": [
          {
            "longitude": 0.5,
            "latitude": 0.5,
            "events": [
              {
                "type": {},
                "tag": "string",
                "date": "1970-01-01T00:00:00.000Z",
                "date_to": "1970-01-01T00:00:00.000Z",
                "time": "string",
                "time_to": "string",
                "location_name": {
                  "country": "string",
                  "region": "string",
                  "city": "string",
                  "address": "string"
                }
              }
            ],
            "location_date": "1970-01-01T00:00:00.000Z",
            "is_fake": false,
            "is_disabled": false,
            "is_no_data": false,
            "is_power_saving": false,
            "is_empty_run": false,
            "is_parking": false
          }
        ]
      }
    ]
  }
]
```

**Описание полей ответа**
- `[].goals` — Точки загрузки/разгрузки
- `[].goals[].longitude` — Долгота
- `[].goals[].latitude` — Широта
- `[].goals[].events` — События
- `[].goals[].events[].type` — Тип события * `0` — Значение по умолчанию * `1` — Метаинформация об устройстве. Включает в себя события выключения GPS, подмены GPS координат, выключения телефона. * `2` — Информация о статусе заказа (статусы выбираются водителем в приложении)
- `[].goals[].events[].tag` — Тэг произошедшего события
- `[].goals[].events[].date` — Дата начала
- `[].goals[].events[].date_to` — Дата окончания
- `[].goals[].events[].time` — Время начала
- `[].goals[].events[].time_to` — Время окончания
- `[].goals[].events[].location_name` — Информация о местоположении
- `[].goals[].events[].location_name.country` — Страна
- `[].goals[].events[].location_name.region` — Регион
- `[].goals[].events[].location_name.city` — Город
- `[].goals[].events[].location_name.address` — Адрес
- `[].goals[].ordinal_id` — Номер по порядку
- `[].goals[].trace` — Нужно ли прокладывать маршрут для этой точки
- `[].traces` — Точки траектории движения водителя
- `[].traces[].car` — Транспортное средство
- `[].traces[].car.driver_phone` — Номер телефона водителя
- `[].traces[].car.car_status` — Тип события * `0` — Без происшествий * `1` — GPS был выключен * `2` — Попытка подделки GPS * `3` — Не было данных * `4` — Режим энергосбережения * `5` — Стоянка
- `[].traces[].first_action` — Время начала действия
- `[].traces[].last_action` — Время окончания действия
- `[].traces[].points` — Точки маршрута
- `[].traces[].points[].longitude` — Долгота
- `[].traces[].points[].latitude` — Широта
- `[].traces[].points[].events` — События
- `[].traces[].points[].events[].type` — Тип события * `0` — Значение по умолчанию * `1` — Метаинформация об устройстве. Включает в себя события выключения GPS, подмены GPS координат, выключения телефона. * `2` — Информация о статусе заказа (статусы выбираются водителем в приложении)
- `[].traces[].points[].events[].tag` — Тэг произошедшего события
- `[].traces[].points[].events[].date` — Дата начала
- `[].traces[].points[].events[].date_to` — Дата окончания
- `[].traces[].points[].events[].time` — Время начала
- `[].traces[].points[].events[].time_to` — Время окончания
- `[].traces[].points[].events[].location_name` — Информация о местоположении
- `[].traces[].points[].events[].location_name.country` — Страна
- `[].traces[].points[].events[].location_name.region` — Регион
- `[].traces[].points[].events[].location_name.city` — Город
- `[].traces[].points[].events[].location_name.address` — Адрес
- `[].traces[].points[].location_date` — Время местоположения
- `[].traces[].points[].is_fake` — Флаг поддельного сигнала GPS
- `[].traces[].points[].is_disabled` — Фдаг выключенности GPS
- `[].traces[].points[].is_no_data` — Флаг наличия данных
- `[].traces[].points[].is_power_saving` — Флаг включенности режима энергосбережения
- `[].traces[].points[].is_empty_run` — Флаг холостого хода
- `[].traces[].points[].is_parking` — Стоянка

**Пример ответа (4XX)**

```json
{
  "reason": "string",
  "error": "string"
}
```

**Описание полей ответа**
- `reason` — Причина ошибки
- `error` — Ключ ошибки


#### Получение истории

Список событий, произошедших в пути следования водителя. Например: поломка, ДТП, отсутствие данных и прочее.

<a id="get-v1.2-orders-carrier-map-history"></a>

Получение истории

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

```bash
curl 'https://api.ati.su/v1.2/orders/carrier/map/history?deal_id=3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/orders/gps-open-api.openapi.json)

**Пример ответа (200)**

```json
[
  {
    "events": [
      {
        "date": "1970-01-01T00:00:00.000Z",
        "event": {
          "type": {},
          "tag": "string",
          "date": "1970-01-01T00:00:00.000Z",
          "date_to": "1970-01-01T00:00:00.000Z",
          "time": "string",
          "time_to": "string",
          "location_name": {
            "country": "string",
            "region": "string",
            "city": "string",
            "address": "string"
          }
        },
        "longitude": 0.5,
        "latitude": 0.5,
        "params": [
          "string"
        ]
      }
    ]
  }
]
```

**Описание полей ответа**
- `[].events` — События в пути
- `[].events[].date` — Время события
- `[].events[].event` — Событие
- `[].events[].event.type` — Тип события * `0` — Значение по умолчанию * `1` — Метаинформация об устройстве. Включает в себя события выключения GPS, подмены GPS координат, выключения телефона. * `2` — Информация о статусе заказа (статусы выбираются водителем в приложении)
- `[].events[].event.tag` — Тэг произошедшего события
- `[].events[].event.date` — Дата начала
- `[].events[].event.date_to` — Дата окончания
- `[].events[].event.time` — Время начала
- `[].events[].event.time_to` — Время окончания
- `[].events[].event.location_name` — Информация о местоположении
- `[].events[].event.location_name.country` — Страна
- `[].events[].event.location_name.region` — Регион
- `[].events[].event.location_name.city` — Город
- `[].events[].event.location_name.address` — Адрес
- `[].events[].longitude` — Долгота
- `[].events[].latitude` — Широта

**Пример ответа (4XX)**

```json
{
  "reason": "string",
  "error": "string"
}
```

**Описание полей ответа**
- `reason` — Причина ошибки
- `error` — Ключ ошибки