Version 11 (modified by tolix, 3 years ago) (diff)
--

Вывоз ТБО: API взаимодействия с планшетом

API использует сообщения в JSON формате, передаваемые по HTTP по принципу запрос-ответ. Инициатором обмена всегда выступает планшет.

Необходимым условием является наличие в сообщениях следующих HTTP заголовков:

X-Signature: reserved
Content-Type: text/x-json

HTTP адрес всех веб-сервисов (URL), используемых в данном компоненте, формируется из базовой части http://<server_name>/components/communa/ и имени конкретного сервиса.

Все параметры, содержащие время, используют часовой пояс оператора-владельца используемых в запросе объектов (спецавтомобилей, контейнеров и т.д.), т.е. местное время.

Типичный сценарий работы планшета выглядит следующим образом:

Планшет запрашивает список сотрудников для простой аутентификации водителя/экспедитора на стороне планшета (get_personnel). В качестве пин-код выступает табельный номер сотрудника
Планшет запрашивает список маршрутов и предлагает на выбор водителю (get_routes)
По завершению выбора маршрута планшет отправляет на сервер событие "На маршруте" с указанием маршрута, водителя и грузчика (экспедитора) (register_event ROUTE_START)
Водитель приступает к циклу уборки - планшет отправляет событие "На смене". (register_event ON_SHIFT) Цикл уборки состоит из:
- получение траектории до следующей платформы (get_directions)
- по приезду и уборке платформы планшет запрашивает у сервера количество сработал датчика поднятий стрелы (get_lifts_count)
- отправляет на сервер событие "Погрузка площадки" с указанием количества подгруженных контейнеров и причины непогрузки оставшихся (если имеются) (register_event PLATFORM_LOADED)
При заполнении бункера спецавтомобиля он едет выгружаться на полигон - планшет отправляет событие "Еду на полигон" (register_event ...), что дает ему возможность сойти с маршрута. Аналогично работает событие "На техобслуживании"
По завершению маршрута планшет отправляет событие "Еду в гараж"

Запрос списка водителей/экспедиторов для аутентификации

Endpoint: http://<server_name>/components/communa/get_personnel

Запрос:

{
    "device_id":"a40d38a959f1ca65"
}

Ответ,

{
   "personnel":[
      {
         "personnel_number":444,
         "first_name":"Иван",
         "last_name":"mts",
         "middle_name":"",
         "id":1012651
      },
      {
         "personnel_number":777,
         "first_name":"Василий",
         "last_name":"mts1",
         "middle_name":"",
         "id":1012652
      }
   ],
   "success":true
}

Запрос списка маршрутов полный (с подробной информацией о платформах)

Endpoint: http://<server_name>/components/communa/get_routes

Запрос:

{
    "device_id":"49aa570dc04344a6"
}

Ответ:

{
   "routes":[
      {
         "platforms":[
            {
               "estimated_fill":1.0,
               "volume":1.100,
               "address":"АТБ-Містечко",
               "lat":50.2107736547029,
               "lng":30.3174322843552,
               "id":1022549,
               "quantity":1
            },
            {
               "estimated_fill":1.0,
               "volume":1.100,
               "address":"пр.Лесі Українки, 15 ",
               "lat":50.1974241245373,
               "lng":30.2944350242615,
               "id":1022542,
               "quantity":1
            },
            {
               "estimated_fill":1.0,
               "volume":1.100,
               "address":"Столичка",
               "lat":50.216073975587,
               "lng":30.3178024291992,
               "id":1022543,
               "quantity":3
            },
            {
               "estimated_fill":1.0,
               "volume":1.100,
               "address":"Солнечная",
               "lat":50.1883300230983,
               "lng":30.2941560745239,
               "id":1022544,
               "quantity":1
            },
            {
               "estimated_fill":1.0,
               "volume":1.100,
               "address":"вул.Володимирська,13",
               "lat":50.1747131083508,
               "lng":30.3193259239197,
               "id":1022545,
               "quantity":1
            },
            {
               "estimated_fill":1.0,
               "volume":1.100,
               "address":"вул.Володимирька, 28 (Корунд)",
               "lat":50.1733834992561,
               "lng":30.3227108716965,
               "id":1022546,
               "quantity":1
            },
            {
               "estimated_fill":1.0,
               "volume":1.100,
               "address":"Фуршет",
               "lat":50.1795055782639,
               "lng":30.3133499622345,
               "id":1022547,
               "quantity":1
            },
            {
               "estimated_fill":1.0,
               "volume":1.100,
               "address":"вул.Набережна",
               "lat":50.1800174337311,
               "lng":30.3084254264832,
               "id":1022548,
               "quantity":1
            },
            {
               "estimated_fill":1.0,
               "volume":1.100,
               "address":"Військове .Містечко",
               "lat":50.2120369970609,
               "lng":30.3167670965195,
               "id":1022550,
               "quantity":1
            },
            {
               "estimated_fill":1.0,
               "volume":1.100,
               "address":"вул.Грушевського,25",
               "lat":50.180299123662,
               "lng":30.3108340501785,
               "id":1022551,
               "quantity":1
            },
            {
               "estimated_fill":1.0,
               "volume":1.100,
               "address":"Іванковичі",
               "lat":50.2786446089967,
               "lng":30.4251337051392,
               "id":1022552,
               "quantity":2
            }
         ],
         "num":"01.05 - Смаколики",
         "id":1022554,
         "itinerary":""
      }
   ],
   "success":true
}

