P2P Motion - Public API

Base URI

http://demo.api.p2p-motion.com/api/v1

Кількість запитів до даного API, наразі обмежується до n запитів на годину за одним API Key, де n = квоті в АРІ-ключі. Кожен АРI-ключ містить наступні API-scopes: orders, predictions та geo-coding. Кожен із наведених scopes, як правило, обмежений власною квотою на запити. Квоти в різних scopes можуть не збігатись. Наприклад, для orders за АРІ-ключем може бути закріплено 300 запитів на годину, тоді як для geo-coding лише 100.

Інформація щодо поточних обмежень міститься в заголовках відповіді кожного запиту. Відповідні заголовки:

RateLimit-Limit: Кількість запитів, які можна виконати за годину часу (завжди сталий показник).
RateLimit-Remaining: Кількість запитів, які залишились до вичерпання квоти. Перегляньте інформацію, наведену нижче, про те, як закінчується термін дії кожного окремого запиту.
RateLimit-Reset: Час, коли закінчиться найстаріший запит у форматі Unix epoch time. Див. нижче, щоб отримати додаткову інформацію про те, як закінчується термін дії обмежень кожного окремого запиту.

Поки обсяг RateLimit-Remaining перевищує 0, Ви зможете виконувати додаткові запити.

Важливо розуміти спосіб, за яким виконані запити виключаються з ліміту. Замість того, щоб підраховувати всі запити протягом години - кожен окремий запит має власний таймер. Це означає, що кожен запит сприяє збільшенню кількості «RateLimit-Remaining» протягом однієї години після запиту. Коли таймер цього запиту закінчується, він більше не враховується до ліміту запитів.

Це має наслідки для значення заголовка “RateLimit-Reset”. Оскільки весь ліміт на запити не скидається одночасно, значення цього заголовка містить час, коли закінчиться найстаріший із виконаних запитів.

Якщо значення “RateLimit-Remaining” досягає нуля, наступні запити отримають код помилки 429, доки не відбудеться поновлення ліміту.

Create order

POST /orders/

Get orders

GET /orders/

Get order by id

GET /orders/{ORDER_ID}/

POST /orders/

Створює замовлення і додає його на чергу до опрацювання.
За замовчуванням, система протягом 2-х хвилин після створення замовлення, шукатиме можливість доправити посилку одним із вільних кур’єрів, проте, якщо вільного кур’єра знайти не вдастся — оголошення буде одразу помічено як “відхилене” (зі статус-кодом 3 в полі info.status.code). При цьому, якщо оголошення буде закріплено на опрацювання одним із кур’єрів — статус оголошення відповідно змінитья на 1 (в опрацюванні), а саме оголошення в полі courier міститиме дані кур’єра, який займається транспортуванням.

Для отримання даних відносно оголошення рекомендовано запитувати його поточний статус з інтервалом 7-10 сек. Задля економії квоти на запити, перевіряти статус оголошення після його створення рекомендовано не раніше, як через 30-40 сек., оскільки вкрай малоімовірним є зміна статусу оголошення в коротший проміжок часу.

Request headers

Content-Type

string required

Example:

application/json

X-API-Key

string required

Min length: 128

Max length: 128

Example:

5P0g24jzva3ylSNFOcnwdCLsSwkI8ZUzQfe0YmAyQlYgBDjkSYzcAEKCtf7hoy7Q8JAxhO4xINZqzb9Qqzk8B6GdHwC1asqYoWhAwFGnb1zwHZT0dJLFGWUkxqdiGl6t

Request body

Object

sender

Object

name

string nullable

Ім’я відправника, або коротка назва точки відправки.

Max length: 32

Example:

Serhii

phone

string

Контактний номер телефону отримувача у форматі 0КК1122333, або +380КК1122333.

Example:

+380508242618

Object nullable

Група полів, що описує відправника в мережі Telegram.

user_id

integer

ID користувача в системі Telegram, для прямого зв`язку кур’єра з відправником.

Example:

189900134

username

string

Ім’я користувача в системі Telegram, яке буде відображено в інтерфейсі кур’єра (без символу @).

Не допускається використання довільного username.
Допустимим є лише дійсний username з мережі Telegram. Використання довільного username може пошкодити навігацію в додатках Telegram та відображення в супутніх інтерфейсах системи.

Max length: 128

Example:

meketiuk

receiver

Object

name

string nullable

Ім’я відправника, або коротка назва точки призначення.

Max length: 32

Example:

Serhii

phone

string

Контактний номер телефону отримувача у форматі 0КК1122333, або +380КК1122333.

Example:

+380508242618

Object nullable

Група полів, що описує відправника в мережі Telegram.

user_id

integer

ID користувача в системі Telegram, для прямого зв`язку кур’єра з отримувачем.

