Интеграция API

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

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

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

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

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

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

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

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

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

Ответ

{
    "result": "ok",
    "token": "ERTWERTwerGSDFgsdfgERt4556KVzWT7GPYP3n2zi3nnOHWyr5vrQ5fDu1RPBiYhTXca4Df4Q74KQ7",
    "data": {
        "id": 1,
        "name": "ИМЯ_ПОЛЬЗОВАТЕЛЯ",
        "email": "ПОЧТА",
        "role_id": 2,
        "created_at": "2019-05-19 08:34:31"
    }
}

Список ролей

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

Ответ

[
    ...
    {
        "id": 2,
        "name": "Клиент"
    },
    ...
]

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

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

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

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

{
    "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, если у пользователя есть доступ

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

Где {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 запрос

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

[
    {
        "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": "Адресс 1",
        ...
    }
]

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

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

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

{
    "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": 1,
        "title": "Принято диспетчером"
    },
    ...
]

Callback

Для того, чтобы каждый раз не отправлять запрос к 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 может содержать следующие значения

Типы посылок

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

Ответ

[
    ...
    {
        "id": 1,
        "title": "Техника"
    },
    ...
]

Веса посылок

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

Ответ

[
    ...
    {
        "id": 1,
        "title": "до 1 кг",
        "method_id": 1
    },
    ...
]

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

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

Ответ

[
    ...
    {
        "id": 1,
        "title": "Пешком"
    },
    ...
]

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

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

Ответ

[
    ...
    {
        "id": 1,
        "title": "Наличными"
    },
    ...
]

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

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

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

{
    "result": "ok",
    "status": "success",
    "message": "Payment was successful",
}