Запрос списка маршрутов без подробной информации о маршруте

Endpoint: http://<server_name>/components/communa/get_routes_v2

Запрос:

{
    "device_id":"49aa570dc04344a6"
}

Ответ:

{
  "routes": [
    {
      "platforms": 41,
      "num": "20211019T0330-AA7044OO",
      "id": 1033710,
      "itinerary": null,
      "wastebins": 84
    },
    {
      "platforms": 167,
      "num": "20211019T0400-AA7041OO",
      "id": 1033722,
      "itinerary": null,
      "wastebins": 248
    },
    {
      "platforms": 55,
      "num": "20211019T0400-AA9180XE",
      "id": 1033723,
      "itinerary": null,
      "wastebins": 111
    },
    {
      "platforms": 5,
      "num": "20211019T0400-AA9183XE",
      "id": 1033721,
      "itinerary": null,
      "wastebins": 10
    },
    {
      "platforms": 86,
      "num": "20211019T0405-AA5897BP",
      "id": 1033711,
      "itinerary": null,
      "wastebins": 136
    },
    {
      "platforms": 77,
      "num": "20211020T0400-AA7041OO",
      "id": 1033727,
      "itinerary": null,
      "wastebins": 131
    },
    {
      "platforms": 1,
      "num": "20211020T0400-AA9183XE",
      "id": 1033729,
      "itinerary": null,
      "wastebins": 2
    },
    {
      "platforms": 108,
      "num": "20211020T0600-AA5895BP",
      "id": 1033720,
      "itinerary": null,
      "wastebins": 222
    },
    {
      "platforms": 38,
      "num": "20211020T0800-AA7044OO",
      "id": 1033724,
      "itinerary": null,
      "wastebins": 78
    },
    {
      "platforms": 46,
      "num": "20211021T0500-AA7044OO",
      "id": 1033728,
      "itinerary": null,
      "wastebins": 85
    },
    {
      "platforms": 77,
      "num": "20211021T0800-AA5895BP",
      "id": 1033730,
      "itinerary": null,
      "wastebins": 125
    }
  ],
  "success": true
}

Регистрация событий

Endpoint: http://<server_name>/components/communa/register_event

Событие "Выход на маршрут"

Запрос:

{
  "event": "ROUTE_START",
  "driver_id": 1012651,
  "loader_id": 1012652,
  "route_id": 1033710,
  "date": 1634810020725,
  "device_id": "1789fa18ad90ba55"
}

Ответ:

{
  "skipped": [],
  "trip_id": 1033731,
  "success": true
}

Событие "Приступил к уборке"

Запрос:

{
  "event": "ON_SHIFT",
  "route_id": 1033710,
  "device_id": "1789fa18ad90ba55"
}

Ответ:

{"success": true}

Событие "Еду в гараж"

Запрос:

{
  "event": "GO_TO_GARAGE",
  "route_id": 1033710,
  "device_id": "1789fa18ad90ba55"
}

Ответ:

{"success": true}

Событие "Еду на полигон"

Запрос:

{
  "event": "GO_TO_COLLECTION_SITE",
  "route_id": 1033722,
  "device_id": "1789fa18ad90ba55"
}

Ответ:

{"success": true}

Событие "Техобслуживание"

Запрос:

{
  "event": "GO_TO_SERVICE",
  "route_id": 1033722,
  "device_id": "1789fa18ad90ba55"
}

Ответ:

{"success": true}

Событие "Погрузка площадки"

Запрос:

{
  "event": "PLATFORM_LOADED",
  "platform_id": 1025030,
  "route_id": 1032188,
  "count": 2,
  "device_id": "29e199b8401de077"
}

Ответ:

{"success": true}

Запрос траектории до следующего пункта маршрута

Endpoint: http://<server_name>/components/communa/get_directions Endpoint: http://<server_name>/components/communa/get_directions_v2

Запрос:

{
  "lat": 49.82279963,
  "lng": 30.06916007,
  "device_id": "29e199b8401de077"
}

Ответ:

{
  "success": true,
  "route": [
    {
      "estimated_fill": 1,
      "volume": 1.1,
      "name": "Вул. Сквирське шосе, 216 а  3є щоденно,Вул. Сквирське шосе, 216 2є щоденно",
      "lat": 49.817365,
      "lng": 30.075344,
      "type": "PLATFORM",
      "id": 1025208,
      "quantity": 2
    },
    {
      "estimated_fill": 1,
      "volume": 1.1,
      "name": "«АТБ-маркет», Вул. Турчанінова, 4",
      "lat": 49.819928,
      "lng": 30.069391,
      "type": "PLATFORM",
      "id": 1025159,
      "quantity": 1
    },
    {
      "estimated_fill": 1,
      "volume": 1.1,
      "name": "Вул. Турчанінова, 25",
      "lat": 49.821286,
      "lng": 30.067053,
      "type": "PLATFORM",
      "id": 1025157,
      "quantity": 5
    },
    {
      "estimated_fill": 1,
      "volume": 1.1,
      "name": "Вул. Сквирське шосе, 250",
      "lat": 49.818504,
      "lng": 30.065084,
      "type": "PLATFORM",
      "id": 1025163,
      "quantity": 4
    },
    {
      "estimated_fill": 1,
      "volume": 1.1,
      "name": "Вул. Сквирське шосе, 264",
      "lat": 49.818593,
      "lng": 30.065134,
      "type": "PLATFORM",
      "id": 1025188,
      "quantity": 3
    },
    {
      "estimated_fill": 1,
      "volume": 1.1,
      "name": "Вул. Сквирське шосе, 256",
      "lat": 49.819249,
      "lng": 30.06513,
      "type": "PLATFORM",
      "id": 1025164,
      "quantity": 4
    },
    {
      "estimated_fill": 1,
      "volume": 1.1,
      "name": "Вул. Сквирське шосе, 238 1є щоденно ",
      "lat": 49.820531,
      "lng": 30.064775,
      "type": "PLATFORM",
      "id": 1025189,
      "quantity": 1
    },
    {
      "estimated_fill": 1,
      "volume": 1.1,
      "name": "Вул. Фурсівська, 29 п/с",
      "lat": 49.821383,
      "lng": 30.061602,
      "type": "PLATFORM",
      "id": 1025167,
      "quantity": 1
    },
    {
      "estimated_fill": 1,
      "volume": 1.1,
      "name": "Вул. Фурсівська, 21 п/с",
      "lat": 49.820526,
      "lng": 30.061734,
      "type": "PLATFORM",
      "id": 1025166,
      "quantity": 1
    }
  ],
  "destination": {
    "estimated_fill": 1,
    "volume": 1.1,
    "name": "Вул. Сквирське шосе, 216 а  3є щоденно,Вул. Сквирське шосе, 216 2є щоденно",
    "lat": 49.817365,
    "lng": 30.075344,
    "type": "PLATFORM",
    "id": 1025208,
    "quantity": 2
  },
  "steps": [
    {
      "maneuver": "depart",
      "distance_before": 0,
      "itinerary_before": "",
      "location": [
        49.8227932,
        30.0691627
      ],
      "duration_before": 0
    },
    {
      "maneuver": "turn-right",
      "distance_before": 109,
      "itinerary_before": "m_boHg{ovDe@uEOoA",
      "location": [
        49.8230599,
        30.0706273
      ],
      "duration_before": 16
    },
    {
      "maneuver": "turn-right",
      "distance_before": 728,
      "itinerary_before": "caboHmdpvDtFwIT_@`FaIb@q@DIDEvA}BnAsBhBsCb@o@pBeD",
      "location": [
        49.818226,
        30.0774666
      ],
      "duration_before": 69
    },
    {
      "maneuver": "arrive",
      "distance_before": 191,
      "itinerary_before": "}baoHeoqvD~@lAB@D@DDJN^j@BDBFBL@HRdBJlAFx@",
      "location": [
        49.817345,
        30.0753506
      ],
      "duration_before": 75
    }
  ],
  "itinerary": "m_boHg{ovDe@uEOoA??tFwIT_@`FaIb@q@DIDEvA}BnAsBhBsCb@o@pBeD??~@lAB@D@DDJN^j@BDBFBL@HRdBJlAFx@",
  "destination2": {
    "estimated_fill": 1,
    "volume": 1.1,
    "name": "«АТБ-маркет», Вул. Турчанінова, 4",
    "lat": 49.819928,
    "lng": 30.069391,
    "type": "PLATFORM",
    "id": 1025159,
    "quantity": 1
  }
}

Запрос количества поднятых контейнеров

Endpoint: http://<server_name>/components/communa/get_lifts_count

Запрос:

{
  "platform_id": 1025157,
  "device_id": "29e199b8401de077"
}

Ответ,

{
  "count": 7,
  "time_to": 1630938442,
  "time_from": 1630937859,
  "success": true
}

Имитация (mock) запроса количества поднятых контейнеров

Endpoint: http://<server_name>/components/communa/get_lifts_count_mock

Запрос:

{
  "platform_id": 1025157,
  "device_id": "29e199b8401de077",
  "count": 10
}

Ответ:

{
  "count": 10,
  "stop_to": 1630938442,
  "stop_from": 1630937859,
  "this_is_mock": true,
  "success": true
}

Залогировать дебажное сообщение на сервере

Endpoint: http://<server_name>/components/communa/debug

Запрос:

{
  "device_id": "957e4432c1357f1f",
  "msg": "Hi there!"
}

Ответ,

{"success": true}