iPost REST API

API Version: 1.20

Getting started

Запрос к API

API_URL: https://api.ipost.life/public/v1

API_URL нужно считать как начальную часть url’а для запроса. Т.е. конечный урл запроса должен состоять из начального url и части, указанной в описании каждого конкретного метода API.

Запросы, требующие отправки сообщения (HTTP BODY) должны быть отосланы с HTTP хедером Content-Type: application/x-www-form-urlencoded или Content-Type: application/json, и быть закодированными соответственно указанному в запросе Content-Type.

Ответ API

Сервер отвечает в формате JSON.

В случае успеха сервер возвращает http код 200 с ожидаемым ответом.

В случае возникновения ожидаемой ошибки, сервер возвращает ответ об ошибке с http кодом 422. В таком случае сервер возвращает тело ответа, которое рекомендуется парсить и разбирать ошибки.

{
    "code": {code},
    "message": {message}
}

Где {code} - это (integer) номер ошибки, а {message} - это (string) текстовое описание ошибки.

Подробнее коды ошибок описаны в разделе Errors.

В случае неудачной идентификации/авторизации пользователя сервер отвечает с http кодом 401.

Так же сервер может вернуть ошибки 403, 404, 500, и прочие. При нормальном ходе работы их возникать не должно, потому любые http коды ошибок, не обозначенные выше, должны считаться непредвиденными (5xx), или ошибкой клиента (4xx).

Notes

Сериализация float

Текущая реализация сериализации данных в JSON предполагает отрезание точки и следующие за ней символы у float-даннных в случае, если дробная часть равна нулю. Тем не менее, парсить такие данные нужно как float.

Сериализация денежных представлений

Таковые в документации указаны как float, но в большинстве случаев эти значения сериализируются в строку, типа "126.95".

Сериализация bool

Значения bool сериализируются как 0 и 1 для false и true соответственно.

Номер телефона

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

Authentication

Большинство методов API требуют идентификации пользователя. Для этого, нужно слать следующий хедер:

Authorization: Bearer {access_token}

где {access_token} - это токен, который можно получить в ЛК: АККАУНТ → ПРОФИЛЬ → вкладка API.

В случае, если метод, требующий идентификации пользователя, запрашивается без хедера авторизации или запрос не прошел авторизацию, сервер ответит с http кодом 401.

Edges

API состоит из т.н. edges, т.е. логически разделенными точками входа / краями. Далее в документации указывается http метод и путь, добавляемый к base url.

Edge: /orders (Заказы)

Получение всех заказов

Метод требует идентификации

GET /orders

QueryString (GET) параметры:

GET /orders?status=active

Результат:

В случае успеха сервер возвращает список заказов в следующем виде:

{
    items: OrderShort[],
    links: NavLinks,
    meta: NavMeta
}

{
    "items": [{
        "id": 188,
        "tariff_type": 1,
        "delivery_time": 7200,
        "delivery_distance": 10223,
        "description": "Дверная ручка",
        "length": 500,
        "width": 500,
        "height": 300,
        "valuation": 600,
        "weight": 600,
        "places": 1,
        "name": "Грек Светлана",
        "phone": "380965156948",
        "price": "178.00",
        "payment_type": 4,
        "status": 0,
        "reason": 0,
        "created_at": 1529963283,
        "updated_at": 1529963283,
        "payment_split": {
            "balance": "100.00",
            "sender": "78.00"
        },
        "custom_price": 0
    }, {
        "id": 187,
        "tariff_type": 1,
        "delivery_time": 5400,
        "delivery_distance": 10223,
        "description": "Компакт-диск",
        "length": 200,
        "width": 200,
        "height": 10,
        "valuation": 250,
        "weight": 100,
        "places": 1,
        "name": "Стриллер Вачеслав",
        "phone": "380508695044",
        "price": "74.00",
        "payment_type": 4,
        "status": 0,
        "reason": 0,
        "created_at": 1529962563,
        "updated_at": 1529962563,
        "payment_split": {
            "balance": "50.00",
            "sender": "24.00"
        },
        "custom_price": 0
    }, {
        "id": 186,
        "tariff_type": 1,
        "delivery_time": null,
        "delivery_distance": 10223,
        "description": "Процессор",
        "length": 200,
        "width": 200,
        "height": 150,
        "valuation": 5000,
        "weight": 1,
        "places": 1,
        "name": "iPCStore Ukraine",
        "phone": "380961212121",
        "price": "94.00",
        "payment_type": 1,
        "status": 0,
        "reason": 0,
        "created_at": 1529962552,
        "updated_at": 1529962552,
        "payment_split": null,
        "custom_price": 20
    }],
    "links": {
        "self": "http://api.ipost.local/public/v1/orders?page=1",
    },
    "meta": {
        "total_count": 3,
        "page_count": 1,
        "current_page": 1
    }
}

Коды ошибок:

• + общие ошибки

Получение подробной информации по заказу

Метод требует идентификации

GET /orders/{id}

Где {id} - это id заказа.

Метод возвращает ту же информацию, что и GET /orders.

Результат:

В случае успеха сервер возвращает объект Order.

