Сервер CourierApp API

Общая информация

Результаты обработки запроса

Если запрос успешно обработан, сервер вернет ответ с статусом 200.

Если при обработке запроса были ошибки, сервер вернет ответ со статусом ошибки (400, 401, 500) и описание ошибки.

{
  "desc": "Не правильное имя пользователя или пароль", // Описание ошибки
  "result": "error" // Признак ошиибки
}

Вызовы

Авторизация курьера

POST /api/v1/auth_pwdсodе

Поиск курьера по строке код+пароль Если находит, то возвращает его UID

2023-08-29 /api/v1/auth и /api/v1/auth_сod упразднены, используется /api/v1/auth_pwdcode

POST запрос:

{
  "pwdсodе": "20331" // Код авторизации (Код сотрудника + Пароль), по аналогии с авторизацией в кассе Юпитер
}

Ответ успех:

{
  "name": "Борисов Артем", // Имя курьера
  "tz_uid": "4:3:0:299094", // UID торговый зал, на котором работает курьер. Сохраняется в приложении и используется в следующих запросах
  "uid": "4:1:0:531", // UID курьера на котором работает курьер. Сохраняется в приложении и используется в следующих запросах
  "wage": 200 // Текущая сумма начислений курьеру. Рассчитывается по настройке начисления исполнителям.
}

Получить список заказов

POST /api/v1/get_orders

Возвращает список заказов на доставку (только заказы с координатами) по указанному курьеру, которые находятся в состоянии "В работе" и статусе "Назначен курьеру".

2023-08-07 Теперь возвращает даже те заказы, у которых нет координат

2023-08-10 Добавлены параметры: build_number (string) - Номер сборки; cashless (boolean) - Если 1 значит безнал, если 0 значит наличные. Если в заказе не определен вид оплаты, то примет значение 0; prepayment (boolean) - Если 1 значит оплата уже была получена на сайте/приложении/агрегаторе, если 0 значит оплату нужно получить с клиента. Если в заказе не определен вид оплаты, то примет значение 0. Значение определяется в соответствии с новым параметром вида оплаты "Онлайн оплата".

2024-04-18 Добавлен параметр delivery_time_from_routing. Дата\время когда заказ нужно доставить по расчётам Яндекса. Рассчитывается при назначении заказов на курьера. Учитывает порядок доставки (если курьер за раз везет несколько заказов). Учитывает время необходимое для того, чтобы отдать заказ (константа 10 мин). Учитывает пробки (по Яндексу)

POST запрос:

{
  "get_type": "courier_orders", // courier_orders - заказы назначенные на курьера, ready_orders - заказы с координатами в статусах "Выполняется", "Готов" 
  "courier_uid": "4:3:0:298972", // UID курьера (только для courier_orders)
  "timestamp": "2020-07-02 10:23:21" // С какой даты отбирать заказы (только для ready_orders)
}

Ответ успех:

[
    {
        "address": "Москва, ул. Авангардная улица, д. 1, под. 1, дмф. 52, эт. 5, кв. 52", // Адрес доставки
        "client": { // Данные клиента
            "name": "Олеся",
            "phone": "8 (909) 321-12-22"
        },
        "coordinates": [ // Координаты адреса доставки
            "55.843121", // Широта
            "37.491072" // Долгота
        ],
        "lines": [ // Данные по составу заказа
            {
                "id": "6:1:0:272681", // ID товарной строки заказа
                "name": "ПИРОЖОК С КАПУСТОЙ", // Имя товара
                "price": 22, // Цена с учётом скидок
                "qty": 1, // Кол-во
                "sum_fact": 22, // Сумма с учётом скидок
                "modifiers": [ // Модификаторы к товару
                    {
                        "id": "6:1:0:272684", // ID Строки модификатора
                        "name": "ДОП. ГРИБЫ", // Имя товара
                        "price": 51, // Цена с учётом скидок
                        "qty": 1, // Кол-во
                        "sum_fact": 51 // Сумма с учётом скидок
                    },
                    {
                        "id": "6:1:0:272682",
                        "name": "ДОП. СЫР",
                        "price": 34,
                        "qty": 1,
                        "sum_fact": 34
                    },
                    {
                        "id": "6:1:0:272683",
                        "name": "ДОП. ЛУК",
                        "price": 42,
                        "qty": 1,
                        "sum_fact": 42
                    }
                ]
            },
            {
                "id": "6:1:0:272645",
                "name": "КАРТОФЕЛЬ ПО-ДЕРЕВЕНСКИ",
                "price": 60,
                "qty": 1,
                "sum_fact": 60,
                "modifiers": []
            }
        ],
        "max_time": 110, // Максимальное время доставки из зоны доставки (минуты)
        "open_date": "2019-06-18 13:30:13", // Дата\время создания заказа
        "order_num": "9-1-79-4", // Номер заказа
        "sum_fact": 389, // Сумма заказа с учётом скидок
        "uid": "5:1:0:116862", // UID заказа
        "urgent": 2, // Уровень срочности, где 1 = "Можно не спешить" (не используется)
        "deliver_at": "14:30", // Время к которому нужно доставить заказ. Если клиент не указывал время, то рассчитывается как максимальное время доставки из зоны
        "delivery_time_from_routing": "2019-06-18 14:00:01", // Дата\время когда заказ нужно доставить по расчётам Яндекса
        "delivering_time": 35, // Время необходимое на доставку по данным Яндекса (минуты)
        "tz": "ТЗ Москва", // Имя торгового зала
        "build_number": "1", // Номер сборки (порядковый номер заказа в РД)
        "cashless": 1, // Безналичная оплата
        "prepayment": 1, // Деньги уже получены (онлайн оплата)
        "been_delivered": false, // Заказ был доставлен
        "when_delivered": "" // Когда заказ был доставлен в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС
    }
]

Отметить, что заказ доставлен

POST /api/v1/order_is_delivered

Изменяет статус заказа на "Заказ доставлен"

2023-08-10 Добавлен параметр pay_is_changed (boolean). Сохраняет в заказ признак, что вид оплаты изменился. Значение параметра можно увидеть в разделе "Все заказы (только просмотр)", колонка "Была смена вида оплаты" 

2023-12-25 В ответ добавлен параметре wage. В нем передается текущая сумма начислений курьеру. Рассчитывается по настройке начисления исполнителям.

POST запрос:

{
  "order_uid": "5:1:0:323",
  "pay_is_changed": 0
}

Ответ успех:

{
  "result": "success",
  "wage": 320
}

Подтвердить, что курьер будет выполнять заказ

POST /api/v1/courier_confirmed

Изменяет признак в заказе, что заказ подтверждён курьером (т.е. курьер заказ увидел, и готов его выполнить)

POST запрос:

{
    "order_uid" : "5:1:0:323"
}

Ответ успех:

{
    "result": "success"
}

Установить текущее местоположение курьера

POST /api/v1/set_current_location_couriers

Данные о местоположении хранятся в памяти. Для каждого курьера сохраняется только последнее местоположение, без истории

POST запрос:

{
  "location": {
    "coords": {
      "latitude": 55.4362326,
      "longitude": 37.3307705,
      "param": 1
    }
  },
  "courier_uid": "4:3:0:298972"
}

Ответ успех:

{
    "result": "success"
}

Установить текущий статус курьера

POST /api/v1/set_courier_status Курьер в течении дня может менять свой статус активен\не активен Если курьер не активен, то не показываем его в списке назначения курьера на заказ (в Юпитере)

POST запрос:

{
  "courier_uid": "4:3:0:298972",
  "satus": "active"    // active - активен, not_active - не актвиен
}

Ответ успех:

{
    "result": "success"
}

Получить список курьеров

POST /api/v1/get_couriers

Возвращает список курьеров у которых открыта смена в Юпитере. Если курьер использует мобильное приложение, то возвращает его последнее местоположение (параметр "coordinates"). Если у курьера есть заказы в статусе "Назначен курьеру", то возвращает признак, что курьера занят (параметр "courier_is_free")

2020-03-20 Добавлен обязательный параметр tz_uid в него нужно передавать UID торгового зала из Юпитера. Ищем открытую смену только по этому ТЗ.

POST запрос:

{
  "tz_uid": "4:3:0:299094"
}

Ответ успех:

{
  "courier_uid": "4:1:0:932",
  "tz_uid": "4:3:0:299094",
  "orders": [
    "5:1:0:115982",
    "5:1:0:115983"
  ]
}

Назначить курьера на заказы

POST /api/v1/appoint_courier

Отправляет в Юпитер команду назначения курьера на несколько заказов

2020-06-25 В массиве orders можно вместо UIDов можно передать номер сборки. Например "orders": ["1","2"]

2024-04-05 При получении запроса, Юпитер создает запись в Журнале поездок. Заказы в массиве orders должны быть расположены в том порядке, в котором они будут доставляться. Рассчитывается и фиксируется время, когда курьер должен вернуться с поездки. В каждый заказ отдельно записывается время, когда заказ должен быть доставлен.

POST запрос:

{
  "courier_uid": "4:1:0:932",
  "tz_uid": "4:3:0:299094",
  "orders": [
    "5:1:0:115982",
    "5:1:0:115983"
  ]
}

Ответ успех:

{
  "result": "success"
}

Курьер вернулся на торговую точку

POST /api/v1/came_back

Завершает ВСЕ открытые поездки курьера. Отправляется после успешного "пинга" FRServer (для подтверждения, что курьер действительно находится на торговой точке). Юпитер фиксирует время получения запроса как время завершения поездки.

POST запрос:

{
  "courier_uid": "4:1:0:932", // UID курьера
  "tz_uid": "4:3:0:299094"  // UID торгового зала
}

Ответ успех:

{
  "result": "success"
}

Ответ ошибка:

{
  "desc": "Ошибка, не удалось подключиться к БД",
  "result": "error"
}

Получить состояние курьера

POST /get_courier_state

Возвращает текущее состояние курьера:

• Закрыта смена
• Свободен. В этом случае также возвращается список заказов, которые курьер может взять в доставку
• Доставляет заказы. У курьера есть незавершенная поездка с недоставленными заказами. В этом случае возвращаются параметры поездки и список ВСЕХ заказов по поездке
• Возвращается. У курьера есть незавершенная поездка, все заказы в поездке доставлены. В этом случае возвращаются параметры поездки и список ВСЕХ заказов по поездке

В параметре frserver_address передается ip-адрес и порт FRServer, который установлен на локальном компьютере торговой точки. Приложение опрашивает FRServer, если FRServer отвечает статусом 200, то это означает, что курьер находится на торговой точке.

POST запрос:

{
  "courier_uid": "4:1:0:932", // UID курьера
  "tz_uid": "4:3:0:299094"  // UID торгового зала
}

Ответ успех:

{
    "courier_status": "delivers_orders", // shift_closed - смена закрыта, free - свободен, delivers_orders - доставляет заказы, returning - возвращается
    "frserver_address": "192.168.0.111:6600" // URL FRServer для проверки местоположения
    "trip": { // Возвращается если статус delivers_orders или returning
        "start": "2024-04-25 19:29:00", // Дата\время начала поездки
        "end": "2024-04-25 20:30:00",  // Дата\время завершения поездки. Плановое по Яндексу
        "orders_qty": 3, // Кол-во заказов в доставке
        "duration_min": 61 // Общее время поездк в минутах. Плановое по Яндексу
    },
  	"orders": [ // Список заказов. Возвращается если статус free, delivers_orders или returning
      ..
    ]
}

Тестовый запрос

POST /api/v1/logmsg

Запрос для отладки мобильного приложения. Записывает тело полученного запроса в лог файл путь к папке HOME/courierapp_ДАТА.log

Пустой POST запрос:

{}

Ответ успех:

{}