Интеграции
21 Mar

Интеграция по API с ТК СДЭК

#интеграция
#api
#интеграциясдэк
#сдэк
#транспортныекампании

Всем привет!

Начинаем писать серию статей по интеграции с разными ТК (транспортными кампаниями) через API.

Такая интеграция может пригодиться например интернет-магазинам, маркет плейсам и т.д.

У вас может возникнуть вопрос - почему бы нам не зайти на сайт документации и не посмотреть там? Мы вам ответим, что документации бывают сложные и объемные для понимания. Здесь же вы найдете конкретные, простые шаги для интеграции с ТК СДЭК.
Мы не будем здесь дублировать API документацию, а лишь структурируем информацию в ней для более простого восприятия.

Сегодня поговорим об интеграции ТК СДЭК, а именно:

  • получение списка ПВЗ
  • расчет стоимости перевозки
  • создание заказа на перевозку
  • получение информации о заказе
  • удаление заказа

сдек интеграция

Ссылка на API документацию СДЭК тут

Подготовка

API интеграция с ТК СДЭК работает в 2х режимах:

  • Боевой - подпишите договор и получите client_id и client_secret для доступа к интеграции. Используйте хост https://api.cdek.ru
  • Тестовый - для доступа используйте:
    • хост - https://api.edu.cdek.ru
    • client_id - wqGwiQx0gg8mLtiEKsUinjVSICCjtTEP
    • client_secret - RmAmgvSgSl1yirlz9QupbzOJVqhCxcP5

Авторизация

Любая интеграция начинается с авторизации.
В API ТК СДЭК авторизация реализована с применением OAuth 2.0 протокола.

На адрес /v2/oauth/token необходимо отправить POST запрос с query параметрами:

grant_type - Тип аутентификации. Доступное значение: client_credentials
client_id - Идентификатор клиента
client_secret - Секретный ключ клиента

JSON ответ:

{
    "access_token": "string", // JWT-токен
    "token_type": "string", // Тип токена. Всегда принимает значение bearer
    "expires_in": 0, // Срок действия токена (по умолчанию 3600 секунд)
    "scope": "string", // Область действия токена
    "jti": "string" // Уникальный идентификатор токена
}

Берем JWT токен и вставляем его в header всех запросов: Authorization: Bearer <Токен>

Получение списка ПВЗ

Для получения списка всех ПВЗ ТК СДЭК необходимо отправить GET запрос на адрес /v2/deliverypoints с необязательными query параметрами. С помощью параметров можно отфильтровать ПВЗ по типу, городу и другим критериям.

В ответе вы получите массив объектов ПВЗ с указанием кода, города, страны, режима работы и других параметров (см документацию).

Расчет стоимости перевозки

Данный этап является важным в интеграции так как предоставляет расчет стоимости по доступным тарифам и срокам доставки.

Для того что бы рассчитать стоимость доставки необходимо отправить POST запрос на адрес /v2/calculator/tarifflist c JSON параметрами.

Пройдемся по важным параметрам расчета стоимости подробнее:

  • type - тип заказа. 1 - интернет-магазин с особыми тарифами по договору с ИМ. 2 - доставка со стандартными тарифами и договором. По-умолчанию 1.
  • from_location - населенный пункт откуда будет отправление. Обязательный параметр. Это объект в котором достаточно указать code.
  • to_location - населенный пункт куда будет отправление. Обязательный параметр. Это объект в котором достаточно указать code.
  • packages - места / упаковки в заказе. Обязательный параметр. Это массив упаковок с весом и габаритами. Достаточно указать weight.

Все параметры можно найти в документации

В ответе вы получите массив тарифов с ценами и продолжительностью доставки.

Сделаем запрос на расчет стоимости доставки: 