Example:

189900134

username

string

Ім’я користувача в системі Telegram, яке буде відображено в інтерфейсі кур’єра. (без символу @)

Не допускається використання довільного username.
Допустимим є лише дійсний username з мережі Telegram. Використання довільного username може пошкодити навігацію в додатках Telegram та відображення в супутніх інтерфейсах системи.

Max length: 128

Example:

meketiuk

info

Object

Параметри доставки.

origin

Object

Параметри відправки посилки.

date_time

string

Дата та час доставки замовлення у форматі ISO 8601.
Не може бути меншаю, ніж поточний час + 5 хв., інакше – буде повернуто помилку.

NOTE: Якщо дата відправки info.origin.date_time та дата доставки info.destination.date_time однакові – замовлення вважатиметься таким, що повинно бути доставлене так швидко, як лише можливо (en. ASAP).

Example:

2015-02-20T19:29:31.238Z

location

Object

Група полів, що описує розташування відправника.

lat

number nullable

Географічна широта у форматі UTM.
(на даний момент обмежена адм. регіоном Чернівецької обл.)

Example:

48.2857435

lng

number nullable

Географічна довгота у форматі UTM.
(на даний момент обмежена адм. регіоном Чернівецької обл.)

Example:

25.9380153

formatted_address

string nullable

Форматована адреса відправника у форматі, що повертається Google geocoding для вказаної місцевості. Підтримуються, також, довільні способи опису адреси (довільний порядок компонентів, орфографічні помилки, тощо).

NOTE: Важливо щоб в результаті зворотного геокодування даного поля, унікально ідентифікувалось не більше однієї локації, інакше – буде повернуто повідомлення про помилку парсингу адреси.

NOTE: Якщо задано lat та lng, тоді formatted_address може бути опціональним. Інакше – дане поле є обов’язковим.

Max length: 512

Example:

вулиця Шевченка, 28, Чернівці, Чернівецька область, Україна, 58000

destination

Object

Параметри отримання посилки.

date_time

string

Дата та час доставки замовлення у форматі ISO 8601.
Не може бути меншою, ніж час відправки + 10 хв, інакше – буде повернуто помилку.

NOTE: Якщо дата відправки info.origin.date_time та дата доставки info.destination.date_time однакові – замовлення вважатиметься таким, що повинно бути доставлене так швидко, як лише можливо (en. ASAP).

Example:

2015-02-20T19:29:31.238Z

location

Object

Група полів, що описує розташування отримувача.

lat

number nullable

Географічна широта у форматі UTM.
(на даний момент обмежена адм. регіоном Чернівецької обл.)

Example:

48.2857435

lng

number nullable

Географічна довгота у форматі UTM.
(на даний момент обмежена адм. регіоном Чернівецької обл.)

Example:

25.9380153

formatted_address

string nullable

Форматована адреса отримувача у форматі, що повертається Google geocoding для вказаної місцевості. Підтримуються, також, довільні способи опису адреси (довільний порядок компонентів, орфографічні помилки, тощо).

NOTE: Важливо щоб в результаті зворотного геокодування даного поля, унікально ідентифікувалось не більше однієї локації, інакше – буде повернуто повідомлення про помилку парсингу адреси.

NOTE: Якщо задано lat та lng, тоді formatted_address може бути опціональним. Інакше – дане поле є обов’язковим.

Max length: 512

Example:

вулиця Шевченка, 28, Чернівці, Чернівецька область, Україна, 58000

escrow

Object nullable

Зворотній супровід коштів.
Використовується у випадку, коли кур’єр повинен доправити оплату за передану ним посилку назад до відправника.

cost

Object

amount

number

Сума повернення – обсяг коштів, що підлягає поверненню.

Example:

45.5

currency_code

string

Код валюти у форматі ISO 4217, в якій проходить операція. На даний момент, підтримується лише UAH, USD, EUR.

Max length: 4

Example:

UAH

priority_type

string

Пріоритет виконання доставки

Enumeration:

0

Одразу після доставки
У випадку використання – одразу генерується замовлення на аналоігчний маршрут в зворотному напрямі.
Тарифікація здійснюється як за подвійну поїздку.

1

В кінці дня
Кошти можуть бути повернені не пізніше як 18:00 поточного дня. До цього часу, кур’єр може оптимально розподілити маршрут для зменшення витрат.

Вартість послуги:

Безкоштовно, якщо кур’єру довелось повертатись в місце відправки за наст. замовленням, або в близьку іколиці.
По вартості поїздки від пункту призначення замовлення в напрямі пункту отримання замовлення кур’єром (зворотна доставка).

2

За 3 дні

Аналогічно до опції 1, проте час на досвтавку коштів складає 3 дні.

3

Безкоштовний безготівковий переказ на картку/рахунок відправника [ОЧІКУЄ ВПРОВАДЖЕННЯ]

memo

string nullable

Опціональні нотатки.
Можуть використовуватись для вказання відправником важливої для кур’єра інформації, наприклад: номеру під’їзда, квартири, комбінацію кодового замка, тощо.

Max length: 256

Examples

Приклад запиту із вказанням даних з мережі Telegram та із опціює “зворотня доставка коштів”.

{
    "sender": {
        "name": "Serhii",
        "phone": "+380508242618",
        "telegram": {
            "user_id": 189900134,
            "username": "meketiuk"
        }
    },
    "receiver": {
        "name": "Serhii",
        "phone": "+380508242618",
        "telegram": {
            "user_id": 189900134,
            "username": "meketiuk"
        }
    },
    "info": {
        "origin": {
            "date_time": "2015-02-20T19:29:31.238Z",
            "location": {
                "lat": 48.2857435,
                "lng": 25.9380153,
                "formatted_address": "вулиця Шевченка, 28, Чернівці, Чернівецька область, Україна, 58000"
            }
        },
        "destination": {
            "date_time": "2015-02-20T19:29:31.238Z",
            "location": {
                "lat": 48.2857435,
                "lng": 25.9380153,
                "formatted_address": "вулиця Шевченка, 28, Чернівці, Чернівецька область, Україна, 58000"
            }
        },
        "escrow": {
            "cost": {
                "amount": 45.5,
                "currency_code": "UAH"
            },
            "priority_type": "3"
        },
        "memo": ""
    }
}

Приклад запиту без вказання даних з мережі Telegram та без зворотньої доставки коштів.

{
    "sender": {
        "name": "Serhii",
        "phone": "+380508242618"
    },
    "receiver": {
        "name": "Serhii",
        "phone": "+380508242618"
    },
    "info": {
        "origin": {
            "date_time": "2015-02-20T19:29:31.238Z",
            "location": {
                "lat": 48.2857435,
                "lng": 25.9380153,
                "formatted_address": "вулиця Шевченка, 28, Чернівці, Чернівецька область, Україна, 58000"
            }
        },
        "destination": {
            "date_time": "2015-02-20T19:29:31.238Z",
            "location": {
                "lat": 48.2857435,
                "lng": 25.9380153,
                "formatted_address": "вулиця Шевченка, 28, Чернівці, Чернівецька область, Україна, 58000"
            }
        },
        "memo": ""
    }
}

Responses

201 Created

400 Bad Request

Запит не містить обов’язкових параметрів

403 Unauthorized or scope-quota limit reached

Запит не містить Headers: X-API-Key, він є не коректним, або ж досягнуто квоти на запити для даного scope.

GET /orders/

Повертає перелік замовлень, зареєстрованих за вказаним API Key.

Request parameters

courier_id

string optional

id користувача в системі P2P Motion

status_code

integer optional

Enumeration:

0

В черзі на опрацювання

1

Виконується

2

Виконано

3

Відхилено

Example:

0

from_date_time

string date-time optional

Фільтр по даті та часу створення замовлення у форматі ISO 8601.

WARN: Обов’язковий параметер якщо to_date_time передано в запиті.

Example:

2015-05-26T19:29:31:00+03:00

to_date_time

string date-time optional

Фільтр по даті та часу створення замовлення у форматі ISO 8601.

WARN: Обов’язковий параметер якщо from_date_time передано в запиті.

Example:

2015-05-26T19:29:31:00+03:00

Request headers

Content-Type

string required

Example:

application/json

X-API-Key

string required

Min length: 128

Max length: 128

Example:

5P0g24jzva3ylSNFOcnwdCLsSwkI8ZUzQfe0YmAyQlYgBDjkSYzcAEKCtf7hoy7Q8JAxhO4xINZqzb9Qqzk8B6GdHwC1asqYoWhAwFGnb1zwHZT0dJLFGWUkxqdiGl6t

Responses

200 OK

Body

Array of Order

400 Bad Request: Invalid status code

400 Bad Request: Invalid date

404 Not Found: Courier

403 Unauthorized or scope-quota limit reached

Запит не містить Headers: X-API-Key, він є не коректним, або ж досягнуто квоти на запити для даного scope.

GET /orders/{ORDER_ID}/