{
    "id": 188,
    "origin_id": null,
    "recreated_id": null,
    "tariff_type": 1,
    "delivery_time": 7200,
    "delivery_distance": 10223,
    "description": "Дверная ручка",
    "length": 500,
    "width": 500,
    "height": 300,
    "valuation": 600,
    "weight": 600,
    "places": 1,
    "name": "Грек Светлана",
    "phone": "380965156948",
    "price": "178.00",
    "payment_type": 4,
    "status": 0,
    "reason": 0,
    "created_at": 1529963283,
    "updated_at": 1529963283,
    "payment_split": {
        "balance": "100.00",
        "sender": "78.00"
    },
    "address": {
        "lat": 50.4327,
        "long": 30.4304,
        "city": "Київ",
        "street": "вул. Михайла Донця",
        "number": "7",
        "flat": null
    },
    "pickup": {
        "time_from": null,
        "time_to": null,
        "comment": null,
        "status": 0,
        "reason": 0,
        "reason_custom": null,
        "updated_at": 1529963283,
        "images": []
    },
    "deliveries": [{
        "id": 2269,
        "name": "И",
        "phone": "380985588999",
        "time_from": null,
        "time_to": null,
        "payment_type": null,
        "finance_type": 0,
        "redelivery_type": 0,
        "age_check_required": 0,
        "personal_id_check_required": 0,
        "order_number": null,
        "confirm_code": 139770,
        "comment": null,
        "status": 0,
        "reason": 0,
        "reason_custom": null,
        "updated_at": 1529963283,
        "payment_amount": null,
        "address": {
            "lat": 50.4399,
            "long": 30.5215,
            "city": "Київ",
            "street": "вул. Шота Руставелі",
            "number": "8",
            "flat": null
        },
        "parcels": [{
            "id": 3422,
            "description": "BLa-bla",
            "valuation": 100,
            "weight": 1,
            "places": 1
        }],
        "images": []
    }],
    "redelivery": null,
    "codtoaccount": null,
    "courier": null,
    "review_meta": {
        "avg_rating": 4.5,
        "count": 5 
    },
    "custom_price": 0
}

Коды ошибок:

• + общие ошибки

Создание заказа

Метод требует идентификации

Для создания нового заказа:

POST /orders

Для оценки стоимости заказа (без создания):

POST /orders?preview=1

NB: при запросе с preview=1 отменяются проверки на обязательность полей (required => nonrequired). Остальные проверки остаются, но могут быть пропущены, если для какой-то проверки не хватает данных (например, если нет габаритов отправления или веса посылок, то проверка на наличие подходящего тарифа не будет произведена, соответственно, ошибки 109 быть не может.)

Поля запроса:

• ¹ Если указать значение в данном поле, то время доставки будет считаться относительным - “доставить за X”, где X - кол-во секунд, кратное 1800 (30 минут), но не менее 1800 (30 минут) и не более 10800 (3 часа). При этом поля time_from и time_to в объектах FormOrderPickup, FormOrderDelivery и FormOrderRedelivery будут проигнорированны. Данное поле возможно установить только в том случае, если в заказе указан только один пункт доставки (order.deliveries).
• ² Если в заказе более 1 пункта доставки, тогда поле обязательно. В других случаях, если значение не указано, оно подставляется из описания посылки.
• ³ Если не указывать, значения будут взяты из профиля пользователя.
• ⁴ Если в заказе более 1 пункта доставки, данное поле не обязательно и игнорируется. В этом случае необходимо заполнить аналогичное поле в доставке (FormOrderDelivery).
• ⁵ Данное поле может быть установлено только если в заказе задан только один пункт доставки.
• ⁶ Значение обязательно в случае, если есть наложенный платеж на расчетный счет. В других случаях игнорируется.
• ⁷ Значение обязательно в случае, если оплата доставки картой. В других случаях игнорируется.

ВНИМАНИЕ: в некоторых случаях (если клиент — бизнес) при использовании ваучера вместе с оплатой с баланса (включая разделение платежа) может вернуться ошибка 136, что значит, что произвести оплату с баланса при использовании ваучера невозможно. Доступные варианты оплаты остатка (если после применения ваучера он есть): наличными отправителем, наличными получателем, разделение платежа на наличными отправителем и получателем.

Количество пунктов доставки (элементов в order.deliveries) должно быть не более 30, в противном случае будет ошибка валидации.

Пустые структуры и значения можно не отправлять.

FormOrderAddress : Object

FormOrderPickup : Object

• ¹ В случае, если в заказе установлено значение delivery_time, то поля time_from и time_to заполнять не нужно. Они будут проигнорированны и выставленны другие после принятия заказа курьером.

FormOrderDelivery : Object

• ¹ В случае, если в заказе установлено значение delivery_time, то поля time_from и time_to заполнять не нужно. Они будут проигнорированны и выставленны другие после принятия заказа курьером.
• ² Поле требуется только при мультидоставке - когда способ оплаты в форме заказа не указан (т.е. для каждого получателя оплата определяется отдельно.). В ином случае оно игнорируется, используется значение order.payment_type.
• ³ Может быть установлено только одно из двух полей - finance_type или redelivery_type. (Т.е. второе должно быть 0 или вовсе отсутствовать).
• ⁴ В настоящее время возможность оформлять обартную доставку для межгорода закрыта!
• ⁵ Поле требуется только при наложенном платеже на карту (если finance_type = FormOrderDeliveryFinanceTypeEnum::FINANCE_TYPE_COD_CARD).

FormOrderParcel : Object

FormOrderRedelivery : Object

• ¹ В случае, если в заказе установлено значение delivery_time, то поля time_from и time_to заполнять не нужно. Они будут проигнорированны и выставленны другие после принятия заказа курьером.
• ² Поле требуется только при мультидоставке и только если хотя бы у одного из получателей указана обратная доставка, в ином случае оно игнорируется, используется значение order.payment_type. Допускаются только следующие значения: PAYMENT_TYPE_RECIPIENT, PAYMENT_TYPE_BALANCE, PAYMENT_TYPE_CARD.

FormOrderCodToAccount : Object

NB: остальные значения для наложенного платежа подтягиваются из бизнес-профиля. Потому последний должен быть заполнен.

FormOrderPaymentTypeEnum : integer

