Интеграция по API

: 06.12.2020 19:10; Просмотров: 229

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

Доступ к API по адресу: https://api.utsr.ru/

Аутентификация

Для аутентификации в API (подписи запросов) Вам необходимо запросить у менеджера API KEY и SECRET KEY

Аутентификация проводится с помощью двух заголовков (HEADER)

X-PARTNER-ID - это API KEY
X-PARTNER-SIGN - подпись запроса.
Формируется как md5 сумма от строки "SECRET KEY + body"
Для GET-запроса: md5(SECRET KEY)
Для POST-запроса: md5(SECRET KEY + POST body)

DEBUG-режим

По умолчанию, после получения API KEY и SECRET KEY при интеграции включен debug-режим.

С помощью данного режима можно "отладить" работу приложения, в ответе возвращается дополнительная информация. Например, если подпись запроса некорректна, то в debug-режиме в ответе будет возвращаться параметр "sign_must_be", который укажет корректную подпись для запроса. Также, в debug-режиме есть ограничения на количество запросов.

По завершении интеграции с API необходимо сообщить менеджеру, интеграция будет переведена в "боевой" режим (дополнительной информации возвращаться не будет)

Методы

Метод получения списка обслуживаемых городов

Метод запроса:

GET

Адрес метода:

/v1/city/

Ответ

Параметр	Тип	Значение
id	string(36)	Идентификатор города в формате GUID
name	string	Наименование города
alias	string	Алиас

Пример запроса:

curl --location --request GET 'https://api.utsr.ru/v1/city/' \
--header 'X-PARTNER-ID: c343652e-37ef-11eb-a671-00163e47de8a' \
--header 'X-PARTNER-SIGN: be8d082f097f0bb43dc666a03f67bd28'

Метод получения списка складов (терминалов)

Метод запроса:

GET

Адрес метода:

/v1/terminal/

Ответ

Параметр	Тип	Значение
id	string(36)	Идентификатор терминала (склада) в формате GUID
name	string	Наименование терминала (адрес)
city	string(36)	Идентификатор города в формате GUID
phone	string	Контактный телефон (справочная информация)
email	string	Контактный email (справочная информация)
timework	string	Время работы (справочная информация)
coordinates	string	Координаты (справочная информация, для отображения на карте)

Пример запроса:

curl --location --request GET 'https://api.utsr.ru/v1/terminal/' \
--header 'X-PARTNER-ID: c343652e-37ef-11eb-a671-00163e47de8a' \
--header 'X-PARTNER-SIGN: be8d082f097f0bb43dc666a03f67bd28'

Метод определения стоимости грузоперевозки

Метод запроса:

POST

Адрес метода:

/v1/calculate/

Параметры запроса

Параметр	Тип	Значение
sending	object	Объект Point, содержащий информацию о точке забора или доставки груза
weight	float	Вес, кг
volume	float	Объем, м³
additionalPack	object	Объект, содержащий информацию о необходимости дополнительной упаковки
additionalPack.pack	boolean	Флаг для определения необходимости дополнительной упаковки
additionalPack.type	enum	lathing - обрешетка pallet - паллетный борт
insurance	object	Объект, содержащий информацию о необходимости страхования груза
insurance.add	boolean	Флаг для добавления услуги страхования груза
insurance.value	float	Оценочная стоимость груза, руб

Объект Point

Параметр	Тип	Значение
type	enum	terminal - склад address - адрес
id	string	При type = terminal, идентификатор терминала (склада) в формате GUID
city	string	При type = address, идентификатор города в формате GUID
address	string	При type = address, объект с информацией об адресе
address.street	string	При type = address, наименование улицы
address.house	string	При type = address, номер дома

Ответ

Параметр	Тип	Значение
price	float	Стоимость грузоперевозки

Пример запроса:

curl --location --request POST 'https://api.utsr.ru/v1/calculate/' \
--header 'X-PARTNER-ID: c343652e-37ef-11eb-a671-00163e47de8a' \
--header 'X-PARTNER-SIGN: bb14314469c612f99e836b85cf4e4dd6' \
--header 'Content-Type: application/json' \
--data-raw '{
    "sending": {
        "type": "terminal",
        "id": "db6b1ed1-d9f8-11e9-814c-00155d016401"
    },
    "delivery": {
        "type": "address",
        "city": "5f11ab0f-37ef-11eb-a671-00163e47de8a",
        "address": {
            "street": "Ленина",
            "house": "1"
        }
    },
    "weight": 10,
    "volume": 0.1,
    "additionalPack":{
        "pack": true,
        "type": "lathing"
    },
    "insurance":{
        "add": true,
        "value": 10000
    }
}'

Коды ошибок

Код ошибки	HTTP-код	Описание ошибки
missed_auth_credentials	401	Не найдены заголовки X-PARTNER-ID и X-PARTNER-SIGN
incorrect_partner	401	Не найдена информация по партнеру (по API KEY)
incorrect_sign	401	Некорректная подпись запроса
undefined_method	500	Некорректный метод для запроса по API. Поддерживаются только методы GET и POST
incorrect_parameter	500	Некорректно передан параметр в теле JSON Body (POST)
internal_error	500	Внутренняя ошибка

Техническая поддержка