Мы предоставляем возможность интегрировать Ваше приложение, сайт, интернет магазин с нашей курьерской службой с помощью REST API. Для удобства, мы постарались написать понятную документацию по использованию нашего API. Над методами API мы продолжаем работать и добавлять новые методы для упрощения работы.
Для тестирования API запросов, отправляйте запросы на тестовый сервер
И только после успешных тестов, подключите публичный адрес
Каждый запрос должен иметь следующие заголовки
Параметр | Обязательно | Описание |
---|---|---|
Authorization | Да | Bearer YOUR_KEY |
Accept | Да | application/json |
YOUR_KEY - это уникальный ключ пользователя, который можно получить в профиле
Для публичного сайта - https://idcourier.uz/admin/profile
Для тестового сайта - https://test.idcourier.uz/admin/profile
либо отправить запрос к API с логином и паролем
Запрос принимает следующие значения
Параметр | Обязательно | Принимает значения | Описание |
---|---|---|---|
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 | Дата регистрации |
Информация о ролях требуется только для разработки внутри проекта
[
...
{
"id": 2,
"name": "Клиент"
},
...
]
id | Идентификатор роли |
name | Наименование роли |
С помощью запроса можно получить список заказов, к которым есть доступ у пользователя
Запрос принимает следующие значения
Параметр | Обязательно | Принимает значения | Описание |
---|---|---|---|
limit | Нет | int | Лимит запрошенных заказов |
skip | Нет | int | Выборка со сдвигом (например если нужно получить данные с десятой строки а не с первой, можно указать 10). Удобно для пагинации |
filter | Нет | array | Фильтр для выборки заказов, можно использовать параметры (см. Параметры заказа) |
full_data | Нет | boolean, string | Полные данные. Если указать 1, вернутся полные данные по всем идентификаторам, которые указаны в заказе (адреса, статус, метод, вес и т.д.). Такой запрос несен нагрузку выше, чем получить просто данные с идентификаторами. Можно снизить нагрузку, отправив запрос с выборочно указанными параметрами, которые хотите получить в развернутом виде. Укажите параметры через зпятую
|
По умолчанию, для фильтрации, каждый параметр приравнивается к значению, но можно так же использовать другие знаки сравнивания, такие как <, >, <=, >=, != , добавив запись в поле параметра и разделив провелом, например 'created_at >='
"created_at >=": "2020-02-08 01:45:35"
Данное условие сработает как "получить заказы, которые были добавлены позже, чем 2020-02-08 01:45:35"
{
"result": "ok",
"data": [
{
...
},
{
...
}
]
}
data - это массив множества заказов. Каждый массив содержит параметры (см. Параметры заказа)
С помощью запроса можно получить один заказ по его 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": "Принято диспетчером",
],
...
]
}
{
"result": "ok",
"data": [
"id": 1,
"status_id": 1,
"method_id": 1,
...
]
}
data - это массив с данными заказа. Массив содержит параметры (см. Параметры заказа)
Метод позволяет создать заказ
Запрос принимает параметры
Параметр | Принимает значения | Обязательный параметр | Описание |
---|---|---|---|
package_id | int | Да | Идентификатор типа посылки. Идентификаторы можно получить с помощью запроса (см. Типы посылок) |
weight_id | int | Да | Идентификатор веса посылки. Идентификаторы можно получить с помощью запроса (см. Способы доставки) |
method_id | int | Нет | По умолчанию "2" (Авто). Идентификатор способа доставки. Идентификаторы можно получить с помощью запроса (см. Способы доставки) |
address_from | array | Да | Адреса, откуда необходимо забрать посылку. При необходимости можно добавить несколько адресов. Например
Ниже приведена таблица с доступными параметрами |
address_to | array | Да | Адреса, КУДА необходимо доставить посылку. На данный момент разрешено добавлять только 1 адрес. Но массив остается многомерным, возможно в будущем сделаем возможность добавлять несколько адресов доставки. Вот пример
Ниже приведена таблица с доступными параметрами |
invoice | array | Нет | Если нужно добавить накладную к заказу, то отправьте нужные данные. И курьер покажет клиенту накладную с вашим номером заказа, списком товаров и суммой заказа. Все данные обязательны для заполнения. При не заполнении данных, ошибки не будет, просто параметр invoice будет проигнорирован. Во избежании непопадания данных в систему, заполняйте все поля со всеми данными
|
callback | string | Нет | Для того, чтобы каждый раз не отправлять запрос к idCourier с запросом на изменение статуса или возможно других изменений, можете указать в параметре callback адрес страницы вашего сайта, которая сможет принять наш запрос. Как только что-то изменится в вашем заказе, наша система отправит на указанный адрес GET запрос. Подробнее (см. Колбэки) |
Доступные параметры для отправки адреса
Параметр | Принимает значения | Обязательный параметр | Описание |
---|---|---|---|
address | string | Да | Полный точный адрес. С указанием района, улицы, номера дома, квартиры и т.д |
valid_date | date | Да | Укажите дату, когда следует забрать либо доставить посылку (дата в формате "Y-m-d") |
delivery_price | string | Auto | Возвращает стоимость доставки в эту точку (для адреса доставки) |
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 | Да | Контактный телефон адресата |
take_package_count | integer | Нет | Количество посылок (по умолчанию 1) |
give_money | integer | Нет | Сумма денег, которую нужно отдать (по умолчанию 0) |
take_money | integer | Нет | Сумма денег, которую нужно забрать (по умолчанию 0) |
payment_method_id | integer | Нет | Идентификатор метода доставки (см. Способы оплаты) |
address_house | integer | Нет | Номер дома |
address_entrance | integer | Нет | Номер подъезда |
address_code | integer | Нет | Код домофона |
address_floor | integer | Нет | Этаж |
address_apartment | integer | Нет | Номер квартиры |
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,
"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",
"delivery_price": "12000",
"contact_name": "Василий",
"contact_tel": "+998999999999",
"address_coordinates": "",
"start_time": null,
"end_time": null,
"message": "",
"order_id": 59
}
]
}
}
Более подробно о параметрах заказа, можете узнать тут (см. Параметры заказа)
Удалять заказ можно только тому, кто его создал и только если он еще не принят диспетчером (где status_id = 0)
{
"result": "ok",
"message": "Заказ успешно удален"
}
{
"result": "error",
"error_code": int,
"message": string
}
Тут перечислены все параметры заказа, которые принимают значения параметра filter и так же возвращается при успешном ответе
Параметр | Принимает значения | Описание |
---|---|---|
id | int | Идентификатор заказа |
user_id | int, array | Идентификатор автора заказа. При использовании для фильтрации по пользователю, нужны права управления заказами. Или массив с данными |
responsible_user_id | int, array | Идентификатор ответственного/диспетчера или массив с данными |
method_id | int, array | Идентификатор cпособа доставки или массив с данными |
weight_id | int, array | Идентификатор веса посылки или массив с данными |
package_id | int, array | Идентификатор типа посылки или массив с данными |
status_id | int, array | Идентификатор статуса заказа или массив с данными |
address_from | array | Массив с идентификаторами или с данными адресов "ОТКУДА" (не для фильтра) |
address_to | array | Массив с идентификаторами или с данными адресов "КУДА" (не для фильтра) |
total | string | Сумма заказа |
removed | int | 0 - заказ активен, 1 - заказ удален |
draft | int | 0 - заказ активен, 1 - черновик |
created_at | Y-m-d H:i:s | Дата и время создания заказа |
Статусы заказа - это важная часть системы, которая дает понимание на какой стадии находится заказ
[
...
{
"id": 1,
"title": "Принято диспетчером"
},
...
]
id | Идентификатор |
title | Название статуса |
Для того, чтобы каждый раз не отправлять запрос к idCourier с запросом на изменение статуса или возможно других изменений, можете указать в параметре callback адрес страницы вашего сайта, которая сможет принять наш запрос. Как только что-то изменится в вашем заказе, наша система отправит на указанный адрес GET запрос.
Это зависит от структуры вашего сайта и подходу к разработке. Но рекомендуем указывать ключ для проверки подлинности нашего запроса. Например
При формировании запроса на создание заказа, можно генерировать key используя id вашего заказа и функцию time() например
$id = 12456;
$key = md5($id.time());
и сохранить для своего заказа в своей системе
При принятии GET запроса на callback, находим заказ с нужным ключем, и уже творим с ним, что требуется
Ответ вернется со следующими параметрами
{
"callback_name":"total",
"callback_message":"Была изменена стоимость доставки для заказа",
"id":"546",
"user_id":"127",
"method_id":"2",
"weight_id":"1",
"package_id":"2",
"status_id":"1",
"total":"12000",
"removed":"0",
"created_at":"2021-02-11 13:12:49"
}
Возвращаемый параметр callback_name может содержать следующие значения
status_id | Был изменен статус заказа |
total | Была изменена стоимость доставки для заказа |
Информация о типах посылок, которые доступны для заказов (Техника, Еда, Подарок, Цветы и др.)
[
...
{
"id": 1,
"title": "Техника"
},
...
]
id | Идентификатор |
title | Название типа |
Список доступных весов посылок
[
...
{
"id": 1,
"title": "до 1 кг",
"method_id": 1
},
...
]
id | Идентификатор |
title | Название типа |
method_id | Идентификатор способа доставки, к которому относится данный вариант веса. Как получить список способов доставки, смотрите раздел "Способы доставки" |
Список доступных способов доставки
[
...
{
"id": 1,
"title": "Пешком"
},
...
]
id | Идентификатор |
title | Название способа доставки |
Если требуется список способов оплаты, его так же можно получить для вашего приложения с помощью запроса
[
...
{
"id": 1,
"title": "Наличными"
},
...
]
id | Идентификатор |
title | Название способа оплаты |
Если вы реализовали оплату за доставку на своем сайте с помощью PayMe, мы не можем привязать эту оплату автоматически к вашему заказу. Вам необходимо отправить запрос сервису после успешной оплаты ( сообщить о том, что поступила оплата), для своевременного внесения информаии в ваш заказ.
Запрос принимает следующие параметры
Параметр | Принимает значения | Обязательный параметр | Описание |
---|---|---|---|
method_payment | string | Да | Метод оплаты. На данный момент поддерживается только значение payme |
receipt_id | string | Да | ID чека в платежной системе, выданный после оплаты (Например в Payme) |
order_id | int | Да | ID заказа в сервисе idCourier, к которому будет привязана оплата |
{
"result": "ok",
"status": "success",
"message": "Payment was successful",
}
Значения параметра status
success | Успешно проверена подлинность чека и внесено в инормацию о заказе |
queue | Скорее всего оплата совершена не полностью, поэтому проверка чека откладывается. Каждые 10 минут сервис будет автоматически проверять оплату, отправляя запрос в платежную систему. После 6 попыток, в случае неудачи, проверка останавливается и к заказу оплата не прикрепляется |
none | Есть несколько вариантов
1. Чек с указанным ID, не найден 2. Вы пытаетесь повторно добавить чек в систему 3. Неверно отправленные данные |
Код | Описание |
---|---|
110 | Ошибка авторизации. Неверный токен |
201 | Заказа с указанным ID не существует |
202 | Нет прав к этому заказу |
203 | Заказ уже в обработке, его нельзя удалить |
0 | Ошибка на сервере |