Возможные значения:

(описания см. в OrderPaymentTypeEnum)

FormOrderPaymentSplit : Object

NB: если будет установлено более одного поля, использоваться будет только первое подходящее, остальные будут проигнорированы.

FormOrderTargetPaymentTypeEnum : integer

Возможные значения:

(описания см. в OrderTargetPaymentTypeEnum)

FormOrderDeliveryFinanceTypeEnum : integer

Возможные значения:

NB: на данный момент опции 3 и 6 недоступны! При использовании этих опций будет приходить ошибка 132.

NB: значение 7 (Наложенный платеж на расчетный счет) не может быть установлено для мультидоставки. В противном случае будет ошибка валидации. Так же, это значение (7) может быть использовано только бизнес-клиентом, у которого заполнен бизнес-профиль. Иначе — ошибка валидации. (Предполагается, что у всех бизнес-клиентов этот профиль заполнен, но есть несколько исключений).

(описания см. в OrderDeliveryFinanceTypeEnum)

FormOrderDeliveryRedeliveryTypeEnum : integer

Возможные значения:

(описания см. в OrderDeliveryRedeliveryTypeEnum)

Разьяснения по оплате

Для определения способа оплаты используется поле order.payment_type. Оно определяет способ оплаты как за доставку, так и за обратную доставку. Но в мультидоставке за обратную доставку отвечает поле FormOrderRedelivery.payment_type.

При установке order.payment_type имеется возможность разбить платеж на 2 способа оплаты, установив в объекте order.payment_split одно из соответсвующих способу разделения оплаты - второе будет расчитано автоматически. Если указаное значение будет больше или равно стоимости доставки, то order.payment_type будет изменен на соответствующий способ (например, выбрали способ оплаты - разделение: с баланса и получателем, но указали фиксированную сумму получателем 200 у.д.е. при стоимости заказа в 150 у.д.е., в таком случае, order.payment_type будет изменен с PAYMENT_TYPE_SPLIT_BALANCE_AND_RECIPIENT на PAYMENT_TYPE_RECIPIENT). Если будет выбран способ платежа - разделение оплаты, но order.payment_split не будет установлен, то разделение будет 50%/50% с округлением каждой части вверх до целой у.д.е.

Примеры:

1. 40 у.д.е. получателем и остальное отправителем:

   payment_type = PAYMENT_TYPE_SPLIT_SENDER_AND_RECIPIENT
   payment_split = {recipient: 40}
   

2. 40 у.д.е. отправителем и остальное получателем:

   payment_type = PAYMENT_TYPE_SPLIT_SENDER_RECIPIENT
   payment_split = {sender: 40}
   

{
    "delivery_time": 5400,
    "description": "Мед. препараты",
    "length": 500,
    "width": 500,
    "height": 300,
    "name": "Имя фамилия отправителя",
    "phone": "380500000001",
    "payment_type": 1,
    "custom_price": 0,
    "address": {
        "lat": 50.45180590,
        "long": 30.52591339,
        "city": "Киев",
        "street": "Крещатик улица",
        "number": "10",
        "flat": "24"
    },
    "pickup": {
        "comment": "Во дворе злой консьерж"
    },
    "deliveries": [
        {
            "name": "Имя фамилия получателя",
            "phone": "380500000002",
            "finance_type": 0,
            "redelivery_type": 0,
            "comment": "Комментарий по получателю",
            "address": {
                "lat": 50.45010990,
                "long": 30.52261900,
                "city": "Киев",
                "street": "Крещатик улица",
                "number": "20-22"
            },
            "parcels": [{
                "description": "Мед. препараты (Аспирин x 1)",
                "valuation": 40.00,
                "weight": 1000,
                "places": 1
            }]
        }
    ],
    "notify_url": "https://example.com/myproject/notify/34353"
}

Результат:

В случае успеха сервер возвращает id заказа и цену.

{
    "id": 10,
    "price": 80,
    "price_parts": {
        "delivery": 30, // Базовая стоимость доставки
        "fast": 40, // Надбавка за срочность
        "weight": 10, // Надбавка за вес
        "distance": 0, // Надбавка за расстояние
        "night": 20, // Надбавка за нерабочее время
        "holiday": 20, // Надбавка за выходной / праздник
        "cod": 0, // Надбавка за наложенный платеж (в случае передачи суммы наложенного платежа на счет iPOST клиента)
        "redeem": 0, // Надбавка на выкуп посылки курьером
        "valuation": 0, // Надбавка на оценочную стоимость
        "redelivery": 0, // Стоимость обратной доставки
        "custom": 50, // Свободная надбавка клиента
    },
    "balance": 510
}

При запросе с preview=1 поля в ответе следующие:

• price и price_parts могут быть null, когда не хватает данных для расчета стоимости
• поле min_delivery_time равно null при наличии более одного пункта доставки, а так же если не хватает данных для расчета времени доставки.
• поле tariff_type может быть null, если не хватает данных для определения типа доставки.

Минимальное время доставки: Система определяет для заказа минимальное время доставки исходя из расстояния. Время доставки — это значение, указанное в delivery_time или разница между deliveries[].time_to и pickup.time_from. В случае, если в заказе есть обратная доставка, то это так же разница между redelivery.time_to и deliveries[].time_from.

Коды ошибок:

