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

Для обращения к ресурсу необходимо отправлять запрос на:

Получение списка тарифов

Ресурс /v1/shipping-tariffs позволяет получить список всех когда-либо загруженных тарифов, так же получить список тарифов на необходимую дату.

Шаги:

  1. Получить AccessToken.
  2. Отправить запрос.

Авторизация

Для получения списка тарифов необходимо отправить GET-запрос (/v1/shipping-tariffs), в котором нужно передать авторизационный токен к данным собственной организации (Access Token). Также при необходимости указать дату tariffDate, до которой необходимо получить весь список действующих тарифных планов. Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис SHIPPING_TARIFF.

Модель запроса

Наименование Описание
Параметры заголовка
Authorization (String) Access token организации-партнера, полученный через SSO. Пример: Bearer c76fb018-27c9-43f7-a751-62646eda7e1a-1
Параметры запроса
page (Number) Номер запрашиваемой страницы
tariffDate (Date) Дата, по которой необходимо получить весь список действующих тарифных планов Формат: YYYY-MM-DD

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

curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer c76fb018-27c9-43f7-a751-62646eda7e1a-1'
'http://edupirfintech.sberbank.ru:9443/fintech/api/v1/shipping-tariffs?page=1&tariffDate=2018-09-12'

Модель ответа

Наименование Описание
_links (Массив объектов JSON (array))
href (string (100)) Абсолютный или относительный адрес
rel (string (4)) Отношение ссылки к текущей сущности (next, prev)
shippingTariff (Массив объектов JSON (array))
externalId (String (36)) Идентификатор тарифа в организации-партнере (UUID)
departmentCode (String (16)) Код города отправки
destinationCode (String (16)) Код города получения
portCode (String (16)) Код города – порта для доставки морем или транзитного населенного пункта
loadingType (String (3)) Тип загрузки (LСL / FCL и FTL / LTL). если Тип доставки RW или SEA, то Тип загрузки FCL. если Тип доставки AIR, то Тип загрузки LCL. если Тип доставки TRK, то Тип загрузки FTL или LTL
deliveryType (String (3)) Тип доставки (AIR, SEA, RW, TRK). если Тип загрузки FCL, то Тип доставки RW или SEA. если Тип загрузки LCL, то Тип доставки AIR. если Тип загрузки FTL или LTL, то Тип доставки TRK
currency (String (3)) Трехзначный код валюты
fclContainerType (String (4)) Тип контейнера (FCL) или фуры для FTL
lclMinWeight (String(36)) Минимальный вес диапазона (для LCL и LTL)
lclMaxWeight (String(36)) Максимальный вес диапазона (для LCL и LTL)
tariffValue (String(36)) Тариф на доставку
currencyIn (String (3)) Трехзначный код валюты (внутренние перевозки)
tariffValueIn (String(36)) Тариф на доставку (внутренние перевозки)
deliveryTimeMin (Number (3)) Транзитное время, Min
deliveryTimeMax (Number (3)) Транзитное время, Max
payType (String (6)) Тип оплаты (BEFORE – предоплата, AFTER – постоплата)
beginDate (String (10)) Дата начала действия тарифа
endDate (String (10)) Дата окончания действия тарифа
cancelDate (String (10)) Дата отмены действия тарифа
routeCode (String (16)) Код маршрута

Пример ответа

{
   "_links":[
      {
         "href":"?tariffDate=2018-03-15&page=3"
         "rel":"next"
      }
   ]"shippingTariff":[
      {
         "externalId":"550e8400-e29b-41d4-a716-446655440000"
         "departmentCode":"JPYOK"
         "destinationCode":"RUMOW"
         "portCode":"12324"
         "loadingType":"FCL"
         "deliveryType":"RW"
         "currency":"840"
         "fclContainerType":"20"
         "lclMinWeight":"10"
         "lclMaxWeight":"1000"
         "tariffValue":"100000"
         "currencyIn":"132"
         "tariffValueIn":"10000"
         "deliveryTimeMin":10
         "deliveryTimeMax":15
         "payType":"AFTER"
         "beginDate":"2020-04-24"
         "endDate":"2020-05-24"
         "cancelDate":"2020-05-24"
         "routeCode":"52313"
      }
   ]
}