curl --location 'https://api.edu.cdek.ru/v2/calculator/tarifflist' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6WyJsb2NhdGlvbjphbGwiLCJvcmRlcjphbGwiLCJwYXltZW50OmFsbCJdLCJleHAiOjE3NDI3NDI0MjUsImF1dGhvcml0aWVzIjpbInNoYXJkLWlkOnJ1LTAxIiwiY2xpZW50LWNpdHk60J3QvtCy0L7RgdC40LHQuNGA0YHQuiwg0J3QvtCy0L7RgdC40LHQuNGA0YHQutCw0Y8g0L7QsdC70LDRgdGC0YwiLCJhY2NvdW50LWxhbmc6cnVzIiwiY29udHJhY3Q60JjQnC3QoNCkLdCT0JvQky0yMiIsImFwaS12ZXJzaW9uOjEuMSIsImFjY291bnQtdXVpZDplOTI1YmQwZi0wNWE2LTRjNTYtYjczNy00Yjk5YzE0ZjY2OWEiLCJjbGllbnQtaWQtZWM1OmVkNzVlY2Y0LTMwZWQtNDE1My1hZmU5LWViODBiYjUxMmYyMiIsImNvbnRyYWN0LWlkOmRlNDJjYjcxLTZjOGMtNGNmNS04MjIyLWNmYjY2MDQ0ZThkZiIsImNsaWVudC1pZC1lYzQ6MTQzNDgyMzEiLCJzb2xpZC1hZGRyZXNzOmZhbHNlIiwiY29udHJhZ2VudC11dWlkOmVkNzVlY2Y0LTMwZWQtNDE1My1hZmU5LWViODBiYjUxMmYyMiIsImZ1bGwtbmFtZTrQotC10YHRgtC40YDQvtCy0LDQvdC40LUg0JjQvdGC0LXQs9GA0LDRhtC40Lgg0JjQnCJdLCJqdGkiOiJvQUVJMS1xLWlMQ3RZZzgxNk9fdHNOWkNNdUkiLCJjbGllbnRfaWQiOiJ3cUd3aVF4MGdnOG1MdGlFS3NVaW5qVlNJQ0NqdFRFUCJ9.hyp3aF2Z7HSqUHQDhPWaZ0l7wbAy5vMOZ4Xm0nmUmgU0T8_oKWy2C92OeWlb0j8dJfeMcycGpxohOTFAoqTfADY5QWEa5QSInp0kklLcZlX5PehIV0RQRbRpa3brYmv9ZGeerefmCPm5qiPrK7cQwU0ujGxLStfU5HvwVUq0KBcrr1vLU283riZ1Kf_U2tAPUK3Y7WIerGcaiVGKpJEfD5ij3cvDW4m0drU9Glb0_5P4FZfbHOSUO0cZfVsLaqoanjegHZGuU3X1RXJP32zgatm8uaodcoTg6dtDnetJXSzz6ikTEIpJEEwloDcF-1KZHmO77fUSzjUEZGPnl26ybA' \
--data '{
    "type": 2,
    "from_location": {
         "code": 44 
    },
    "to_location" : {
        "code": 278 
    },
    "packages": [
        {
            "weight" : 1000
        }
    ]
}'

И получим ответ:

{
  "tariff_codes": [
    {
      "tariff_code": 751,
      "tariff_name": "Сборный груз склад-склад",
      "tariff_description": "Наземная доставка сборных горузов",
      "delivery_mode": 4,
      "delivery_sum": 6600.0, // Стоимость доставки
      "period_min": 8, // Минимальное время доставки (в рабочих днях)
      "period_max": 12, // Максимальное время доставки (в рабочих днях)
      "calendar_min": 8, // Минимальное время доставки (в календарных дня)
      "calendar_max": 12 // Максимальное время доставки (в календарных дня)
    },
    {
      "tariff_code": 139,
      "tariff_name": "Посылка дверь-дверь",
      "tariff_description": "",
      "delivery_mode": 1,
      "delivery_sum": 870.0,
      "period_min": 8,
      "period_max": 12,
      "calendar_min": 8,
      "calendar_max": 12
    },
    {
      "tariff_code": 138,
      "tariff_name": "Посылка дверь-склад",
      "tariff_description": "",
      "delivery_mode": 2,
      "delivery_sum": 730.0,
      "period_min": 8,
      "period_max": 12,
      "calendar_min": 8,
      "calendar_max": 12
    }
  ]
}

