Интеграция API Служба доставки СДЭК (CDEK)

Данный документ описывает реализацию обмена информацией между Falcon Space и службой доставки СДЭК.

Общие входные данные:

  • Город отправления (Флаг - от двери);
  • Город получения (Флаг - до двери);
  • Длина, см;
  • Ширина, см;
  • Высота, см;
  • Вес, г.

 Общий алгоритм:

  1.  Формирование текста запроса с параметрами
  2.  Отправка запроса 
  3.  Получение ответа на запрос
  4.  Парсинг ответа,  получение данных.

Полезные сервисы СДЭК

Сервисы - https://cdek.ru/services

Тарифы для частных лиц - https://cdek.ru/individuals/tariffs

Расчёт стоимости доставки - https://cdek.ru/calculate

Интеграция - https://cdek.ru/integration

Интеграция - Часто задаваемые вопросы - https://cdek.ru/integration#questions

Вариант с авторизацией

Что нужно сделать чтобы интегрироваться?

Шаг 1: Интеграция возможна только при наличии договора (интернет-магазина или договора на оказание курьерских услуг) и если он имеет статус “Подписан” в наших системах.

  

Вариант без авторизации

Можно ли использовать API-калькулятора тарифов без договора?

Да, параметры учетной записи (Account и Secure) не являются обязательными, но Вы не сможете проводить расчет по тарифам для интернет-магазинов и у Вас не будут учитываться персональные скидки.

Технические параметры

Взаимодействие с сервисом происходит в режиме онлайн с помощью стандартного протокола HTTPS и формата JSON.

Обмен сообщениями должен осуществляться в кодировке UTF-8.

  

КАЛЬКУЛЯТОР БЕЗ АВТОРИЗАЦИИ - ВЕРСИЯ v1.5 API интеграции

https://confluence.cdek.ru/pages/viewpage.action?pageId=15616129#id-Протоколобменаданными(v1.5)-4.14CalculatorКалькулятор

Процедуру обмена реализованы по пункту - 4.14.1. Расчет стоимости по тарифам с приоритетом

СДЭК - тарифы – PROCEDURE [api_ruCDEKTariff_request]

Для получения стоимости и сроков доставки необходимо отправить json-объект серверу СДЭК.

При передаче json-объекта в заголовке нужно указать соответствующий Content-Type.

  • URL: http://api.cdek.ru/calculator/calculate_price_by_json.php
  • Content-Type: application/json
  • Метод запроса: POST
  • Формат на выходе: JSON

Входные данные запроса – параметры процедуры PROCEDURE [api_ruCDEKTariff_request]

Переменная

Тип

Значение по умолчанию

Описание

Примечание

1

@dateExecute2

nvarchar(10)

''

Планируемая дата отправки заказа в формате “ГГГГ-ММ-ДД

2

@senderCityId

int

36528

Код города отправителя из базы СДЭК

 

3

@receiverCityId       

int

288  

Код города получателя из базы СДЭК

 

4

@tariffId

int

1

Код выбранного тарифа

 

 

 goods    Габаритные характеристики упаковки

5

@weight

int

300

Вес (грамм )

ПЕРЕСЧЕТ! Вес упаковки (в килограммах)

6

@length

int

5

Длина упаковки (в сантиметрах)

 

7

@width

int

20

Ширина упаковки (в сантиметрах)

 

 

@height

int

10

Высота упаковки (в сантиметрах)

 

Приложение 1. Услуги (тарифы) и режимы доставки СДЭК

Тарифы для обычной доставки 

Код

Название тарифа

Режим доставки

Ограничение по весу

Услуга

Описание

1

Экспресс лайт дверь-дверь

дверь-дверь (Д-Д)

до 30 кг

Экспресс

Классическая экспресс-доставка по России документов и грузов до 30 кг.

3

Супер-экспресс до 18

дверь-дверь (Д-Д)

до 30 кг

Срочная доставка

Срочная доставка документов и грузов «из рук в руки» по России к определенному часу.

5

Экономичный экспресс склад-склад

склад-склад (С-С)

 

Экономичная доставка