Обновление тарифа

Ресурс /v1/shipping-tariffs/{externalId} позволяет добавить/обновить тариф, для того, чтобы иметь возможность работы с тарифами по международной логистике.

Шаги:

  1. Получить AccessToken.
  2. Отправить запрос.

Авторизация

Для добавления тарифа необходимо отправить PUT-запрос (/v1/shipping-tariffs/{externalId}), в котором нужно передать авторизационный токен к данным собственной организации (Access Token), идентификатор тарифа в организации-партнера (externalId) и информацию о тарифе по международной логистике. Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис SHIPPING_TARIFF.

Модель запроса

Наименование Описание
Параметры заголовка
Authorization (String) Access token полученный через SSO. Пример: Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1
Параметры запроса
externalId (String) Идентификатор тарифа в организации-партнера
Body
ShippingTariff
beginDate (string) Дата начала действия тарифа
cancelDate (string, optional) Дата отмены действия тарифа
currency (string) Трехзначный код валюты
currencyIn (string, optional) Трехзначный код валюты (внутренние перевозки)
deliveryTimeMax (integer, optional) Максимальное транзитное время в днях
deliveryTimeMin (integer, optional) Минимальное транзитное время в днях
deliveryType (string) Тип доставки = ['AIR', 'SEA', 'RW', 'TRK']
departmentCode (string) Код города отправки
destinationCode (string) Код города получения
endDate (string) Дата окончания действия тарифа
externalId (string, optional) Идентификатор тарифа в организации-партнере (UUID)
fclContainerType (string, optional) Тип контейнера = ['20', '40', '40H', '40R', '40RH'] (для FCL ) или фуры = ['82', '82R', '82T', '86', '90', '92', '96J', '100M', '120T'] (для FTL).
lclMaxWeight (number, optional) Максимальный вес диапазона (для LCL и LTL)
lclMinWeight (number, optional) Минимальный вес диапазона (для LCL и LTL)
loadingType (string) Тип загрузки = ['LCL', 'FCL', ‘LTL’, ’FTL’]
payType (string) Тип оплаты = ['AFTER', 'BEFORE']
portCode (string, optional) Код города – порта для доставки морем или транзитного населенного пункта
routeCode (string, optional) Код маршрута
routeComment (string, optional) Комментарий к маршруту
tariffValue (number) Тариф на доставку
tariffValueIn (number, optional) Тариф на доставку (внутренние перевозки)

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

{
   "beginDate":"2018-12-31",
   "cancelDate":"2018-12-31",
   "currency":"840",
   "currencyIn":"string",
   "deliveryTimeMax":16,
   "deliveryTimeMin":14,
   "deliveryType":"RW",
   "departmentCode":"JPYOK",
   "destinationCode":"RUMOW",
   "endDate":"2018-12-31",
   "externalId":"22a6dd81-103a-4d3a-8e9b0ba4b527f5f6",
   "fclContainerType":"20",
   "lclMaxWeight":0,
   "lclMinWeight":0,
   "loadingType":"FCL",
   "payType":"AFTER",
   "portCode":"string",
   "routeCode":"string",
   "routeComment":"string",
   "tariffValue":0,
   "tariffValueIn":0
}

Дополнительная информация

Подписание запроса транспортной подписью

Content-Type может содержать одно из двух значений:

  1. application/json – запрос без подписи.
  2. application/jose – запрос, подписанный транспортной подписью.

Если Content-Type имеет значение application/jose, то запрос должен содержать данные (реквизитный состав платежного документа) в виде компактной сериализации RFC 7515: JSON Web Signature (JWS).