• 44 — Нет привязанной карты (в случае наложенного платежа на карту клиента)
• 104 — Недостаточно средств на балансе
• 105 — Баланс ниже нуля
• 109 — Для заказа не нашлось подходящего тарифа
• 114 — Cумма оценочной стоимости больше допустимой
• 117 — Указаный адрес находится вне допустимых пределах карты
• 123 — Cумма оценочной стоимости для выкупа больше допустимой
• 124 — Время доставки слишком малое для этого маршрута
• 125 — Время обратной доставки слишком малое для этого маршрута
• 128 — Cумма оценочной стоимости для наложенного платежа на расчетный счет больше допустимой
• 130 — Значение age_check_dob не соответствует совершеннолетию на дату доставки.
• 132 — Опция отключена. В поле message ошибки есть текстовое описание
• 135 — Ваучер не найден
• 136 — Нельзя произвести оплату с баланса при использовании ваучера
• 139 — Платежная карта не найдена
• 140 — Неуспешный платеж
• + общие ошибки

Редактирование существующего заказа

Метод требует идентификации

PATCH /orders/{id}

Поля запроса:

FormOrderUpdatePickup : Object

FormOrderUpdateDelivery : Object

FormOrderUpdateParcel : Object

Результат:

В случае успеха сервер возвращает новую цену.

{
    "price": "80",
    "balance": "510"
}

Коды ошибок:

• 44 — в запросе указанные неизвестные или не соответствующие заказу id доставок или посылок
• 104 — Недостаточно средств на балансе
• 105 — Баланс ниже нуля
• 106 — запрос пытается отредактировать завершенную точку забора/доставки (STATUS_DONE, STATUS_CANCELED)
• 112 — статус у заказа не STATUS_NEW, STATUS_INWORK или STATUS_MODERATE
• 114 — Cумма оценочной стоимости больше допустимой
• 116 — запрос пытается отредактировать добавочную стоимость доставки, когда заказ не в статусе STATUS_NEW
• 118 — в заказе есть несколько получателей, или значение payment_type не соответствует одному из PAYMENT_TYPE_BALANCE, PAYMENT_TYPE_SENDER, PAYMENT_TYPE_RECIPIENT
• 123 — Cумма оценочной стоимости для выкупа больше допустимой
• 128 — Cумма оценочной стоимости для наложенного платежа на расчетный счет больше допустимой
• 132 — Опция отключена. В поле message ошибки есть текстовое описание
• 140 — Неуспешный платеж
• 142 — Ограничение редактирования заказа: в запросе указаны габариты/вес свыше допустимого в тарифе или суммарная разница изменения объявленной стоимости выше определенного лимита (лимит лучше уточнять у менеджера).
• + общие ошибки

Отмена заказа

Метод требует идентификации

Для отмены заказа:

POST /orders/{id}/cancel

Для оценки штрафа (без отмены):

POST /orders/{id}/cancel?preview=1

Где {id} - это id заказа.

Результат:

В случае успеха сервер возвращает размер штрафа.

{
    "fine": 0,
    "balance": "510"
}

Коды ошибок:

• + общие ошибки

Получить стикер для доставки

Метод требует идентификации

GET /stickers/{id}

Где {id} - это id доставки (order.deliveries[].id).

Результат:

В случае успеха сервер возвращает файл в формате pdf размером 100mm x 100mm. В случае, если запрашивается стикер с неизвестным id заказа, будет возвращена ошибка 44.

Коды ошибок:

• + общие ошибки

Оставить отзыв об исполнении заказа

Метод требует идентификации

POST /orders/{id}/review

Где {id} - это id заказа.

Поля запроса:

Поле text является обязательным при оценке 1 и 2. Если в этом случае оно не будет указано, то будет ошибка 131.

Если курьер еще не был назначен, или заказ был отменен курьером ранее, то в ответ придет ошибка 106.

Результат:

В случае успеха сервер отвечает с http кодом 200 без тела ответа.

Коды ошибок:

• 106 - нельзя оставить отзыв, т.к. курьер не назначен или заказ отменен клиентом.
• 131 - требуется добавить комментарий.
• + общие ошибки

Изменить отзыв об исполнении заказа

Метод требует идентификации

PATCH /orders/{id}/review

Описание смотреть в POST /orders/{id}/review, т.к. фактически является синонимом. Отличается только http-методом и только для семантической разницы.

Удалить отзыв об исполнении заказа

Метод требует идентификации

DELETE /orders/{id}/review

Где {id} - это id заказа.

Результат:

В случае успеха сервер отвечает с http кодом 200 без тела ответа.

Коды ошибок:

• + общие ошибки

Получить отзывы об исполнении заказа

Метод требует идентификации

GET /orders/{id}/reviews

Где {id} - это id заказа.

Результат:

В случае успеха сервер возвращает список значений в следующем виде:

{
    items: Review[],
}

{
    "items": [
        {
            "order_id": 123,
            "target_id": null,
            "rating": 5,
            "text": "Все ок, хорошо поработал, красафчег!",
            "created_at": 1459799323,
            "updated_at": 1459800411
        },
        {
            "order_id": 123,
            "target_id": 2,
            "rating": 5,
            "text": "Хороший курьер, быстро доставил!",
            "created_at": 1459898132,
            "updated_at": 1459898132
        }
    ]
}

Коды ошибок:

• + общие ошибки

Получить локацию курьера

Метод требует идентификации

GET /orders/{id}/tracking

Где {id} - это id заказа.

Результат:

В случае успеха сервер возвращает объект Location.

{
    "lat": 12.33333,
    "long": 0.13232
}

В случае, если запрашивается отзыв с неизвестным id заказа, придет ошибка 44.

Коды ошибок:

• 44 — Заказ с таким id не найден
• + общие ошибки

Получить все отзывы о курьере

Метод требует идентификации

GET /orders/{id}/courier/reviews

Где {id} - это id заказа.

Результат:

В случае успеха сервер возвращает список значений в следующем виде:

{
    items: CourierReview[],
    links: NavLinks,
    meta: NavMeta
}