Как видите в ТК СДЭК для расчета стоимости не нужно указывать ПВЗ или адрес квартиры, а достаточно указать населенный пункт и в ответе получить цены на разные тарифы такие как "склад - склад", "склад - дверь" и т.д.

Создание заказа на перевозку

После успешного расчета стоимости доставки можем переходить к созданию заказа на доставку.

Для создания заказа необходимо отправить POST запрос на адрес /v2/orders c JSON параметрами.

Пройдемся по важным параметрам создания заказа подробнее:

  • type - тип заказа. 1 - интернет-магазин с особыми тарифами по договору с ИМ. 2 - доставка со стандартными тарифами и договором. По-умолчанию 1.
  • tariff_code - код тарифа. Обязательное поле (получается из расчета стоимости)
  • from location - адрес отправления. Обязательное поле, если заказ с тарифом "от двери". Это объект в котором достаточно указать address.
  • to_location - адрес получения. Обязательное поле, если заказ с тарифом "до двери". Это объект в котором достаточно указать address.
  • shipment_point - код ПВЗ СДЭК, на который будет производиться самостоятельный привоз клиентом. Обязательное поле, если заказ с тарифом "от склада".
  • delivery_point - код ПВЗ СДЭК, на который будет доставлена посылка. Обязательное поле, если заказ с тарифом "до склада" или "до постамата".
  • sender - отправитель. Обязательное поле, если заказ типа "доставка", не обязательное. если тип заказ "интернет-заказ". Это объект, в котором достаточно указать name, phones (поле number в массиве номеров телефона) и company.
  • recipient - получатель. Обязательное поле. Это объект, в котором достаточно указать name и phones (поле number в массиве номеров телефона).
  • packages - места / упаковки в заказе. Обязательный параметр. Это массив упаковок с весом и габаритами. Достаточно указать number (порядковый номер упаковки), weight и comment.

Все параметры для создания заказа можно найти в документации

В ответе вы получите uuid, по которому можно получить информацию и удалить заказ.

Сделаем запрос на создание заказа "дверь-склад":