JWS состоит из:

  • заголовка (Header),
  • JSON-документа с реквизитным составом платежного поручения (Payload),
  • подписи запроса (Signature).

Формирование компактной сериализации JWS

JWS формируется из трех составляющих:

Base64Url(Header) || ’.’ || Base64Url(Payload) || ’.’ || Base64Url(Signature)

Signature - это подпись данных приватной частью ключевой пары пользователя (используется приватный ключ парный сертификату пользователя с UUID, указанному в Заголовке (Header) в параметре kid). Подпись вычисляется по алгоритму указанному в Заголовке (Header) в параметре alg, в данном случае gost34.10-2012, и вычисляется от исходных данных: Base64Url(Header) || ‘.’ || Base64Url(Payload).

Формирование исходных данных для вычисления подписи описано в спецификации RFC 7515: JSON Web Signature (JWS).

Следует отметить, что при кодировании JWS используется преобразование Base64Url, отличающееся от Base64 преобразования.
Условно это преобразование можно представить следующим образом:

Base64Url(x) := Base64(x).Split(‘=’)[0].Replace(‘+’, ’-’).Replace(‘/’, ’_’)

здесь функция Split(x), разбивает строку на части ([i] означает взятие i–ой части), используя символ разделитель x, функция Replace(x,y) заменяет все вхождения символа x на символ y.

Преобразование BASE64URL, отличается от BASE64 преобразования:

BASE64URL BASE64
- (minus) +
_ (underline) /
  • В BASE64URL не используется (опускается) padding, т.е. не добавляются знаки ‘=’ на конце закодированного содержимого Padding of Encoded Data.

В ответе на запрос сервер возвращает JSON-документ, который содержит реквизитный состав подготовленного черновика рублевого платежного поручения в статусе Создан.

Коды возврата

Код Описание Причина возникновения
200 (GET-запроса) OK
201 (PUT-запрос) CREATED
Создан
400 DESERIALIZATION_FAULT
Неверный формат Неверный формат запроса
WORKFLOW_FAULT
Для внешнего сервиса недоступны операции по счету: 40702810ХХХХХХХХХХХХ Для внешнего сервиса недоступны операции по счету: счет не добавлен в список разрешенных в оферте; внешний сервис заблокирован в СББОЛ; счет указан неверно. Отсутствует доступный открытый рублевый расчетный счет у организации плательщика
Документ с такими реквизитами уже существует Документ с такими реквизитами уже существует. Проверка по номер документа в течении года
Не указан идентификатор сертификата подписи Не указан идентификатор сертификата подписи(параметр kid заголовка JWS)
Некорректный формат параметра kid заголовка JWS Некорректный формат параметра kid заголовка JWS(ожидается UUID)
VALIDATION_FAULT
Ошибка валидации Ошибка валидации данных запроса с указанием некорректных значений. Значения полей модели или параметров запроса не соответствуют допустимым и определенным в модели
SIGN_CHECK_EXCEPTION
Подлинность подписи не установлена/Сертификат не обнаружен или не является активным Ошибка возникает, если не удалось установить подлинность подписи
401 UNAUTHORIZED
accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х Указан некорректный или просроченный access_token
403 ACTION_ACCESS_EXCEPTION
Операция не может быть выполнена: доступ к ресурсу запрещен У пользователя нет прав на использование соответствующего сервиса SberBusinessAPI (Fintech API), доступ к которому не предусмотрен настройками scope; У пользователя отсутствует оферта с внешним сервисом
415 JWS_EXCEPTED
В соответствии с текущими настройками сервиса с clientId=%s необходимо использовать запрос в формате JWS Compact Serialization Ошибка возникает, если в настройках внешних сервисов выставлен флаг «Требуется подпись для внешнего сервиса»
500 UNKNOWN_EXCEPTION
Внутренняя ошибка сервера
503 UNAVAILABLE_RESOURCE_EXCEPTION
Сервис временно недоступен Проводятся технические работы

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней