2. API v1

2.1 Робимо запити

Постійна адреса Smartdelivery API:

http://api.smartdelivery.com.ua/

Шаблон запиту до API:

Запит складається з адреси запиту до API із версією, командою та параметрами у канонічному вигляді:

http://api.smartdelivery.com.ua/[version]/action[?param1=value1][&param2=value2][&param3=value3]

Де version це версія, action це команда, param# це уточнювальний параметр, value# це його значення.

Приклади запитів:

http://api.smartdelivery.com.ua/v1/services

http://api.smartdelivery.com.ua/v1/houses?city=Тернополь&language=en

http://api.smartdelivery.com.ua/v1/houses?city=вишгород&service_filter[]=novaposhta

Версія

Єдина доступна версія API наразі є v1.

Команди

У шаблонах запитів до API команда вказана як action. Наразі чинний список команд:

• houses — список відділень у місті. Обов'язковий уточнювальний параметр city, необов'язковий уточнювальний параметр service_filter
• cities буде доступною незабаром — список міст, які є у базі даних. В кожному з міст є хоча б одне віділення якогось сервісу. Необов'язковий уточнювальний параметр service_filter
• services буде доступною незабаром — список сервісів

Уточнювальні параметри

Параметр	Можливі значення
language	ua(за замовчуванням), ru, планується en
city	вільне значення
service_filter	масив внутрішніх аліасів сервісів smartdelivery, наприклад: ['novaposhta'] тільки для Нової Пошти, ['novaposhta','autolux'] тільки для Автолюксу і Нової Пошти

2.2 Отримуємо відповіді

Структура відповідей

API завжди відповідає у форматі JSON.

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

Повний JSON

{
   "status": "value",
   "messages": [
      "value",
      "value",
      ...
   ],
   "data": [
   {
      "key": "value",
      "key": "value",
      ...
   },
   {
      "key": "value",
      "key": "value",
      ...
   },
   ...
   ]
}

Приклади відповідей

Відділення у Вишгороді

Звертаємось до API за такою адресою: http://api.smartdelivery.com.ua/v1/houses?city=вишгород

{
    "status": "success",
    "messages": [],
    "data": [
        {
            "title": "Відділення №1: вул. Кургузова, 14",
            "phones": "(044) 323-0-222",
            "latitude": "50.577847741654000",
            "longitude": "30.475237369537000",
            "service_title": "Нова пошта",
            "service_alias": "novaposhta",
            "city_title": "Вишгород"
        },
        {
            "title": "Відділення №2 (до 30 кг): вул. Київська, 2",
            "phones": "(044) 323-02-22",
            "latitude": "50.574159000000000",
            "longitude": "30.488620000000000",
            "service_title": "Нова пошта",
            "service_alias": "novaposhta",
            "city_title": "Вишгород"
        },
        {
            "title": "Відділення № 3 ( до 30 кг на одне місце): просп. Тараса Шевченко, 2д",
            "phones": "0-800-500-609",
            "latitude": "50.581055390000000",
            "longitude": "30.489709740000000",
            "service_title": "Нова пошта",
            "service_alias": "novaposhta",
            "city_title": "Вишгород"
        },
        {
            "title": "Поштомат №1: вул. Шолуденка, 6в",
            "phones": "0-800-500-609",
            "latitude": "50.588804000000000",
            "longitude": "30.491974000000000",
            "service_title": "Поштомати Приватбанку",
            "service_alias": "privatbank",
            "city_title": "Вишгород"
        }
    ]
}

Приклад помилки: непідтримувана мова

Звертаємось до API за такою адресою: http://api.smartdelivery.com.ua/v1/cities?language=kz Відповідь повертається у стандартному форматі JSON.

{
    "status": "fail",
    "messages": [
        "unknown language"
    ]
}

Помилки

Статуси помилок, які може повернути API у разі неправильного запиту чи параметрів:

Помилка	Що це означає
bad request	вказана команда чи версія не існує або не вказана
unknown language	вказана мова не підтримується
unknown service alias	вказано непідтримуваний аліас сервісу
city not defined	не вказано місто
city not found	вказаного міста немає у базі даних