Повертає перелік замовлень, зареєстрованих за вказаним API Key.

Path variables

ORDER_ID

string required

Request headers

Content-Type

string required

Example:

application/json

X-API-Key

string required

Min length: 128

Max length: 128

Example:

5P0g24jzva3ylSNFOcnwdCLsSwkI8ZUzQfe0YmAyQlYgBDjkSYzcAEKCtf7hoy7Q8JAxhO4xINZqzb9Qqzk8B6GdHwC1asqYoWhAwFGnb1zwHZT0dJLFGWUkxqdiGl6t

Responses

200 OK

Body

Order

403 Unauthorized or scope-quota limit reached

Запит не містить Headers: X-API-Key, він є не коректним, або ж досягнуто квоти на запити для даного scope.

Format address

GET /geocoding/format-address/

Повертає форматовану адресу, що відповідає отриманій адресі address, або ж координатам (lat, lng). У випадку, якщо передана адреса не може бути унікально ідентифікована – буде повернуто декілька припущень.

Request parameters

lat

number double optional

Географічна широта у форматі UTM.

(на даний момент обмежена адм. регіоном Чернівецької обл.)
INFO: Обов’язковий параметр, якщо address відсутній в запиті.

Example:

48.2857435

lng

number double optional

Географічна довгота у форматі UTM.

(на даний момент обмежена адм. регіоном Чернівецької обл.)
INFO: Обов’язковий параметр, якщо address відсутній в запиті.

Example:

25.9380153

address

string optional

Адреса у форматі, що повертається Google geocoding для вказаної місцевості.
Підтримуються, також, довільні способи опису адреси (довільний порядок компонентів, орфографічні помилки, тощо).
INFO: Обов’язковий параметр, якщо lat та lng не передаються.

Example:

Шевченка 28

language

string optional

Enumeration:

ua

Локалізувати видачу укр. мовою.

ru

Локалізувати видачу рос. мовою.
Для деяких регіонів, відсутня рос. локалізація.

Default:

ru

Request headers

Content-Type

string required

Example:

application/json

X-API-Key

string required

Min length: 128

Max length: 128

Example:

5P0g24jzva3ylSNFOcnwdCLsSwkI8ZUzQfe0YmAyQlYgBDjkSYzcAEKCtf7hoy7Q8JAxhO4xINZqzb9Qqzk8B6GdHwC1asqYoWhAwFGnb1zwHZT0dJLFGWUkxqdiGl6t

Responses

200 OK

Body

Array of Location

404 Not Found

Передана адреса, або координати не можуть бути декодовані.

400 Bad Request

Деякі із параметрів вказано у невідповідному форматі. response.message міститиме більше інформації.

403 Unauthorized or scope-quota limit reached

Запит не містить Headers: X-API-Key, він є не коректним, або ж досягнуто квоти на запити для даного scope.

Get cost prediction

GET /predictions/cost/

Повертає вартість виконання замовлення найближчим кур’єром на основі переданих вхідних даних. Використовується для прогнозування кінцевої вартості замовлення для клієнта.

Request parameters

origin_address

string optional

Адреса відправника у форматі, що повертається Google geocoding для вказаної місцевості. Підтримуються, також, довільні способи опису адреси (довільний порядок компонентів, орфографічні помилки, тощо).

NOTE: Важливо щоб в результаті зворотного геокодування даного поля, унікально ідентифікувалось не більше однієї локації, інакше – буде повернуто повідомлення про помилку парсингу адреси.

NOTE: Якщо задано lat та lng, тоді origin_formatted_address може бути опціональним. Інакше – дане поле є обов’язковим.

Example:

вулиця Шевченка, 28, Чернівці, Чернівецька область, Україна, 58000

destination_address

string optional

Адреса отримувача у форматі, що повертається Google geocoding для вказаної місцевості. Підтримуються, також, довільні способи опису адреси (довільний порядок компонентів, орфографічні помилки, тощо).

NOTE: Важливо щоб в результаті зворотного геокодування даного поля, унікально ідентифікувалось не більше однієї локації, інакше – буде повернуто повідомлення про помилку парсингу адреси.

NOTE: Якщо задано lat та lng, тоді destiantion_formatted_address може бути опціональним. Інакше – дане поле є обов’язковим.

Example:

вулиця Шевченка, 28, Чернівці, Чернівецька область, Україна, 58000

Request headers

Content-Type

string required

Example:

application/json

X-API-Key

string required

Min length: 128

Max length: 128

Example:

5P0g24jzva3ylSNFOcnwdCLsSwkI8ZUzQfe0YmAyQlYgBDjkSYzcAEKCtf7hoy7Q8JAxhO4xINZqzb9Qqzk8B6GdHwC1asqYoWhAwFGnb1zwHZT0dJLFGWUkxqdiGl6t

Object

id

integer int64

sender

User

receiver

User

courier

User

info

Info

Methods: Get order by id Get orders

Object

id

integer int64

P2P Motion user idenfier

name

string

Example:

Serhii

phone

string

Example:

+380508241618

location

Location

Object nullable

user_id

integer int64

Example:

189900134

username

string

Example:

meketiuk

roles

Array

Unique items: YES

Example:

[
    "Client"
]

string

Enumeration:

Client

Courier

Business

Types: Order

Параметри доставки замовлення.

Object

origin

Object

Параметри відправки посилки.

date_time

string date-time

Дата та час доставки замовлення у форматі ISO 8601.
Не може бути меншаю, ніж поточний час + 5 хв., інакше – буде повернуто помилку.

NOTE: Якщо дата відправки info.origin.date_time та дата доставки info.destination.date_time однакові – замовлення вважатиметься таким, що повинно бути доставлене так швидко, як лише можливо (en. ASAP).

Example:

2015-05-26T19:29:31:00+03:00

location

Location

Група полів, що описує розташування відправника.

destination

Object

Параметри отримання посилки.

date_time

string date-time

Дата та час доставки замовлення у форматі ISO 8601.
Не може бути меншою, ніж час відправки + 10 хв, інакше – буде повернуто помилку.

NOTE: Якщо дата відправки info.origin.date_time та дата доставки info.destination.date_time однакові – замовлення вважатиметься таким, що повинно бути доставлене так швидко, як лише можливо (en. ASAP).

Example:

2015-05-26T19:29:31:00+03:00

location

Location

Група полів, що описує розташування отримувача.

cost

Cost read-only

Вартість виконання замовлення кур’єром.

escrow

Escrow nullable

status

Object read-only

code

integer

Enumeration:

0

В черзі на опрацювання

1

Опрацьовується

2

Доставлено

3

Відхилено

message

string

Використовується в поєднанні з кодом 3 для пояснення причини відхилення.

created

string date-time read-only

Дата та час створення замовлення у форматі ISO 8601.

Example:

2015-05-26T19:29:31:00+03:00

memo

string

Опціональні нотатки.
Можуть використовуватись для вказання відправником важливої для кур’єра інформації, наприклад: номеру під’їзда, квартири, комбінацію кодового замка, тощо.

Max length: 256

Types: Order

Object

lat

number double

Географічна широта у форматі UTM.

Example:

48.2857435

lng

number double

Географічна довгота у форматі UTM.

Example:

25.9380153

address

string

Адреса, введена користувачем.
Зберігається в незмінному вигляді, оскільки в процесі обробки можуть бути втрачені деякі компоненти, які користувач вказав, наприклад, номер будинку.

Example:

Шевченка 28

short_address

string

Скорочена форматована адреса.
Призначена для короткої інформативної видачі.

Example:

вул. Шевченка, 28, Чернівці, Чернівецька обл.

formatted_address

string

Повна ареса у форматі, що відповідає прийнятому в поточній місцевості.

Example:

вулиця Шевченка, 28, Чернівці, Чернівецька область, Україна, 58000

Methods: Format address

Types: Info User

Object

amount

number double

Example:

45.5

currency_code

string

UAH, USD, EUR…

Example:

UAH

Types: Escrow Info

Параметри зворотньої доставки коштів за передану посилку.

Object

cost

Cost required

Сума повернення – обсяг коштів, що підлягає поверненню.

priority_type

integer

Валюта повернення

Enumeration:

0

Одразу після доставки
У випадку використання – одразу генерується замовлення на аналоігчний маршрут в зворотному напрямі.
Тарифікація здійснюється як за подвійну поїздку.

1

До 18:00 поточного дня
Кошти можуть бути повернені не пізніше як 18:00 поточного дня. До цього часу, сервіс може оптимально розрахувати маршрути для зменшення кінцевої вартості зворотної доставки.

Вартість послуги:

Безкоштовно, якщо кур’єру довелось повертатись в місце відправки за наст. замовленням, або в близькі околиці.
По вартості поїздки від пункту призначення замовлення в напрямі до пункту отримання замовлення кур’єром (зворотна доставка).

2

За 3 дні

Аналогічно до опції 1, проте час на досвтавку коштів складає 3 дні.

3

Безкоштовний безготівковий переказ на картку/рахунок відправника [ОЧІКУЄ ВПРОВАДЖЕННЯ]

Types: Info