Недорогая доставка грузов по России ЖД и автотранспортом (доставка грузов с увеличением сроков).

  

города получателя из базы СДЭК

  • Id - Идентификатор города по базе СДЭК (CityCode)
  • FullName - Полное название города/населенного пункта включая региональную принадлежность
  • CityName - Название города не включает региональную принадлежность 

ID

FullName

CityName

OblName

36528

5663234234, Москва

Москва

438

Ростов-на-Дону

Ростов-на-Дону

Ростовская обл.

402

Архангельск

Архангельск

Архангельская обл.

288

Владивосток

Владивосток

Приморский край

  

Пример текста запроса - request.

URL: http://api.cdek.ru/calculator/calculate_price_by_json.php  

JSON - BODY  

{
"version":"1.0",
"dateExecute":"2020-06-03",
"senderCityId":"36528",
"receiverCityId":"288",
"tariffId":"1",
"goods":
[
                {
                "weight":"0.300",
                "length":"5",
                "width":"20",
                "height":"10"
                }
]
}

Пример текста ответа - response.

{
    "result": {
        "price": "1370",
        "deliveryPeriodMin": 7,
        "deliveryPeriodMax": 10,
        "deliveryDateMin": "2020-06-10",
        "deliveryDateMax": "2020-06-13",
        "tariffId": "1",
        "priceByCurrency": 1370,
        "currency": "RUB"
    }
}

CREATE PROCEDURE [dbo].[api_ruCDEKTariff_request]
	@parameters ExtendedDictionaryParameter READONLY,  -- входящие параметры для внутренней обработки (используйте Key, Value2)
	@username nvarchar(32)  -- текущий пользователь.
    --
    -- ВХ.ПАРАМ
, @dateExecute2 nvarchar(10) = ''		--'2020-07-19'	-- Планируемая дата отправки заказа в формате “ГГГГ-ММ-ДД”
, @senderCityId          int = 36528 -- Код города отправителя из базы СДЭК integer
, @receiverCityId        int = 288   -- Код города получателя из базы СДЭК  integer
, @tariffId              int = 1     -- Код выбранного тарифа
-- goods	Габаритные характеристики упаковки
, @weight                int = 300   -- Вес (грамм )	– ПЕРЕСЧЕТ! Вес упаковки (в килограммах) numeric(20,3)
, @length                int = 5		-- Длина упаковки (в сантиметрах)	integer
, @width                 int = 20		-- Ширина упаковки (в сантиметрах)	integer
, @height                int = 10		-- Высота упаковки (в сантиметрах)	integer
AS
BEGIN


-- Вес (грамм )	– ПЕРЕСЧЕТ! Вес упаковки (в килограммах) numeric(20,3) -
-- 1 Грамм (гр) = 0.001 Килограмма (кг)
DECLARE @weightKG numeric(20,3)
SET     @weightKG = @weight * 0.001


-- Планируемая дата отправки заказа в формате “ГГГГ-ММ-ДД”
-- 23 	ISO8601 	гггг-мм-дд
IF  LEN(  ISNULL ( @dateExecute2   , '' ) )=0
SET @dateExecute2  =  CONVERT ( nvarchar(10) , GETDATE() , 23 )
-- exec as_print @str = @dateExecute2

DECLARE @apiUrl 		nvarchar(max) = '' 		-- Финальная строка для отправки -- @apiStr -- ФАКТИЧЕСКИ ЭТО Url
DECLARE @apiCommomStr 	nvarchar(max) = '' 	    -- Общая часть для всех запросов
DECLARE @jsonRequest 	nvarchar(max) = '' 	    -- текст json-объекта

-- необходимо отправить json-объект серверу СДЭК.
-- При передаче json-объекта в заголовке нужно указать соответствующий Content-Type.
-- URL :	http://api.cdek.ru/calculator/calculate_price_by_json.php
-- Type:	Content-Type: application/json	--  указать ЭТО ДОЛЖНО БЫТЬ В HEADER

SET     @apiCommomStr = N'http://api.cdek.ru/calculator/calculate_price_by_json.php' --

