+998 (95) 169-05-01
+998 (95) 169-05-02
+998 (95) 146-05-01

Интеграция API

Методы для интеграции Вашего приложение с нашей службой доставки

ДОКУМЕНТАЦИЯ API

Введение

Мы предоставляем возможность интегрировать Ваше приложение, сайт, интернет магазин с нашей курьерской службой с помощью REST API. Для удобства, мы постарались написать понятную документацию по использованию нашего API. Над методами API мы продолжаем работать и добавлять новые методы для упрощения работы.

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

Все запросы отправляются на адрес

https://idcourier.uz/api

Каждый запрос должен иметь следующие заголовки

Параметр Обязательно Описание
Authorization Да Bearer YOUR_KEY
Accept Да application/json

YOUR_KEY - это уникальный ключ пользователя, который можно получить в профиле https://idcourier.uz/admin/profile, либо отправить запрос к API с логином и паролем

Получить ключ

GET /auth/token

Запрос принимает следующие значения

Параметр Обязательно Принимает значения Описание
login Да string Логин в системе. Пользователь должен иметь аккаунт в системе
password Да string Пароль в системе

Ответ

{
    "result": "ok",
    "token": "ERTWERTwerGSDFgsdfgERt4556KVzWT7GPYP3n2zi3nnOHWyr5vrQ5fDu1RPBiYhTXca4Df4Q74KQ7",
    "data": {
        "id": 1,
        "name": "ИМЯ_ПОЛЬЗОВАТЕЛЯ",
        "email": "ПОЧТА",
        "role_id": 2,
        "created_at": "2019-05-19 08:34:31"
    }
}
id Идентификатор пользователя
token Персональный ключ пользователя, который требуется использовать в каждом запросе
role_id Идентификатор роли пользователя. 2 - это клиент.
created_at Дата регистрации

Список ролей

Информация о ролях требуется только для разработки внутри проекта

GET /role

Ответ

[
    ...
    {
        "id": 2,
        "name": "Клиент"
    },
    ...
]
id Идентификатор роли
name Наименование роли

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

С помощью запроса можно получить список заказов, к которым есть доступ у пользователя

Для этого нужно отправить простой запрос

GET /order

Запрос принимает следующие значения

Параметр Обязательно Принимает значения Описание
limit Нет int Лимит запрошенных заказов
skip Нет int Выборка со сдвигом (например если нужно получить данные с десятой строки а не с первой, можно указать 10). Удобно для пагинации
filter Нет array Фильтр для выборки заказов, можно использовать параметры (см. Параметры заказа)
full_data Нет boolean, string

Полные данные. Если указать 1, вернутся полные данные по всем идентификаторам, которые указаны в заказе (адреса, статус, метод, вес и т.д.). Такой запрос несен нагрузку выше, чем получить просто данные с идентификаторами.

Можно снизить нагрузку, отправив запрос с выборочно указанными параметрами, которые хотите получить в развернутом виде. Укажите параметры через зпятую

{
    "full_data": "status_id,address_from,address_to"
}

По умолчанию, для фильтрации, каждый параметр приравнивается к значению, но можно так же использовать другие знаки сравнивания, такие как <, >, <=, >=, != , добавив запись в поле параметра и разделив провелом, например 'created_at >='

"created_at >=": "2020-02-08 01:45:35"

Данное условие сработает как "получить заказы, которые были добавлены позже, чем 2020-02-08 01:45:35"

Вернется ответ

{
    "result": "ok",
    "data": [
    	{
        	...
        },
    	{
        	...
        }
    ]
}

data - это массив множества заказов. Каждый массив содержит параметры (см. Параметры заказа)

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

С помощью запроса можно получить один заказ по его ID, если у пользователя есть доступ

Для этого нужно отправить запрос

GET /order/{id}

Где {id} - это идентификатор заказа

По умолчанию данные возвращаются только с идентификаторами. Если же нужны полные данные, то отправьте параметр full_data со значением 1

{
    "full_data": 1
}

Или укажите через запятую необходимые параметры

{
    "full_data": "status_id,user_id"
}

Тогда вернутся данные с массивами данных, Например параметр status_id вернется так

{
    "result": "ok",
    "data": [
        "id": 1,
        "status_id": [
            "id": 1,
            "title": "Принято диспетчером",
        ],
        ...
    ]
}

При отсутствии либо при отрицательном значении параметра full_data, вернется ответ только с идентификаторами

{
    "result": "ok",
    "data": [
    	"id": 1,
    	"status_id": 1,
    	"method_id": 1,
    	...
    ]
}

data - это массив с данными заказа. Массив содержит параметры (см. Параметры заказа)

Создать заказ

Метод позволяет создать заказ

Для этого нужно отправить POST запрос

POST /order

Запрос принимает параметры

Параметр Принимает значения Обязательный параметр Описание
package_id int Да Идентификатор типа посылки. Идентификаторы можно получить с помощью запроса (см. Типы посылок)
weight_id int Да Идентификатор веса посылки. Идентификаторы можно получить с помощью запроса (см. Способы доставки)
method_id int Нет По умолчанию "2" (Авто). Идентификатор способа доставки. Идентификаторы можно получить с помощью запроса (см. Способы доставки)
payment_id int Нет По умолчанию "1" (Наличные). Идентификатор способа оплаты. Идентификаторы можно получить с помощью запроса (см. Способы оплаты)
address_from array Да

Адреса, откуда необходимо забрать посылку. При необходимости можно добавить несколько адресов. Например

[
    {
        "address": "Адресс 1",
        "valid_date": "2020-05-20",
        "contact_name": "Андрей",
        "contact_tel": "+998999999999",
        "address_coordinates": "41.309688, 69.220205",
        "start_time": "00:00:00",
        "end_time": "00:00:00",
        "message": ""
    },
    {
        "address": "Адресс 2",
        ...
    }
]

Ниже приведена таблица с доступными параметрами

address_to array Да

Адреса, КУДА необходимо доставить посылку. При необходимости можно добавить несколько адресов. Например

[
    {
        "address": "Адресс 1",
        ...
    },
    {
        "address": "Адресс 2",
        ...
    }
]

Ниже приведена таблица с доступными параметрами

Доступные параметры для отправки адреса

Параметр Принимает значения Обязательный параметр Описание
address string Да Полный точный адрес. С указанием района, улицы, номера дома, квартиры и т.д
valid_date date Да Укажите дату, когда следует забрать либо доставить посылку (дата в формате "Y-m-d")
start_time time Нет Не обязательно. Если требуется доставить в опледеленный промежуток времени, укажите время С какого времени (дата в формате "H:i:s")
end_time time Нет Не обязательно. Если требуется доставить в опледеленный промежуток времени, укажите время ДО какого времени (дата в формате "H:i:s")
address_coordinates string Нет Если есть возможность отправить координаты указанного адреса, отправьте с этим параметром в формате "41.309688, 69.220205"
contact_name string Да Контактное имя адресата
contact_tel string Да Контактный телефон адресата
message string Нет Если есть дополнительная информация, укажите её

Запрос может выглядеть примерно так

{
    "package_id":2,
    "weight_id": 1,
    "address_from": [
        {
            "address": "Юнусабадский район, дом 23, квартира 2",
            "valid_date": "2020-05-20",
            "contact_name": "Андрей",
            "contact_tel": "+998999999999"
        }   
    ],
    "address_to": [
        {
            "address": "Юнусабадский район, квартал 7, дом 12, квартира 98, 5й подъезд, 3 этаж",
            "valid_date": "2020-05-20",
            "contact_name": "Василий",
            "contact_tel": "+998999999999"
        }   
    ]
}

Если все прошло хорошо, вернется ответ

{
    "result": "ok",
    "data": {
        "user_id": 1,
        "executor_user_id": 0,
        "responsible_user_id": 0,
        "method_id": 2,
        "weight_id": 1,
        "package_id": 2,
        "payment_id": 1,
        "status_id": 0,
        "total": 0,
        "id": 59,
        "address_from": [
            {
                "address": "Юнусабадский район, дом 23, квартира 2",
                "valid_date": "2020-05-20",
                "contact_name": "Андрей",
                "contact_tel": "+998999999999",
                "address_coordinates": "",
                "start_time": null,
                "end_time": null,
                "message": "",
                "order_id": 59
            }
        ],
        "address_to": [
            {
                "address": "Юнусабадский район, квартал 7, дом 12, квартира 98, 5й подъезд, 3 этаж",
                "valid_date": "2020-05-20",
                "contact_name": "Василий",
                "contact_tel": "+998999999999",
                "address_coordinates": "",
                "start_time": null,
                "end_time": null,
                "message": "",
                "order_id": 59
            }
        ]
    }
}

Более подробно о параметрах заказа, можете узнать тут (см. Параметры заказа)

Удаление заказа

Удалять заказ можно только тому, кто его создал и только если он еще не принят диспетчером (где status_id = 0)

DELETE /order/{id}
Где {id} - Идентификатор заказа

Вернется ответ


{
    "result": "ok",
    "message": "Заказ успешно удален"
}
В случае неудачи, вернется ошибка

{
    "result": "error",
    "error_code": int,
    "message": string
}

Параметры заказа

Тут перечислены все параметры заказа, которые принимают значения параметра filter и так же возвращается при успешном ответе

Параметр Принимает значения Описание
id int Идентификатор заказа
user_id int, array Идентификатор автора заказа. При использовании для фильтрации по пользователю, нужны права управления заказами. Или массив с данными
executor_user_id int, array Идентификатор исполнителя/курьера или массив с данными
responsible_user_id int, array Идентификатор ответственного/диспетчера или массив с данными
method_id int, array Идентификатор cпособа доставки или массив с данными
weight_id int, array Идентификатор веса посылки или массив с данными
package_id int, array Идентификатор типа посылки или массив с данными
payment_id int, array Идентификатор способа оплаты или массив с данными
status_id int, array Идентификатор статуса заказа или массив с данными
address_from array Массив с идентификаторами или с данными адресов "ОТКУДА" (не для фильтра)
address_to array Массив с идентификаторами или с данными адресов "КУДА" (не для фильтра)
total string Сумма заказа
created_at Y-m-d H:i:s Дата и время создания заказа

Статусы заказа

Статусы заказа - это важная часть системы, которая дает понимание на какой стадии находится заказ

GET /status

Ответ

[
    ...
    {
        "id": 1,
        "title": "Принято диспетчером"
    },
    ...
]
id Идентификатор
title Название статуса

Типы посылок

Информация о типах посылок, которые доступны для заказов (Техника, Еда, Подарок, Цветы и др.)

GET /package

Ответ

[
    ...
    {
        "id": 1,
        "title": "Техника"
    },
    ...
]
id Идентификатор
title Название типа

Веса посылок

Список доступных весов посылок

GET /weight

Ответ

[
    ...
    {
        "id": 1,
        "title": "до 1 кг",
        "method_id": 1
    },
    ...
]
id Идентификатор
title Название типа
method_id Идентификатор способа доставки, к которому относится данный вариант веса. Как получить список способов доставки, смотрите раздел "Способы доставки"

Способы доставки

Список доступных способов доставки

GET /method_delivery

Ответ

[
    ...
    {
        "id": 1,
        "title": "Пешком"
    },
    ...
]
id Идентификатор
title Название способа доставки

Способы оплаты

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

GET /payment

Ответ

[
    ...
    {
        "id": 1,
        "title": "Наличными"
    },
    ...
]
id Идентификатор
title Название способа оплаты

Коды ошибок

Код Описание
110 Ошибка авторизации. Неверный токен
201 Заказа с указанным ID не существует
202 Нет прав к этому заказу
203 Заказ уже в обработке, его нельзя удалить
0 Ошибка на сервере