Сервер CourierApp API

• courier_uid, tz_uid 

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

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

Если запрос успешно обработан, сервер вернет ответ с статусом 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

2025-03-26 Параметр wage упразднен, статистику нужно получать отдельным запросом

POST запрос:

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

Ответ успех:

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

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

POST /api/v1/get_orders

Возвращает данные по заказам. Список возвращаемых заказов и набор параметров запроса зависит от варианта запроса get_type:

• completed_orders - выполненные заказы курьером за период
  • Требует передачи параметров courier_uid, tz_uid, start_date, end_date
  • Передаются заказы в статусах "Заказ доставлен", "Заказ закрыт"
  • В ответе дополнительно передается сумма начисления курьеру за заказ, параметр wage
• courier_orders - заказы назначенные на курьера 
  • Требует передачи параметров courier_uid, tz_uid 
  • Статус возвращаемых заказов зависит от настроек Юпитера. Если включена роль "Передавать в приложение курьера заказы в любом статусе", то возвращаются заказы в статусах: "Выполняется", "Выполняется частично", "Готов к передаче клиенту", "Распечатан счет", "Назначен курьеру". Если роль выключена, то возвращаются заказы в статусе "Назначен курьеру"
  • Возвращаются только заказы в которые записаны координаты дома.
• ready_orders - заказы готовые к передаче клиенту.
  • Требует передачи параметра timestamp (дата\время предыдущего запроса заказов) для определения и заполнения признака наличия новых заказов
  • Возвращаются заказы в статусе "Готов к передаче клиенту"
  • Возвращаются только заказы в которые записаны координаты дома

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, completed_orders.
  "courier_uid": "4:3:0:298972", // UID курьера (обязательно для courier_orders, completed_orders).
  "tz_uid": "4:3:0:299094", // UID торговый зал, на котором работает курьер (обязательно для courier_orders, completed_orders).
  "timestamp": "2020-07-02 10:23:21", // Дата\время прерыдущего запроса заказов (обязательно для ready_orders).
  "start_date": "2025-04-02", // С какой даты отбирать заказы (обязательно для completed_orders).
  "end_date": "2025-04-05" // По какую дату отбирать заказы, включительно (обязательно для completed_orders).
}

Ответ успех:

[
    {
        "address": "Москва, ул. Авангардная улица, д. 1, под. 1, дмф. 52, эт. 5, кв. 52", // Адрес доставки
        "zone_name": "Зона доставки № 1", // Название зоны доставки
        "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, // Сумма заказа с учётом скидок
        "wage": 50, // Сумма начисления курьеру за заказ (передается только если get_type = completed_orders)
        "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. В нем передается текущая сумма начислений курьеру. Рассчитывается по настройке начисления исполнителям.

2025-03-26 Параметр wage упразднен, статистику нужно получать отдельным запросом

POST запрос:

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

Ответ успех:

{
  "result": "success"
}

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

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 для проверки местоположения
    "tz_coordinates" : [ // Массив коордиант торгового зала
		"55.767210", // Широта
		"37.593390" // Долгота
    ],
    "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 /get_courier_stats

Возвращает статистику по курьеру. Статистика возвращается за один день и за текущий месяц. День и месяц определяются по дате последнего рабочего дня. Статистика рассчитывается по заказам которые были отмечены как доставленные либо закрыты.

POST запрос:

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

Ответ успех:

{
    "result": "success",
    "day": { // Блок со статистикой за день
        "label": "26-03-2025", // Дата за который собрана статистика
        "orders_qty": 1, // Кол-во заказов
        "orders_sum": 1660.00, // Сумма заказов
        "cash_sum": 1660.00, // Сумма заказов с наличной оплатой
        "cashless_sum": 0.00, // Сумма заказов с безналичной оплатой
        "wage": 166.00 // Сумма начислений курьеру. Рассчитывается по настройке начисления исполнителям.
    },
    "month": { // Блок со статистикой за месяц
        "label": "Март 2025", // Месяц за который собрана статистика
        "orders_qty": 1,
        "orders_sum": 1660.00,
        "cash_sum": 1660.00,
        "cashless_sum": 0.00,
        "wage": 166.00
    }
}

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

POST /api/v1/logmsg

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

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

{}

Ответ успех:

{}