{
    "items": [
        {
            "author_type": 1,
            "rating": 5,
            "text": "Все ок, хорошо поработал, красафчег!",
            "created_at": 1459799323,
            "updated_at": 1459800411
        },
        {
            "author_type": 2,
            "rating": 5,
            "text": "Хороший курьер, быстро доставил!",
            "created_at": 1459898132,
            "updated_at": 1459898132
        }
    ],
    "links": {
        "self": "http://api.ipost.local/public/v1/orders/1234/courier-reviews?page=1",
    },
    "meta": {
        "total_count": 2,
        "page_count": 1,
        "current_page": 1
    }
}

Коды ошибок:

• 106 - отзывы курьера не доступны, заказ находится не в работе.
• + общие ошибки

Отзывы на заказы

Получить все отзывы на заказы

Метод требует идентификации

GET /order-reviews

QueryString (GET) параметры:

GET /order-reviews?author_type=1

Результат:

В случае успеха сервер возвращает список значений в следующем виде:

{
    items: Review[],
    links: NavLinks,
    meta: NavMeta
}

{
    "items": [
        {
            "order_id": 123,
            "target_id": null,
            "rating": 5,
            "text": "Все ок, хорошо поработал, красафчег!",
            "created_at": 1459799323,
            "updated_at": 1459800411
        },
        {
            "order_id": 123,
            "target_id": 155,
            "rating": 5,
            "text": "Хороший курьер, быстро доставил!",
            "created_at": 1459898132,
            "updated_at": 1459898132
        }
    ],
    "links": {
        "self": "https://api.ipost.life/public/v1/order-reviews?page=1",
    },
    "meta": {
        "total_count": 2,
        "page_count": 1,
        "current_page": 1
    }
}

Коды ошибок:

• + общие ошибки

Edge: /cards (Платежные карты)

Получение списка платежных карт

Метод требует идентификации

GET /cards

Результат:

В случае успеха сервер возвращает список значений в следующем виде:

{
    items: PaymentCard[],
}

{
    "items": [
        {
            "id": 123,
            "type": "VISA",
            "number": "44****2154"
        },
        {
            "id": 250,
            "type": "MASTERCARD",
            "number": "51****3453"
        }
    ]
}

Коды ошибок:

• + общие ошибки

Уведомления об изменении статуса заказа

Если при отправке заказа добавить поле notify_url, то сервер будет делать POST-запрос на этот урл при изменении статуса заказа.

Аутентификация запроса

Для аутентификации запроса передается заголовок X-Signature, содержащий подпись запроса.

Алгоритм формирования подписи — HMAC-SHA256:

Signature = HMAC_SHA256(Key, Content)

Для аутентификации/авторизации запроса требуется локально сформировать подпись и сопоставить с переданной в заголовке.

Содержимое запроса

Содержимое запроса передается в формате JSON.

Структура содержимого следующая:

Поля type, order_id, status присутствуют в запросе всегда.

Поле reason присутствует в запросе только при наличии причины для статуса (актуально для “MODERATE”, “CANCELED”).

Поле courier присутствует в запросе только при назначении курьера на заказ! (То есть, при первом запросе со статусом INWORK).

Поле courier_location присутствует в запросе только когда на заказ назначен курьер.

Поле recreated_id может присутствовать в запросе только при отмене заказа (status = "CANCELED") или при статусе “курьер не найден” (status = "UNAPPLIED"), если оператор iPOST в это же время пересоздал заказ. В таком случае нужно считать новый заказ (recreated_id) замещающим текущий. Дальнейшие обновления будут приходить по новому заказу. Если пересоздания заказа не было, то поле отсутствует, заказ считается закрытым. Реализовано ввиду невозможности в настоящий момент переназначать курьера в заказе.

Поля pickup_update, delivery_updates, redelivery_update, codtoaccount_update присутствуют в запросе только при наличии обновления по соответствующим пунктам заказа.

За весь цикл работы с заказом может несколько раз приходить уведомление со значением status = "INWORK", но разными значениями пунктов (pickup_update, delivery_updates …).

Конечные статусы заказа - CANCELED (если нет recreated_id), UNAPPLIED (если нет recreated_id), DONE.

Заказ из статуса MODERATE может вновь стать активным (INWORK), отмененным (CANCELED) или “курьер не назначен” (UNAPPLIED).

Примеры

Назначен курьер на заказ

{
    "type":"order:status-update",
    "order_id":342,
    "status":"INWORK",
    "courier": {
        "idhash": "hpdjXS73QxwDCFH0TU0MYMz6hosY6AJj9/tymHya9H4",
        "name": "Соловьев Кирилл",
        "phone": "380501234567",
        "avatar": "https://api.ipost.life/path/to/image.jpg",
        "rating": 5.84,
        "orders_count": 320,
        "created_at": 1558264087
    },
    "courier_location": {
        "lat": 50.4502499,
        "long": 30.5222594
    }
}

Курьер получил отправление

{
    "type":"order:status-update",
    "order_id":342,
    "status":"INWORK",
    "pickup_update": {
        "status": "DONE"
    },
    "courier_location": {
        "lat": 50.4502499,
        "long": 30.5222594
    }
}

Курьер доставил отправление

{
    "type":"order:status-update",
    "order_id":342,
    "status":"DONE",
    "delivery_updates": [
        {
            "id": 849,
            "status": "DONE"
        }
    ],
    "courier_location": {
        "lat": 50.4502499,
        "long": 30.5222594
    }
}

В некоторых случаях может прийти уведомление без статуса назначения, сразу с завершенным заказом.

{
    "type":"order:status-update",
    "order_id":342,
    "status":"DONE",
    "courier_location": {
        "lat": 50.4502499,
        "long": 30.5222594
    }
}

