Интеграция 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. Услуги (тарифы) и режимы доставки СДЭК

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

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

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

Пример текста запроса - 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