SET     @jsonRequest  = N'{' + CHAR(10)
                      + N'"version":"1.0",'  + CHAR(10)
                      + N'"dateExecute":"'   + @dateExecute2 +'",'+ CHAR(10)
                      + N'"senderCityId":"'  + TRY_CAST ( @senderCityId   AS nvarchar )  +'",'+  CHAR(10)
                      + N'"receiverCityId":"'+ TRY_CAST ( @receiverCityId AS nvarchar )  +'",'+  CHAR(10)
                      + N'"tariffId":"'      + TRY_CAST ( @tariffId       AS nvarchar )  +'",'+  CHAR(10)
                      + N'"goods":'			+ CHAR(10)
                      + N'['				+ CHAR(10)
                      + CHAR(9)+ N'{'				+ CHAR(10) -- табуляции CHAR(9)
                      + CHAR(9)+ N'"weight":"'  + TRY_CAST ( @weightKG AS nvarchar )  +'",'+  CHAR(10)
                      + CHAR(9)+ N'"length":"'  + TRY_CAST ( @length   AS nvarchar )  +'",'+  CHAR(10)
                      + CHAR(9)+ N'"width":"'   + TRY_CAST ( @width    AS nvarchar )  +'",'+  CHAR(10)
                      + CHAR(9)+ N'"height":"'  + TRY_CAST ( @height   AS nvarchar )  +'" '+  CHAR(10) -- Последняя строка без запятой
                      + CHAR(9)+ N'}' + CHAR(10)
                      + N']' + CHAR(10)
                      + N'}'

-- PRINT @jsonRequest

SET  @apiUrl  =  @apiCommomStr -- + @jsonRequest

    -- ОТЛАДКА
    -- exec as_print @str='api_ruCDEKTariff_request'
	insert into as_trace ( header, text, username, code , created )   values( '@apiUrl Url', @apiUrl , @username, 'api_ruCDEKTariff_request' , GETDATE() )
	insert into as_trace ( header, text, username, code , created )   values( '@jsonRequest', @jsonRequest , @username, 'api_ruCDEKTariff_request' , GETDATE() )


	-- SELECT 1  Msg, Result, Url (адрес, куда будет идти запрос)
	select '' Msg, 1 Result
          , @apiUrl Url
          , 'application/json' ContentType -- явное указание для HEADER

	-- SELECT 2 PARAMETERS - параметры, которые будут передаваться во внешний источник
	 select 'id' name
           , @jsonRequest value -- это body
           , 'json' [type] -- form (в форме передается), header (в http headers), get запросы передавайте прямо в URL
   -- Как отправить исходящий запрос POST с JSON телом?
   -- Для этого указываем тип запроса POST и передаем только 1 параметр с type=json в формате строки с JSON.
END

СДЭК - тарифы - PROCEDURE [api_ruCDEKTariff_response]

 Результат запроса может быть как сообщение с информацией, так и сообщение с ошибкой.

 Список возможных сообщение об ошибка.

  •  'Ошибка! Строка @response не является JSON!' (Проверка ответа оператором ISJSON() )
  •  'Ошибка! Запрос @response вернул ошибку! '… @errorText.

Если ошибок в ответе не обнаружено, из ответа выбираться такие данные:

  •  deliveryPeriodMin             Минимальное время доставки в днях       integer
  •  deliveryPeriodMax            Максимальное время доставки в днях
  • deliveryDateMin                Минимальная дата доставки, формате 'ГГГГ-ММ-ДД'
  • deliveryDateMax               Максимальная дата доставки, формате 'ГГГГ-ММ-ДД'
  • tariffId                             Код тарифа, по которому рассчитана сумма доставки
  • priceByCurrency               Цена в валюте взаиморасчетов.
  • currency                          Валюта интернет-магазина

 

Пример текста – результат: "Срок доставки: от 7 до 10 дней. Даты: с 2020-06-10 по 2020-06-13. Сумма: 1370 RUB."

PROCEDURE [dbo].[api_ruCDEKTariff_response]

CREATE PROCEDURE [dbo].[api_ruCDEKTariff_response]
	@response nvarchar(max),
	@parameters ExtendedDictionaryParameter READONLY,  -- входящие параметры для внутренней обработки (используйте Key, Value2 - те же что и на request)

	@username nvarchar(32)
AS
BEGIN
	-- ОТЛАДКА
    -- exec as_print @str='api_ruPostDelivery_response'
	insert into as_trace (text, username, code , created  ) values( @response, @username, 'api_ruCDEKTariff_response' , GETDATE() )

    DECLARE @json1 NVARCHAR(MAX)  = N''
	SET @json1 = @response

    -- Для проверки правильности JSON формата существует функция ISJSON, которая возвращает 1, если это JSON, 0 — если нет и NULL, если был передан NULL
    DECLARE @presentJSON bit = 0
    SELECT @presentJSON = ISNULL( ISJSON( @json1 ) , 0 )

    IF @presentJSON <> 1
    BEGIN
        SELECT 'Ошибка! Строка @response не является JSON!' Msg, 0 Result, @response Response
        RETURN
    END

	-- Обработка ошибки в ответе
    DECLARE @presentError bit = 0, @errorText NVARCHAR(MAX), @errorCode NVARCHAR(MAX), @errorMsg NVARCHAR(MAX)

	DECLARE @deliveryDateMin NVARCHAR(MAX)
          , @deliveryDateMax NVARCHAR(MAX)
          , @tariffId		 NVARCHAR(MAX)
          , @priceByCurrency NVARCHAR(MAX)
          , @currency		 NVARCHAR(MAX)
           --
    DECLARE @deliveryDaysMin NVARCHAR(MAX)
          , @deliveryDaysMax NVARCHAR(MAX)

    SELECT @presentError = IIF( JSON_QUERY( @json1, '$.error[0]') IS NULL  , 0 , 1 )  -- Проверка массива JSON_QUERY  '$.error[0]'
           , @errorCode    = JSON_VALUE( @json1, '$.error[0].code')
           , @errorMsg     = JSON_VALUE( @json1, '$.error[0].text')
           -- Данные
           , @deliveryDaysMin = JSON_VALUE( @json1, '$.result.deliveryPeriodMin')
	 	   , @deliveryDaysMax = JSON_VALUE( @json1, '$.result.deliveryPeriodMax')

           , @deliveryDateMin = JSON_VALUE( @json1, '$.result.deliveryDateMin')
	 	   , @deliveryDateMax = JSON_VALUE( @json1, '$.result.deliveryDateMax')

           , @tariffId =		JSON_VALUE( @json1, '$.result.tariffId')
	 	   , @priceByCurrency = JSON_VALUE( @json1, '$.result.priceByCurrency')
	 	   , @currency =		JSON_VALUE( @json1, '$.result.currency')

      IF @presentError = 1
      BEGIN
		  SET @errorText = 'code:'+ ISNULL( @errorCode, '' ) +' text:'+ ISNULL( @errorMsg, '' )
          SELECT 'Ошибка! Запрос @response вернул ошибку! '+ ISNULL( @errorText, '' ) Msg, 0 Result, @response Response
          RETURN
      END

    DECLARE @deliveryText NVARCHAR(MAX)
    -- Срок доставки: от 2 до 4 дней.
	SET @deliveryText = 'Срок доставки: от ' + ISNULL( @deliveryDaysMin, '' )+' до '+ISNULL( @deliveryDaysMax, '' )+' дней. '
					   +'Даты: с ' + ISNULL( @deliveryDateMin, '' )+' по '+ISNULL( @deliveryDateMax, '' )+'. '
					   +'Сумма: '  + ISNULL( @priceByCurrency, '' )+' '   +ISNULL( @currency, '' )+'.'
	-- SELECT 1
	select @deliveryText as Msg, 1 Result, @response Response

	-- SELECT 2 Внешние действия

END

Платформа Falcon Space

Это снижение стоимости владения

за счет меньшего количества людей для поддержки

Это быстрое внесение изменений

по ходу эксплуатации программы

Это современный интерфейс

полная адаптация под мобильные устройства

Бесплатное обучение разработке на Falcon Space

Вы можете разрабатывать самостоятельно или сотрудничать с нами в плане веб-разработки на платформе Falcon Space.
Примечание