• Главная
  • Главная
  • Новости
  • Новости
  • Документация
  • Документация по системе

Навигация по документации 

API обменника для исполнителя заказов

ДАННЫЙ ПРОТОКОЛ НАХОДИТСЯ В СТАДИИ РАЗРАБОТКИ! Использование данного протокола не доступно!

Версии

  • 2016-11-28 - Изменена структура status для соответствия ack
  • 2016-11-11 - Изменена структура ack для устранения дублирования и добавление новых полей
  • 2016-10-31 - предварительная версия

Введение

Работа с заказами состоит из следующих стадий

  • Обменник предлагает заказ (request)
  • Внешняя система сообщает о том, что у нее есть исполнитель для данного заказа (ack)
  • Обменник назначает заказ внешней системе (setorder), либо отменяет заказ (cancel)
  • По завершении заказа Обменник сообщает внешней системе дополнительные данные (оценку клиента, коментарий клиента по заказу)

В процессе работы обменник может передавать показания таксометра на выбранный URL (если он прописан)

Запросы к внешней системе

Предложение заказа (request)

В POST-теле запроса будет JSON вида:

{
    "id": "9d88e3ee976e11e69add6f31c648b566",
    "version": 1,
    "from": {
        "address": "Россия, Москва, Таганрогская улица, 29",
        "porch": 3,
        "lon": 33,
        "lat": 55
    },
    "to": {
        "address": "Россия, Московская область, Домодедово аэропорт",
        "porch": 2,
        "lon": 33,
        "lat": 55
    },
    "client": {
        "name": "Пупкин Василий",
        "comment": "Можно приехать минут на 10 пораньше"
    },
    "booking_time": "2013-01-02 23:00:00 +0400",
    "booking_time_exact": 1,
    "status": "request",
    "messenger": {
        "tariff": 1,
        "category": "business",
        "comment": "Сказать клиенту пароль: я от Семена",
        "minprice": 450,
        "inctime": 30,
        "incdist": 20,
        "timecost": 11,
        "distcost": 22,
        "transfer": 1,
        "algorithm": "max",
        "distcost_cad": 20,
        "distcost_out": 30,
        "timecost_cad": 10,
        "timecost_out": 15,
        "distcost_service_out": 200,
        "add_minprice": 400,
        "add_minprice_transfer": 500,
        "included_req_costs": 1,
        "distcost_unit": 15,
        "timecost_unit": 20,
        "speed": 20,
        "speed_time_markup": 12.1,
        "time_free": 10,
        "time_cost_wait": 11,
        "hide_client_phone": 1,
        "ready_disable": 1,
        "waiting_included": 0,
        "contact": {
            "phone": "+79261234567",
            "title": "гендиректор диспетчерской Такси-супер"
        }
    },
        "requirement": {
        "has_conditioner":              1,
        "no_smoking":                   0,
        "child_chair":                  0,
        "childseat_amount":             0,
        "childcradle_amount":           2,
        "childbooster_amount":          3,
        "animal_transport":             1,
        "universal":                    0,
        "wifi":                         1,
        "check":                        0,
        "card":                         1,
        "noncash":                      0,
        "special_number":               1,
        "no_brand":                     0,
        "car_license":                  1,
        "driver_license":               1,
        "driver_rating":                1
    },

    "fee": {
        "fix": 10,
        "relative": 5
    }
}

Расшифровку полей можно посмотреть в put

Пояснения по передаваемым полям:

  • Клиент передается без телефона.
  • status для предложения всегда request
  • version - номер версии заказа. Запросы доставляются асинхронно, поэтому могут прийти в разном порядке. Если Вы приняли запрос с version=7, то можете смело игнорировать запросы с version=6 и ниже. Данные в заказе от версии к версии могут изменяться.

Закрепление заказа (setorder)

В POST-теле запроса будет JSON аналогичный Предложение заказа:

{
    ...
    "client": {
        ...
        "phone": "+7123456789",
    },
    "status": "confirm",
}

Расшифровку полей можно посмотреть в put