curl --location 'https://api.edu.cdek.ru/v2/orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6WyJsb2NhdGlvbjphbGwiLCJvcmRlcjphbGwiLCJwYXltZW50OmFsbCJdLCJleHAiOjE3NDI3NDI0MjUsImF1dGhvcml0aWVzIjpbInNoYXJkLWlkOnJ1LTAxIiwiY2xpZW50LWNpdHk60J3QvtCy0L7RgdC40LHQuNGA0YHQuiwg0J3QvtCy0L7RgdC40LHQuNGA0YHQutCw0Y8g0L7QsdC70LDRgdGC0YwiLCJhY2NvdW50LWxhbmc6cnVzIiwiY29udHJhY3Q60JjQnC3QoNCkLdCT0JvQky0yMiIsImFwaS12ZXJzaW9uOjEuMSIsImFjY291bnQtdXVpZDplOTI1YmQwZi0wNWE2LTRjNTYtYjczNy00Yjk5YzE0ZjY2OWEiLCJjbGllbnQtaWQtZWM1OmVkNzVlY2Y0LTMwZWQtNDE1My1hZmU5LWViODBiYjUxMmYyMiIsImNvbnRyYWN0LWlkOmRlNDJjYjcxLTZjOGMtNGNmNS04MjIyLWNmYjY2MDQ0ZThkZiIsImNsaWVudC1pZC1lYzQ6MTQzNDgyMzEiLCJzb2xpZC1hZGRyZXNzOmZhbHNlIiwiY29udHJhZ2VudC11dWlkOmVkNzVlY2Y0LTMwZWQtNDE1My1hZmU5LWViODBiYjUxMmYyMiIsImZ1bGwtbmFtZTrQotC10YHRgtC40YDQvtCy0LDQvdC40LUg0JjQvdGC0LXQs9GA0LDRhtC40Lgg0JjQnCJdLCJqdGkiOiJvQUVJMS1xLWlMQ3RZZzgxNk9fdHNOWkNNdUkiLCJjbGllbnRfaWQiOiJ3cUd3aVF4MGdnOG1MdGlFS3NVaW5qVlNJQ0NqdFRFUCJ9.hyp3aF2Z7HSqUHQDhPWaZ0l7wbAy5vMOZ4Xm0nmUmgU0T8_oKWy2C92OeWlb0j8dJfeMcycGpxohOTFAoqTfADY5QWEa5QSInp0kklLcZlX5PehIV0RQRbRpa3brYmv9ZGeerefmCPm5qiPrK7cQwU0ujGxLStfU5HvwVUq0KBcrr1vLU283riZ1Kf_U2tAPUK3Y7WIerGcaiVGKpJEfD5ij3cvDW4m0drU9Glb0_5P4FZfbHOSUO0cZfVsLaqoanjegHZGuU3X1RXJP32zgatm8uaodcoTg6dtDnetJXSzz6ikTEIpJEEwloDcF-1KZHmO77fUSzjUEZGPnl26ybA' \
--data '{
    "tariff_code" : 123,
    "type": 2,
    "from_location": {
         "address": "г. Москва, ул. Тверская, 10" 
    },
    "delivery_point" : "KSK1",
    "packages": [
        {
            "number":1,
            "weight" : 1000,
            "comment": "Комментарий к упаковке"
        }
    ],
    "sender": {
        "company": "ООО Рога и копыта",
        "name": "Петров Петр Петрович",
        "phones": [
            {
                "number": "89992345667"
            }
        ]
    },
    "recipient" : {
        "name": "Иванов Иван Иванович",
        "phones": [
            {
                "number": "89992345667"
            }
        ]
    }
}'

И получим ответ:

{
  "entity": {
    "uuid": "c708db98-7520-4566-ba44-f15e9e2f7c2b"
  },
  "requests": [
    {
      "request_uuid": "be49da4e-86ec-4b71-a990-6652f2f15024",
      "type": "CREATE",
      "date_time": "2025-03-23T14:22:19+0000",
      "state": "ACCEPTED"
    }
  ],
  "related_entities": []
}

Получение информации о заказе

Итак, мы рассчитали стоимость и создали заказ. В дальнейшем может понадобиться посмотреть детали заказа.

Для получения информации по заказу необходимо отправить GET запрос на адрес /v2/orders/{uuid}, где {uuid} - это идентификатор созданного заказа.

В ответе вы получите информацию по заказу такую как статусы, отправителя и т.д. Подробное описание информации о заказе можно найти в документации

Отправим запрос на получение информации по нашему заказу:

curl --location 'https://api.edu.cdek.ru/v2/orders/c708db98-7520-4566-ba44-f15e9e2f7c2b' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6WyJsb2NhdGlvbjphbGwiLCJvcmRlcjphbGwiLCJwYXltZW50OmFsbCJdLCJleHAiOjE3NDI3NDI0MjUsImF1dGhvcml0aWVzIjpbInNoYXJkLWlkOnJ1LTAxIiwiY2xpZW50LWNpdHk60J3QvtCy0L7RgdC40LHQuNGA0YHQuiwg0J3QvtCy0L7RgdC40LHQuNGA0YHQutCw0Y8g0L7QsdC70LDRgdGC0YwiLCJhY2NvdW50LWxhbmc6cnVzIiwiY29udHJhY3Q60JjQnC3QoNCkLdCT0JvQky0yMiIsImFwaS12ZXJzaW9uOjEuMSIsImFjY291bnQtdXVpZDplOTI1YmQwZi0wNWE2LTRjNTYtYjczNy00Yjk5YzE0ZjY2OWEiLCJjbGllbnQtaWQtZWM1OmVkNzVlY2Y0LTMwZWQtNDE1My1hZmU5LWViODBiYjUxMmYyMiIsImNvbnRyYWN0LWlkOmRlNDJjYjcxLTZjOGMtNGNmNS04MjIyLWNmYjY2MDQ0ZThkZiIsImNsaWVudC1pZC1lYzQ6MTQzNDgyMzEiLCJzb2xpZC1hZGRyZXNzOmZhbHNlIiwiY29udHJhZ2VudC11dWlkOmVkNzVlY2Y0LTMwZWQtNDE1My1hZmU5LWViODBiYjUxMmYyMiIsImZ1bGwtbmFtZTrQotC10YHRgtC40YDQvtCy0LDQvdC40LUg0JjQvdGC0LXQs9GA0LDRhtC40Lgg0JjQnCJdLCJqdGkiOiJvQUVJMS1xLWlMQ3RZZzgxNk9fdHNOWkNNdUkiLCJjbGllbnRfaWQiOiJ3cUd3aVF4MGdnOG1MdGlFS3NVaW5qVlNJQ0NqdFRFUCJ9.hyp3aF2Z7HSqUHQDhPWaZ0l7wbAy5vMOZ4Xm0nmUmgU0T8_oKWy2C92OeWlb0j8dJfeMcycGpxohOTFAoqTfADY5QWEa5QSInp0kklLcZlX5PehIV0RQRbRpa3brYmv9ZGeerefmCPm5qiPrK7cQwU0ujGxLStfU5HvwVUq0KBcrr1vLU283riZ1Kf_U2tAPUK3Y7WIerGcaiVGKpJEfD5ij3cvDW4m0drU9Glb0_5P4FZfbHOSUO0cZfVsLaqoanjegHZGuU3X1RXJP32zgatm8uaodcoTg6dtDnetJXSzz6ikTEIpJEEwloDcF-1KZHmO77fUSzjUEZGPnl26ybA'

И вот наш ответ:

{
  "entity": {
    "uuid": "c708db98-7520-4566-ba44-f15e9e2f7c2b",
    "type": 2,
    "tariff_code": 123,
    "delivery_point": "KSK1",
    "sender": {
      "company": "ООО Рога и копыта",
      "name": "Петров Петр Петрович",
      "phones": [
        {
          "number": "89992345667"
        }
      ]
    },
    "recipient": {
      "name": "Иванов Иван Иванович",
      "phones": [
        {
          "number": "89992345667"
        }
      ]
    },
    "from_location": {
      "address": "г. Москва, ул. Тверская, 10"
    },
    "packages": [
      {
        "number": "1",
        "weight": 1000,
        "comment": "Комментарий к упаковке"
      }
    ],
    "statuses": [
      {
        "code": "ACCEPTED",
        "name": "Принят",
        "date_time": "2025-03-23T14:55:47+0000",
        "city": "Офис СДЭК",
        "deleted": false
      }
    ]
  },
  "requests": [
    {
      "request_uuid": "0bb4c892-e9b2-4521-8ab4-2b355daaf225",
      "type": "CREATE",
      "date_time": "2025-03-23T14:55:47+0000",
      "state": "ACCEPTED"
    }
  ],
  "related_entities": []
}

Удаление заказа

В ваших бизнес-процессах может появиться необходимость удалить заказ.
В ТК СДЭК удаление заказа возможно только в статусе "Создан".

Для удаления заказа необходимо отправить DELETE запрос на адрес /v2/orders/{uuid}, где {uuid} - это идентификатор заказа.

При успешном удалении вы получите uuid удаленного заказа.

Например удалим наш заказ:

curl --location --request DELETE 'https://api.edu.cdek.ru/v2/orders/c708db98-7520-4566-ba44-f15e9e2f7c2b' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6WyJsb2NhdGlvbjphbGwiLCJvcmRlcjphbGwiLCJwYXltZW50OmFsbCJdLCJleHAiOjE3NDI3NDI0MjUsImF1dGhvcml0aWVzIjpbInNoYXJkLWlkOnJ1LTAxIiwiY2xpZW50LWNpdHk60J3QvtCy0L7RgdC40LHQuNGA0YHQuiwg0J3QvtCy0L7RgdC40LHQuNGA0YHQutCw0Y8g0L7QsdC70LDRgdGC0YwiLCJhY2NvdW50LWxhbmc6cnVzIiwiY29udHJhY3Q60JjQnC3QoNCkLdCT0JvQky0yMiIsImFwaS12ZXJzaW9uOjEuMSIsImFjY291bnQtdXVpZDplOTI1YmQwZi0wNWE2LTRjNTYtYjczNy00Yjk5YzE0ZjY2OWEiLCJjbGllbnQtaWQtZWM1OmVkNzVlY2Y0LTMwZWQtNDE1My1hZmU5LWViODBiYjUxMmYyMiIsImNvbnRyYWN0LWlkOmRlNDJjYjcxLTZjOGMtNGNmNS04MjIyLWNmYjY2MDQ0ZThkZiIsImNsaWVudC1pZC1lYzQ6MTQzNDgyMzEiLCJzb2xpZC1hZGRyZXNzOmZhbHNlIiwiY29udHJhZ2VudC11dWlkOmVkNzVlY2Y0LTMwZWQtNDE1My1hZmU5LWViODBiYjUxMmYyMiIsImZ1bGwtbmFtZTrQotC10YHRgtC40YDQvtCy0LDQvdC40LUg0JjQvdGC0LXQs9GA0LDRhtC40Lgg0JjQnCJdLCJqdGkiOiJvQUVJMS1xLWlMQ3RZZzgxNk9fdHNOWkNNdUkiLCJjbGllbnRfaWQiOiJ3cUd3aVF4MGdnOG1MdGlFS3NVaW5qVlNJQ0NqdFRFUCJ9.hyp3aF2Z7HSqUHQDhPWaZ0l7wbAy5vMOZ4Xm0nmUmgU0T8_oKWy2C92OeWlb0j8dJfeMcycGpxohOTFAoqTfADY5QWEa5QSInp0kklLcZlX5PehIV0RQRbRpa3brYmv9ZGeerefmCPm5qiPrK7cQwU0ujGxLStfU5HvwVUq0KBcrr1vLU283riZ1Kf_U2tAPUK3Y7WIerGcaiVGKpJEfD5ij3cvDW4m0drU9Glb0_5P4FZfbHOSUO0cZfVsLaqoanjegHZGuU3X1RXJP32zgatm8uaodcoTg6dtDnetJXSzz6ikTEIpJEEwloDcF-1KZHmO77fUSzjUEZGPnl26ybA'

Заказ ушел на удаление:

{
  "entity": {
    "uuid": "c708db98-7520-4566-ba44-f15e9e2f7c2b"
  },
  "requests": [
    {
      "request_uuid": "76384073-42d0-45b0-ba30-508b01af48ce",
      "type": "DELETE",
      "date_time": "2025-03-23T14:57:32+0000",
      "state": "ACCEPTED"
    }
  ],
  "related_entities": []
}

Обратите внимание что после успешного выполнения, заказ удаляется не сразу, а создается задача на его удаление.

В этой статье мы рассмотрели базовые методы интеграции вашего сервиса с ТК СДЭК. Мы не стали углубляться в более сложные методы, поскольку уверены, что после настройки базовой интеграции с ТК СДЭК, вам будет легко разобраться с более сложными вариантами. В каждой транспортной компании существуют похожие методы интеграции, однако их реализация может существенно отличаться.

В следующих статьях мы подробнее расскажем о нюансах интеграции с ТК ПЭК, Яндекс.Доставка, Деловые Линии, Байкал Сервис и другими.

Комментарии (1)
Коммент. (1)
Евгений • 21 Mar
Интересно!

Обсуждения

Категории

Теги