Курьер отменяет заказ

{
    "type":"order:status-update",
    "order_id":342,
    "status":"MODERATE",
    "reason":"CANCELED_BY_COURIER",
    "courier_location": {
        "lat": 50.4502499,
        "long": 30.5222594
    }
}

Заказ стал на модерацию оператором.

Заказ отменен

{
    "type":"order:status-update",
    "order_id":342,
    "status":"CANCELED",
    "reason":"CANCELED_BY_COURIER",
    "courier_location": {
        "lat": 50.4502499,
        "long": 30.5222594
    }
}

Заказ полностью отменен.

Заказ отменен и пересоздан

{
    "type":"order:status-update",
    "order_id":342,
    "status":"CANCELED",
    "reason":"CANCELED_BY_COURIER",
    "recreated_id":345,
    "courier_location": {
        "lat": 50.4502499,
        "long": 30.5222594
    }
}

Типы данных

Order : Object

NB: Поле updated_at означает дату изменения полей заказа. Это значение не относится ко вложенным структурам.

OrderShort : Object

NB: Поле updated_at означает дату изменения полей заказа. Это значение не относится ко вложенным структурам.

OrderDelivery : Object

OrderRedelivery : Object

Обратная доставка

OrderCodToAccount : Object

Наложенный платеж на расчетный счет

OrderAddress : Object

OrderPickup : Object

OrderParcel : Object

PaymentCard : Object

Привязанная карта пользователя.

OrderStatusEnum : integer

Возможные значения:

OrderReasonEnum : integer

Возможные значения:

OrderPaymentTypeEnum : integer

OrderPaymentSplit : Object

Этот объект динамический - количество полей в нем может меняться. Описание возможных полей:

OrderTariffTypeEnum : integer

Возможные значения:

OrderTargetStatusEnum : integer

Возможные значения:

OrderTargetReasonEnum : integer

Возможные значения:

OrderTargetPaymentTypeEnum : integer

OrderCodToAccountStatusEnum : integer

Возможные значения:

OrderDeliveryFinanceTypeEnum : integer

Дополнительные финансовые операции по доставке.

Возможные значения:

OrderDeliveryRedeliveryTypeEnum : integer

Возможные значения:

CourierInfo : Object

CourierReview : Object

CourierReviewAuthorTypeEnum : integer

Возможные значения:

Image : Object

Review : Object

ReviewMeta : Object

Location : Object

NotifyOrderStatusEnum : string

NotifyOrderReasonEnum : string

NotifyPickupUpdate : Object

NB: поле reason присутствует только при наличии причины установки статуса (актуально для “CANCELED”). NB: поле reason_custom присутствует только если reason = "CUSTOM".

NotifyDeliveryUpdate : Object

NB: поле reason присутствует только при наличии причины установки статуса (актуально для “CANCELED”). NB: поле reason_custom присутствует только если reason = "CUSTOM".

NotifyRedeliveryUpdate : Object

NB: поле reason присутствует только при наличии причины установки статуса (актуально для “CANCELED”). NB: поле reason_custom присутствует только если reason = "CUSTOM".

NotifyCodToAccountUpdate : Object

NotifyOrderTargetStatusEnum : string

NotifyOrderTargetReasonEnum : string

NotifyCodToAccountStatusEnum : string

NavLinks : Object

Данный объект представляет словарь (Map<String, String>) ссылок навигации перечисления.

Возможные пары:

Все ключи, кроме self могут отсутствовать. Например, если все элементы укладываются в одну страницу, будет существовать только self. В случае, если следующей или предыдущей страницы нет, будут отсутствовать next (и last) или prev (и first) соответственно.

NavMeta : Object

Данный объект представляет словарь (Map<String, integer>) метаинформации перечисления.

Возможные пары:

Errors

Внимание: В данный момент коды ошибок не стандартизированны, и могут измениться в ходе разработки API. Потому рекомендуется создать список констант на клиенте и использовать их при разработке клиента, чтоб в дальнейшем без проблем можно было их изменить.

Список кодов ошибок

Ошибка 0

Когда приходит эта ошибка, нужно просто показать сообщение из нее (message) пользователю.

Ошибка 1

Запрашиваемая версия API закрыта. Необходимо обновить приложение. Можно показать пользователю поп-ап с текстом типа “Для продолжения работы требуется обновить приложение” и кнопочкой “Обновить”, нажатие на которую ведет на источник установки приложения (e.g. плей-маркет).

Ошибка 100

С этой ошибкой есть дополнительное поле - errors

[
    {
        "field": {field_name},
        "message": {error_message}
    }
]

где {field_name} - (string) имя поля, {error_message} - (string) текстовое описание ошибки.

Ошибки 104, 105

С этой ошибкой есть дополнительное поле:

• balance (float) - текущая сумма на балансе пользователя

Ошибка 109

С этой ошибкой есть дополнительные поля:

• maxLength (integer) - Максимальная длина (мм) отправления NB: Это значение может изменяться!
• maxWidth (integer) - Максимальная ширина (мм) отправления NB: Это значение может изменяться!
• maxHeight (integer) - Максимальная высота (мм) отправления NB: Это значение может изменяться!
• maxWeight (integer) - Максимальный вес (г) отправления NB: Это значение может изменяться!

Ошибка 114

С этой ошибкой есть дополнительные поля:

• max (float) - Максимальное допустимая сумма оценочной стоимости. NB: Это значение может изменяться!

Ошибка 117

Допустимые пределы карты на данный момент - Киев и Киевская область (по версии Google Maps).

С этой ошибкой есть дополнительные поля:

• reason (string|null) - Текстовое описание ошибки, которое можно показать пользователю. NB: Этого поля может вовсе не быть!
• lat (float) - Гео-координаты адреса - latitude NB: Это значение может изменяться!
• long (float) - Гео-координаты адреса - longitude NB: Это значение может изменяться!

Ошибка 123

С этой ошибкой есть дополнительные поля:

• max (float) - Максимальное допустимая сумма для выкупа посылки. NB: Это значение может изменяться!

Ошибка 124

С этой ошибкой есть дополнительные поля:

• min (integer) - Минимальное допустимое время доставки. NB: Это значение может изменяться!

Ошибка 125

С этой ошибкой есть дополнительные поля:

• min (integer) - Минимальное допустимое время обратной доставки. NB: Это значение может изменяться!

Ошибка 128

С этой ошибкой есть дополнительные поля:

• max (float) - Максимальное допустимая сумма наложенного платежа. NB: Это значение может изменяться!

Важная заметка касательно обновления 1.10

В обновлении 1.10 был переработан механизм определения тарифа для заказа. Теперь ошибка 119 будет встречаться только при создании мульти-заказа.

В виду этого изменения было убрано поле delivery_type из заказа. Вместо него теперь есть поле tariff_type, определяющее тип тарифа, который был применен к конкретному заказу. Для создания заказа типа “доставить за XX минут” можно использовать новое поле delivery_time.

Для обратной совместимости значение delivery_type все еще обрабатывается в форме и возвращается методами получения списка заказов/информации о заказе, но с корректировками: * в форме создания заказа: - значения DELIVERY_TYPE_REGULAR, DELIVERY_TYPE_INTERCITY и DELIVERY_TYPE_MULTI игнорируются. Тип тарифа (по городу, межгород, мульти) определяется автоматически на основании данных в запросе. - значения DELIVERY_TYPE_FAST30, DELIVERY_TYPE_FAST60, DELIVERY_TYPE_FAST90, DELIVERY_TYPE_FAST120 преобразовываются в соответствующее значение delivery_time, тип тарифа определяется автоматически на основании данных в запросе. * в методах получения списка заказов и подробной информации о заказе данное значение частично эмулируется.

В будущих версиях API поддержка значения delivery_type будет окончательно прекращена. Рекомендуется как можно скорее начать использовать новые значения tariff_type и delivery_time.

На тестовом сервере поле delivery_type не поддерживается.

Changelog

1.20

• Добавлено поле id в структуру OrderParcel.
• Добавлена ошибка 142 (Ограничение редактирования заказа).
• Метод редактирования объявленной стоимости (PATCH /orders/{id}) расширен до частичного редактирования заказа.

1.19

• Добавлен метод получения стикера для доставки GET /stickers/{id}.

1.18

• При создании заказа с мульти-доставкой (несколько получателей) теперь можно указывать пункты доставки в разных населенных пунктах.
• Значение MULTI переименовано в MULTI_INCITY в перечислении OrderTariffTypeEnum.
• Добавлено значение MULTI_INTERCITY в перечисление OrderTariffTypeEnum.
• Удалена ошибка 119 (Адрес отправителя и адрес получателя находятся в разных населенных пунктах).

1.17

• Добавлено поле recreated_id в структуру Order.

1.16

• Добавлено поле payment_card_id в запрос метода создания заказа (POST /orders). Так же добавлены ошибки 139 (Платежная карта не найдена) и 140 (Неуспешный платеж).
• Добавлено значение REASON_PAYMENT_FAILED в перечисление OrderReasonEnum.
• Добавлено значение PAYMENT_FAILED в перечисление NotifyOrderReasonEnum.
• Добавлено значение PAYMENT_TYPE_CARD в перечисления OrderTargetPaymentTypeEnum и FormOrderTargetPaymentTypeEnum.
• Добавлены значения PAYMENT_TYPE_CARD, PAYMENT_TYPE_SPLIT_CARD_AND_SENDER, PAYMENT_TYPE_SPLIT_CARD_AND_RECIPIENT в перечисления OrderPaymentTypeEnum и FormOrderPaymentTypeEnum.
• Добавлено поле card в структуру FormOrderPaymentSplit.

1.15

• В структуру Review добавлено поле order_id.
• Добавлен метод получения всех отзывов на заказы GET /order-reviews.
• Добавлен метод вывода списка привязанных платежных карт (GET /cards)
• Добавлено поле cod_card_id в структуру FormOrderDelivery.
• Добавлена структура PaymentCard.

1.14

• В структуре Review добавлено поле target_id.
• В структуре Order удалено поле review и добавлено поле review_meta.
• Добавлена структура ReviewMeta.
• Добавлен метод получения отзывов о выполнении заказа (GET /orders/{id}/reviews).
• Добавлен метод получения всех отзывов о курьере (GET /orders/{id}/courier/reviews).
• Добавлена структура CourierReview.
• Добавлено перечисление CourierReviewAuthorTypeEnum.

1.13

• Максимальное значение delivery_time в методе создания заказа (POST /orders) увеличено до 10800 (3 часа)

1.12

• Добавлено поле voucher_code в запрос метода создания заказа (POST /orders). Так же добавлены ошибки 135 (Ваучер не найден) и 136 (Нельзя произвести оплату заказа с баланса при использовании ваучера).
• Добавлена аутентификация уведомлений об изменении статуса заказа (на notify_url)

1.11

• Добавлена проверка возраста получателя:
  • поле personal_id_check_required в структуре FormOrderDelivery @ метод создания заказа (POST /orders)
  • поле personal_id_check_value в структуре FormOrderDelivery @ метод создания заказа (POST /orders)
  • поле personal_id_check_required в структуре OrderDelivery
  • значение 6 (REASON_PERSONAL_ID_CHECK_NOT_PASSED) в перечисление OrderTargetReasonEnum причин статуса пункта доставки
  • значение PERSONAL_ID_CHECK_NOT_PASSED в перечисление NotifyOrderTargetReasonEnum причин статуса пункта доставки в уведомлении на notify_url

