+998 (95) 169-05-02

Интеграция API

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

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

Введение

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

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

Для тестирования API запросов, отправляйте запросы на тестовый сервер

https://test.idcourier.uz/api

И только после успешных тестов, подключите публичный адрес

https://idcourier.uz/api

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

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

YOUR_KEY - это уникальный ключ пользователя, который можно получить в профиле

Для публичного сайта - https://idcourier.uz/admin/profile
Для тестового сайта - https://test.idcourier.uz/admin/profile

либо отправить запрос к API с логином и паролем

Публичный сайт https://idcourier.uz и тестовый сайт https://test.idcourier.uz работают независимо друг от друга, поэтому необходимо зарегистрировать аккаунт и на тестовом сайте и на публичном

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

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" (Авто). Идентификатор способа доставки. Идентификаторы можно получить с помощью запроса (см. Способы доставки)
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 Да

Адреса, КУДА необходимо доставить посылку. На данный момент разрешено добавлять только 1 адрес. Но массив остается многомерным, возможно в будущем сделаем возможность добавлять несколько адресов доставки. Вот пример

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

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

invoice array Нет

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

{
    "order_number": "Номер вашего заказа",
    "location": "Адрес получателя",
    "total": "Сумма заказа",
    "client_name": "Имя получателя",
    "client_telephone": "Телефон получателя",
    "products": [
        {
            "name": "Наименование товара",
            "artikul": "Артикул товара",
            "quantity": "Количество",
            "total": "Сумма заказа этого товара",
        },
        ...
    ]
}

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)

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

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


{
    "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 Дата и время создания заказа

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

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

GET /status

Ответ

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

Callback

Для того, чтобы каждый раз не отправлять запрос к idCourier с запросом на изменение статуса или возможно других изменений, можете указать в параметре callback адрес страницы вашего сайта, которая сможет принять наш запрос. Как только что-то изменится в вашем заказе, наша система отправит на указанный адрес GET запрос.

Формат ссылки на ваш сайт

Это зависит от структуры вашего сайта и подходу к разработке. Но рекомендуем указывать ключ для проверки подлинности нашего запроса. Например

https://yoursite.domain/callback/?key=efa6942a9321c03916b30de8adcf3ac3

Реализация на стороне вашего сервиса

При формировании запроса на создание заказа, можно генерировать 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 Была изменена стоимость доставки для заказа


Типы посылок

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

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 Название способа оплаты

Подтверждение оплаты

Если вы реализовали оплату за доставку на своем сайте с помощью PayMe, мы не можем привязать эту оплату автоматически к вашему заказу. Вам необходимо отправить запрос сервису после успешной оплаты ( сообщить о том, что поступила оплата), для своевременного внесения информаии в ваш заказ.

POST /receipt

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

Параметр Принимает значения Обязательный параметр Описание
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 Ошибка на сервере