Пояснения по передаваемым полям:

  • Передается телефон клиента.
  • status всегда confirm

Отмена заказа (cancel)

Вызывается если заказ был отменен, просрочен или ушел в другую службу. POST-тело будет содержать следующие данные:

{
    "id": 12345,
    "status": "cancelled",
    "comment": "Клиент отменил заказ"
}

где поля:

  • id - ID заказа
  • status - статус заказа:
    • cancelled - отменен клиентом
    • cancelled_user - отменен создателем
    • failed - отменен исполнителем
    • assigned - распределен другому клиенту
    • timeout - просрочен
  • comment - коментарий к отмене заказа

Передача показаний таксометра

Вызывается для заказов в статусе transporting с частотой примерно 1 раз в минуту.

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

POST-тело запроса будет содержать следующие данные:

[
    {
        "id": 1234,
        "txm": {
            "point": {
                "lon": 37.234,
                "lat": 55.345,
                "dist": 12345
            },
            "time": {
                "total": 27,
                "pause": 11,
                "begin": '2016-10-30 21:23:12 +0300',
                "cost":  73.00
            },
            "dist": {
                "total": 6300,
                "begin": 6045,
            },
            "cost": {
                "total": 143.34,
                "time": 73.00,
                "universal": 20.11,
                "dist": 50.23
            }
        }
    }
]

где поля:

  • id - идентификатор заказа (в одном запросе могут передаваться таксометры по нескольким заказам)
  • txm - расчитанный таксометр

Отзыв по заказу (feedback)

Если клиент оценил поездку то передается отзыв по ней. POST-тело будет содержать следующие данные:

{
    "id": 12345,
    "rating": 4,
    "comment": "Поездка прошла хорошо"
}

Оценки будут отправляться только в статусах:

  • complete - выполнен
  • cancelled - отменен клиентом
  • cancelled_user - отменен создателем
  • failed - сорван

Обратные запросы к ОБМЕННИКУ

api/APIKEY/order/ack

При получении предложения заказа КЛИЕНТ решает будет он выполнять этот заказ или нет. Если КЛИЕНТ хочет выполнить данный заказ он отпраляет в ОБМЕННИК согласие. Это POST запрос с телом в формате JSON:

{
    "id": 12345,
    "tariff":[1,2],

    "driver_details": {
        "sign": "007",
        "name": "Васисуалий Пупкин",
        "phone": "+79876543210",
        "license": "A1234556"
    },

    "car_details": {
        "brand": "Мерседес",
        "model": "600",
        "color": "зеленый",
        "age": 1991,
        "number": "762",
        "license": "МО 123456"
    },

    "point": {
        "lon": 37.123,
        "lat": 55.345,
        "time": "2014-01-02 23:22:21 +0400"
    },

    "service": {
        "title": "Название службы",
        "phone": "+79876543211"
    }
}

Описание полей можно посмотреть: При изменении статуса заказа.

где:

  • id - идентификатор заказа который хочется взять
  • tariff - тарифы по которым согласен исполнить заказ
  • driver/name - имя водителя
  • driver/phone - телефон водителя
  • driver/license - лицензия водителя

В ответ на запрос возвращаются следующие коды HTTP:

  • 200 - статус успешно изменен
  • 400 - не хватает обязательного параметра в запросе
  • 410 - согласие уже есть
  • 404 - заказ не найден

api/APIKEY/order/status

При изменении статуса в программном обеспечении КЛИЕНТА, он должен уведомлять ОБМЕННИК об этом изменении. Ожидается POST запрос с телом в формате JSON:

{
    "id": 12345,
    "status": "complete",
    "payment": 1500
}

при переназначении аналогично ack:

{
    "id": 12345,
    "tariff":[1],

    "status": "driving",

    "driver_details": {
        "sign": "007",
        "name": "Васисуалий Пупкин",
        "phone": "+79876543210",
        "license": "A1234556"
    },

    "car_details": {
        "brand": "Мерседес",
        "model": "600",
        "color": "зеленый",
        "age": 1991,
        "number": "762",
        "license": "МО 123456"
    },

    "point": {
        "lon": 37.123,
        "lat": 55.345,
        "time": "2014-01-02 23:22:21 +0400"
    },

    "service": {
        "title": "Название службы",
        "phone": "+79876543211"
    }
}

Описание полей можно посмотреть: При изменении статуса заказа.

  • status - текущий статус заказа. Возможны следующие варианты:

    • driving - водитель выехал на заказ
    • waiting - водитель ожидает клиента
    • transporting - водитель везет клиента
    • complete - клиент доставлен
    • failed - водитель сообщил о невозможности выполнить заказ (срыв)
    • confirm - при переназначении - назначен водителю
  • payment - (актуально только при статусе ‘complete’)

  • comment - коментарий службы или водителя при отмене заказа (cancelled) или при срыве заказа (failed)

Секции tariff, driver_details, car_details, service присылаются при переназначении машины аналогично запросу ack. В случае, если присутствует хотя бы одна из этих секций, обязаны присутствовать остальные. Статус при этом должен быть confirm, либо driving (назначена, выехал).

Переназначение возможно только в статусах

  • confirm - заказ назначен
  • driving - водитель выехал на заказ
  • waiting - водитель ожидает клиента

Переназначение в статусе transporting запрещено.

Статусы заказа могут меняться в описанном выше порядке, за исключением failed который может быть отправить в любой момент.

В ответ на запрос возвращаются следующие коды HTTP:

  • 200 - статус успешно изменен
  • 400 - не хватает обязательного параметра в запросе
  • 410 - статус уже изменен или более поздний
  • 404 - заказ не найден

api/APIKEY/order/tracks

По всем заказам в работе передаются точки. Рекомендуемое время: раз в 15 сек. POST запрос с телом в формате JSON:

[
    [ "7e968f6279d846d19d69a6c0bc9d291e",
        37.2123,
        55.32222,
        "2014-01-02 23:22:21 +0400"
    ],
    [ "c8dc47f9c8b545ab8bc79369a19a4382",
        37.1233, 55.77226,
        "2014-01-02 23:22:22 +0400"
    ]
]

Передается в виде массива, состоящего из элементов, каждый из которых описывает один заказ:

  1. Идентификатор заказа
  2. Долгота водителя, исполняющего заказ
  3. Широта водителя, исполняющего заказ
  4. Полная дата/время точки

Общие сведения

  • О системе

ДИРЕКТОРУ

  • С чего начать
  • Платежные системы
  • Работа с пользователями
  • Колонны
  • Автомобили
  • Водители
  • Категории водителей
  • Условия расчетов водителей
  • Периодические списания
  • Корпоративные клиенты
  • Телефония
  • SMS провайдеры

ДИСПЕТЧЕРУ

  • Общие сведения и понятия
  • Заказы службы такси
  • Заявки (предзаказ)
  • Передача заказа в обменник
  • Тарифы
  • Геозоны
  • Система контроля заказов

ВОДИТЕЛЮ

  • Мобильное приложение ШЕФ
  • Инструкция ШЕФ
  • Полная инструкция ШЕФ
  • Настройка системы навигации
  • Робот заказов
  • Видео инструкции
  • Периодические списания
  • Таксометр ШЕФа
  • Работа с купонами
  • Топливные карты
  • Работа с безналичными заказами
  • Описание проблем

ОБМЕННИК

  • Общие сведения
  • Обработка заказа в обменнике
  • Правила обменника

ДОПОЛНИТЕЛЬНО

  • Вопросы-Ответы
  • Как пополнить баланс службы
  • Что нельзя делать

API интеграций

  • Интеграция с ERP и CRM
  • Вброс заказа в Обменник
  • Протокол обмена с внешним ПО
  • Платежные терминалы
  • API бота топлива
  • Управление клиентами в МП
  • Получение заказов из Обменника

© Copyright 2011-2018. Все права защищены. NOWTAXI LLC, info@nowtaxi.ru
  