1.10

• Изменения в методе создания заказа (POST /orders):
  • удалено поле delivery_type из формы запроса
  • добавлено поле delivery_time в форму запроса
  • удалены значения delivery_time_from и delivery_time_to из структуры ответа при запросе с preview=1
  • добавлено значение tariff_type в структуру ответа при запросе с preview=1
  • ошибка 119 теперь актуальна только для мульти-доставок
• В методе изменения добавочной стоимости существующего заказа (PATCH /orders/{id}) изменены условия — в заказе должен быть только один пункт доставки (вместо проверки delivery_type == DELIVERY_TYPE_MULTI, т.к. поле delivery_type удалено).
• В структуре Order удалено поле delivery_type и добавлены поля tariff_type и delivery_time.
• В структуре OrderShort удалено поле delivery_type и добавлено поле tariff_type.
• Удалено перечисление OrderDeliveryTypeEnum и добавлено новое — OrderTariffTypeEnum.

1.9

• В методах создания/обновления отзыва об исполнении заказа (POST /orders/{id}/review и PATCH /orders/{id}/review) поле text стало условно обязательным, добавлена ошибка 131.
• Удалено значение 5 (FINANCE_TYPE_REDEEM_RECIPIENT_NORESERVE) из перечисления OrderDeliveryFinanceTypeEnum и из перечисления FormOrderDeliveryFinanceTypeEnum, таким образом, выкупа отправления с компенсацией получателем без гарантирования (со стороны клиента) более нет. Если будет передано значение 5, оно будет неявно преобразовано в 2 (FINANCE_TYPE_REDEEM_RECIPIENT).
• В методе создания заказа (POST /orders) отключены опции наложенного платежа на баланс и карту (значения 3 и 6 поля finance_type в FormOrderDelivery).
• Добавлена ошибка 132.

1.8

• Добавлено поле age_check_dob в форму FormOrderDelivery метода создания заказа (POST /orders).
• Добавлена ошибка 130 в метод создания заказа (POST /orders).
• Добавлено поле age_check_dob в структуру OrderDelivery.

1.7

• Теперь в случаях, когда не был вовремя назначен курьер, заказ переходит на модерирование вместо конечного статуса UNAPPLIED. После этого курьер может быть назначен вручную (переход в статус INWORK), или заказ может быть отменен (переход в статус CANCELED), или подтвержден, что курьер не найден (переход в статус UNAPPLIED). В последних двух случаях заказ может быть пересоздан с recreated_id в уведомлении.
• Добавлено значение 6 в перечисление OrderReasonEnum.
• Добавлено значение COURIER_NOT_ASSIGNED в перечисление NotifyOrderReasonEnum.

1.6

• Добавлено поле courier_location в запросе на notify_url.

1.5

• Добавлены значения 4 и 5 в перечисление OrderReasonEnum.
• Добавлены значения MANUAL_REVIEW и FRAUD в перечисление NotifyOrderReasonEnum.
• Изменена максимальная длина поля notify_url в запросе создания заказа POST /orders до 1024.

1.4

• В метод создания заказа (POST /orders) добавлена ошибка 128.
• Добавлено описание ошибки 128.
• Добавлена проверка возраста получателя:
  • поле age_check_required в структуре FormOrderDelivery
  • поле age_check_required в структуре OrderDelivery
  • значение 5 (REASON_AGE_CHECK_NOT_PASSED) в перечисление OrderTargetReasonEnum причин статуса пункта доставки
  • значение AGE_CHECK_NOT_PASSED в перечисление NotifyOrderTargetReasonEnum причин статуса пункта доставки в уведомлении на notify_url

1.3

• Добавлены поля pickup_update, delivery_updates, redelivery_update, codtoaccount_update в запросе на notify_url.
• Добавлены типы NotifyPickupUpdate, NotifyDeliveryUpdate, NotifyRedeliveryUpdate, NotifyCodToAccountUpdate, NotifyOrderStatusEnum, NotifyOrderReasonEnum, NotifyOrderTargetStatusEnum, NotifyOrderTargetReasonEnum, NotifyCodToAccountStatusEnum.
• Добавлены перечисления NotifyPickupUpdate, NotifyDeliveryUpdate, NotifyRedeliveryUpdate, NotifyCodToAccountUpdate.
• Добавлены примеры запросов на notify_url.

1.2.2

• Добавлено поле origin_id в структуру Order.
• Добавлено поле recreated_id в запросе на notify_url.

1.2.1

• Добавлено поле idhash в структуру CourierInfo.
• Добавлено поле courier в запросе на notify_url.

1.2

• Добавлено значение 7 в перечисление OrderDeliveryFinanceTypeEnum
• Добавлена структура OrderCodToAccount в структуру Order (поле codtoaccount)
• Добавлено перечисление OrderCodToAccountStatusEnum
• Изменения в методе создания заказа (POST /orders):
  • Добавлено поле запроса codtoaccount
  • Добавлена структура FormOrderCodToAccount
  • Добавлено значение 7 в перечисление формы FormOrderDeliveryFinanceTypeEnum, а так же в этой секции добавлен разъяснительный текст касательно этого значения.
• Удалено поле company_name из структуры CourierInfo, т.к. не используется.
• Добавлено поле order_number в форме FormOrderDelivery метода POST /orders.
• Добавлено поле order_number в структуру client::OrderDelivery.

1.1

• Добавлено поле notify_url в тело запроса POST /orders.