История изменений

Введение

Общее описание

В документе представлен порядок и формат обмена данными между Компанией «СДЭК» и клиентом Интернет-Магазином (далее ИМ) или партнером, представляющим интернет-магазины.

Ответы на часто задаваемые вопросы можно увидеть тут: http://www.cdek.ru/faq/

Вопросы и пожелания клиентов принимаем на e-mail: integrator@cdek.ru.

Условные обозначения

Термины и определения

ИС — любая информационная система: программное обеспечение, ERP – решение, сайт ИМ.

Интеграция — передача данных, находящихся в различных источниках (ИС)  и предоставление данных пользователям в унифицированном виде.

API (англ. Application Programming Interface) – интерфейс прикладного программирования, интерфейс программирования приложений. Это набор готовых функций, структур и констант, предоставляемых приложением (библиотекой, сервисом) для использования во внешних программных продуктах (ИС).

HTTP (англ. Hyper Text Transfer Protocol) – протокол передачи гипертекста. Это протокол прикладного уровня передачи данных (изначально – в виде гипертекстовых документов в формате HTML).

HTTPS (англ. Hyper Text Transfer Protocol Secure) – расширение протокола HTTP, поддерживающее шифрование. Данные, передаваемые по протоколу HTTP, «упаковываются» в криптографический протокол SSL или TLS. В отличие от HTTP для  HTTPS по умолчанию используется ТСР-порт 443.

ИМ — интернет-магазин, далее по тексту ИМ – клиент или партнер СДЭК с договором интернет-магазина.

Место (грузоместо, упаковка) — неделимая единица груза, отправляемая ИМ (может быть несколько в одном заказе).

Отправление (заказ) — сумма всех мест, единовременно отправляемых ИМ по одному направлению.

Объемный вес — расчетное значение веса, измеряется в кг. Расчет может быть произведен из указанных габаритов места по формуле длина * высота * ширина/5000. Это общепринятый у транспортных компаний алгоритм пересчета.

Физический вес – определяется взвешиванием погрузочного места на весах. Существуют вес груза нетто и брутто. Нетто — это чистый вес груза без упаковки, а брутто — вес груза в упакованном виде. 

Расчетный вес – вес, максимальный среди объемного и физического. Расчет стоимости услуг производится исходя из расчетного веса.

ПВЗ – пункт выдачи заказов получателю. Место, где получатель может самостоятельно забрать свой груз. ПВЗ могут быть как собственные склады СДЭК, так и терминалы выдачи грузов партнеров – почтоматы.

СД – курьерская служба доставки СДЭК.

Международный заказ - заказ, у которого страна отправителя не равна стране получателя и хотя бы одна страна не входит в Таможенный союз. 

Что нужно, чтобы осуществить интеграцию

1 шаг: Интеграция возможна только при наличии согласованного договора со СДЭК.

2 шаг: Представителю ИМ необходимо изучить документацию и часто задаваемые вопросы, представленные на сайте www.cdek.ru/clients/integrator.html

3 шаг: Выбрать подходящий для себя вариант интеграции:

• Готовые модули партнеров, представленные на сайте компании.

• Собственная реализация, если готовые решения по какой-либо причине не подходят.

4 шаг: С помощью тестовой учетной записи протестировать и настроить интеграцию.

• Если выбран готовый модуль партнеров, то за консультацией по настройке необходимо обращаться к разработчику или в службу поддержки данного модуля.

• Если реализуется собственное решение, то все предварительные настройки делаем под тестовой учетной записью.

5 шаг: После того как все проверено (протестировано, все вопросы решены), вам следует получить ключ доступа к "боевой" учетной записи (Account и Secure password) для интеграции. Ключи можно получить в личном кабинете СДЭК по ссылке: https://lk.cdek.ru/integration/index. Для этого нужно в личном кабинете в разделе "Интеграция" нажать кнопку "Создать ключ", затем в этом разделе появится идентификатор аккаунта и пароль.

6 шаг: Перейти на использование «боевой» учетной записи и работать далее в штатном режиме.

1. Общие положения

XML API компании является решением, позволяющим взаимодействовать с сервисом в режиме онлайн с помощью стандартных протоколов и форматов НТТР/ НТТРS и XML.

XML API позволяет реализовать следующую функциональность:

1. Список ПВЗ - используется для получения актуального списка ПВЗ с подробной информацией о нем для дальнейшего использования в ИС ИМ. 

2. Регистрация заказа - позволяет на основании документов, содержащих данные по заказам Клиента в акте приема-передачи/ТТН (товарно-транспортная накладная), создать в базе СДЭК накладные, по которым производится вся транспортировка.

3. Обновление заказа - используется для изменения созданной накладной. Возможно изменять следующие данные в накладной: сумму наложенного платежа, данные о получателе, все данные мест и позиций товаров.

4. Удаление заказа - предоставляет возможность удалить из базы СДЭК заказы в случае их ошибочного импорта или существенных изменений их характеристик. Условием возможности удаления заказа является отсутствие движения груза на складе СДЭК (статус заказа «Создан»).

5. Печатная форма квитанции к заказу - используется для формирования печатной формы квитанции к заказу в формате pdf. 

6.  Заявка на вызов курьера  - документ, содержащий информацию по вызову курьера, если необходимо забрать груз со склада ИМ. Груз доставляется до склада СДЭК.

Условия формирования заявки:

• диапазон времени для приезда курьера не должен быть меньше 3 часов.

Предварительно осуществляется прозвон ИМ по указанному контактному телефону для подтверждения вызова курьера, уточнения информации.

7. Информация о результате прозвона - документ, содержащий данные по прозвону получателя о договоренности доставки до двери или забора (приема груза) со склада в зависимости от режима доставки.

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

• ИМ самостоятельно предоставляет в СДЭК расписание получателя для доставки/забора;

• изменения в заказе реквизитов получателя (контактное лицо, адрес доставки, телефон);

• изменения суммы по оплате за товар.

Данные передаются по уже существующим в базе СДЭК заказам. Также в документе «Список заказов на доставку» возможна передача данных «Прозвон получателя» по новым заказам. Расписание доставки может быть передано только на один день.

Если попытка доставки по расписанию была неудачной, ИМ снова отправляет расписание доставки. Отчет о неудачных попытках доставки предоставляется ИМ в документе «Статусы заказов» (Причины задержки).

8. Печать ШК места - используется для формирования печатной формы этикетки для упаковки в формате pdf.

9. Отчет "Статусы заказов" - позволяет отслеживать следующую информацию по заказам:

• последний статус заказа на доставку и возврата в указанном периоде;
• полную историю статусов заказа на доставку и возврата;
• последний статус «возвратного» заказа («возвратной накладной»);
• полную историю статусов «возвратного» заказа («возвратной накладной»);
• данные о вручении посылки (когда, кому);
• неудавшиеся попытки доставки в разрезе расписания доставки, предоставленного ИМ.

Запрос можно формировать как за определенный период, в который произошли изменения статусов, так и по конкретному списку посылок.

10. Отчет "Информация по заказам" - позволяет отслеживать следующую информацию по заказам:

• код тарифа, по которому был доставлен заказ;
• стоимость выставленных услуг СДЭК по заказу (т.е. сумму на которую будет выставлен счет);
• дата последнего изменения суммы заказа;
• способ передачи заказа получателю (курьер, самозабор);
• тип оплаты наложенного платежа.

11. Список регионов – используется для получения детальной информации о регионах.

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

12. Список городов – используется для получения детальной информации о городах.

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

13. Калькулятор - позволяет рассчитывать стоимость доставки одного отправления по заданным входным параметрам. 

1.1. Идентификаторы посылок и информация на ярлыке

Предпочтительным для компании СДЭК является использование ее собственных ярлыков (квитанций накладных), которые можно получить в виде файла PDF, используя XML API. В случае использования собственного ярлыка, он обязательно должен содержать информацию о получателе (ФИО, адрес, телефон) и любой из идентификаторов:

• Идентификатор посылки СДЭК. Рекомендуется в штрих-коде указывать номер накладной СДЭК (в формате обмена данными это атрибут «DispatchNumber»).

• Идентификатор заказа ИМ – номер заказа (атрибут «Order. Number»).

• Идентификатор грузоместа (упаковки) – штрих-код упаковки (атрибут «Package.BarCode»). - устаревшее поле

Все штрих-коды должны иметь расшифровку закодированного текста под или над штрих-кодом, чтобы иметь возможность вводить вручную закодированную информацию. Рекомендуется для печати использовать стандарт Code 128.

1.2. Ограничение срока хранения информации в системе

Данные о посылках без движения груза (в статусе «Создан») хранятся в системе СДЭК в течение 30 дней от даты акта. Удаление производится автоматически каждый день в 23-00 NSK. Поэтому отправку запроса на создание заказов на доставку необходимо осуществлять перед реальной отправкой товара (груза).

1.3. Форматы данных и их кодировка

Размерности:

Типы данных:

Float – число с плавающей точкой. В качестве разделителя используется именно точка, а не запятая.

String – строка символов заданной длины. Длина строки указывается в скобках.

Integer – целое число.

Boolean – (булевы значения) – принимает значения 0 или 1.

Во всех модулях дата/время передается в формате UTC (YYYY-MM-DDТhh:mm:ss), если иное не указано в описании.

Date Time – дата и время в формате ISO 8601:2004:YYYY-MM-DDThh:mm:ss+hh:mm.

ПРИМЕР: Для даты 21 декабря  2012 года 11 часов 49 минут 49 секунд, время московское: 2012-12-21Т11:49:49+03:00

Может содержать неполную информацию. Например, только часы и минуты (15:30), в таком случае используется часовой пояс UTC+00:00.

Date – дата в формате ISO 8601:2004:YYYY-MM-DD.

Time – время в формате hh:mm:ss.

Email – адрес электронной почты длиной до 255 символов. Должен соответствовать RFC 2822. Основные требования: 

допустимы только символы латинского алфавита, числа 0-9, символы: ! $ & * - = \ ^ `| ~ #% '+ /? _ { } 

Домен (часть почты после @) должен существовать.
Email должен содержать только один символ @

Внимание! Кириллические адреса (например: пример@пример.рф) не допустимы. 

Phone – телефонный номер. Примерный формат для РФ: +7 (ХХХ) ХХХ-ХХ-ХХ, строковый тип данных

Данные передаются в формате XML в кодировке UTF-8, при этом необходимо учитывать, что в значениях полей нельзя использовать символы разметки XML (< > & " ').

1.4. Авторизация клиентов

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

Идентификация ИМ осуществляется двумя параметрами:

Для обеспечения безопасности при передаче/запросе данных ИМ должен передавать значение поля secure, вычисляемое по алгоритму:

secure = md5(date.'&'. secure password), где

secure password – пароль, выданный компанией СДЭК по запросу;

date – дата документа.

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

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

1.5. Тестовые учетные записи и их ограничения

Для облегчения процесса интеграции компанией СДЭК предоставляются отдельные тестовые учетные записи:

Посылки для тестовых учетных записей не будут обрабатываться и доставляться. 

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

После реализации АPI проводится тестирование интеграции. Тестирование состоит из нескольких этапов:

• Тестирование обмена запросами подразумевает собой проверку структуры передаваемых данных на корректность, а также проверку типов данных и значений, передаваемых в параметрах тестируемых методов.

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

По завершению отладки ИМ сообщает о готовности переключиться на боевую учетную запись. При этом у клиента обязательно должен быть договор со СДЭК. Для этого нужно в личном кабинете, в разделе Интеграция нажать кнопку «Создать ключ», затем в этом разделе появится Идентификатор аккаунта и Пароль.

1.6. Уведомления

ИМ имеет возможность получать уведомления о результате отправки данных на электронную почту. Уведомления содержат информацию как об удачной загрузке заказов, так и об ошибках передачи данных. Список e-mail адресов передается СДЭКу вместе с запросом на учетную запись. От данных уведомлений можно отписаться, но следует помнить, что все рассылки о проведении технических работ и изменениях в протоколе также высылаются на данный адрес.

Все уведомления приходят с электронного адреса: noreply@cdek.ru в формате UTF-8.

1.7. Обратная связь

Контактная информация ГК «СДЭК»:

Основной сайт:  http://cdek.ru

Телефон единой справочной службы: 8-800-550-1409 (звонок бесплатный).

Главный офис: 630007, Россия, г. Новосибирск, ул. Большевистская, д. 101

Если у вас возникли вопросы, или Вы нашли ошибку,  вы можете обратиться в службу технической поддержки СДЭК по электронной почте integrator@cdek.ru. Рекомендуем в теме письма указывать «Интеграция СДЭК, клиент Название Вашей Компании, Номер Договора, если есть».

2. Алгоритм работы ИМ с интеграцией СДЭК

Рекомендованный алгоритм работы:

1. В ИС ИМ производится подготовка информации о заказах. Заказы можно группировать в единый реестр по любым характеристикам, например, по дате передачи груза на доставку, или передавать каждый отдельно сразу как появился.

2. Из ИС производится регистрация заказов в СД с тарифом от склада.

3. В ИС необходимо осуществить проверку, что СД приняла информацию о заказе:

• если хотя бы один заказ был принят, то можно готовить груз для передачи в СД;
• просмотреть список ошибок, внести изменения в заказы в соответствии с рекомендациями по списку ошибок и повторить отправку запроса.

4. При необходимости можно сохранить в своей ИС список номеров накладных СД (можно получить в ответ на запрос регистрации заказов). 

5. Распечатать штрих-коды мест и наклеить на грузоместа.

6. Распечатать квитанции к заказу и приложить их к грузу.

7. Распечатать акт приема-передачи, если осуществляется передача консолидированного груза в СД. Акт приема-передачи можно найти в договоре или использовать свой. 

8. При необходимости можно осуществить вызов курьера для забора консолидированного груза. Данная процедура не обязательна при условии, что ИМ сам доставит груз в СД. Для осуществления вызова курьера рекомендуем использовать запрос на «Вызов курьера» . Курьер приедет по указанному адресу в соответствии с заявкой и произведет забор груза по акту и отвезет его на склад СД для дальнейшей транспортировки.

9. СД после приемки груза на склад произведет расконсолидацию груза и будет осуществлять доставку каждого груза отдельно в соответствии с местом назначения и выбранной услугой (тарифом) доставки.

10. ИС может в соответствии с внутренним распорядком запросить «Статус заказа» и отобразить статус СД в своей ИС или же сопоставить статус СД с аналогичным статусом ИС и отобразить уже свой статус для дальнейшего информирования сотрудников ИМ и получателя.

11.В случае изменения позиций товара или суммы наложенного платежа, заказ можно актуализировать, отправив запрос на обновление. 

12. При необходимости отменить заказ, по которому еще не была осуществлена работа (статус заказа «Создан»), нужно отправить запрос на удаление.

13. Если по условиям договора ИМ самостоятельно прозванивает (информирует) получателя, необходимо передать СДЭК информацию о договоренности доставки с помощью метода «Прозвон получателя» .

14. При получении конечного статуса «Не вручен» ожидается возврат груза отправителю. Отслеживать возврат груза можно точно также, как описано в п.9.

15. При получении конечного статуса «Вручен» можно прекратить отслеживание состояния доставки груза.

Рекомендуем поместить логотип СДЭК в хорошо просматриваемой части сайта, чтобы получатели видели, какая СД осуществляет доставку. Последнюю версию логотипа можно получить по ссылке https://classic.cdek.ru/website/edostavka/template/images/logo.png

2.1. Схема взаимодействия

Ниже представлен процесс взаимодействия и соответствующие статусы заказов в ИС СДЭК:

3. Общее описание API

Для взаимодействия с API необходимо отправить POST-запрос на URL: <базовый url интерфейса>/method.

Содержимое запроса (XML-файл) передается в переменной POST-запроса, либо в теле POST-запроса для некоторых методов.

Пример curl команды для одного и другого варианта запроса:

1. curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' 'http://integration.cdek.ru/integration/add' -d ‘xml_request=<?xml ...’'

2. curl -X POST --header 'Content-Type: application/xml' 'http://integration.cdek.ru/integration/addRaw' -d ‘<?xml ...’'

Для второго варианта (передачи в теле запроса) путь к методу аналогичен первому варианту, но содержит в конце пути суффикс Raw

3.1. Базовый URL интерфейса

3.2. Перечень методов API

3.3. Перевод ошибок интеграции

Для клиента, отправляющего запрос в API интеграции, определяется и устанавливается язык контрагента. Язык определяется по коду языка страны, к которой принадлежит контрагент:

• если язык определен, то вывод ошибок API интеграции осуществляется на языке контрагента;
• если код языка не определен, то для вывода ошибок используется язык по умолчанию.

4. Методы XML API

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

Метод используется для получения списка действующих ПВЗ, откуда клиент самостоятельно может забрать заказ.

Список ПВЗ может быть ограничен характеристиками, задаваемыми пользователем.

4.1.1. Описание передаваемых параметров запроса 

Для получения списка ПВЗ необходимо отправить GET запрос с параметрами, перечисленными ниже:

¹ Если одновременно указаны параметры cityid и citypostcode, то для определения города всех стран присутствия СДЭК приоритет отдается cityid.

4.1.2. Формат ответа

Сервер СДЭК вернет результат в виде XML :

Пример. Список ПВЗ

Запрос списка ПВЗ в городе Новосибирске, в которых разрешен прием наложенного платежа
http://integration.cdek.ru/pvzlist/v1/xml?weightmax=50&cityid=270&allowedcod=1

<PvzList>
	<Pvz Code="NSK71" PostalCode="630001" Name="На Холодильной" CountryCode="1" countryCodeIso="RU" CountryName="Россия" RegionCode="23" RegionName="Новосибирская обл." CityCode="270" City="Новосибирск" WorkTime="Сб-Вс 10:00-16:00, 					Пн-Пт 10:00-20:00" Address="ул. Холодильная, 13" FullAddress="Россия, Новосибирская обл., Новосибирск, ул. Холодильная, 13" AddressComment="Рядом с остановкой «Холодильная» ( по стороне нечетных домов Дуси Ковальчук) стоит дом , от 	дороги второе офисное помещение." Phone="+79913770310"Email="Bibikova.m@cdek.ru" qqId="" Note="" coordX="82.885359" coordY="55.049586" Type="PVZ" ownerCode="cdek" IsDressingRoom="true" IsHandout="true" IsReception="true" HaveCashless="true" AllowedCod="true" 	NearestStation="Холодильная" MetroStation="Заельцовская" Site="">
		<PhoneDetail number="+79913770310"/>
		<WorkTimeY day="1" periods="10:00/20:00"/>
		<WorkTimeY day="2" periods="10:00/20:00"/>
		<WorkTimeY day="3" periods="10:00/20:00"/>
		<WorkTimeY day="4" periods="10:00/20:00"/>
		<WorkTimeY day="5" periods="10:00/20:00"/>
		<WorkTimeY day="6" periods="10:00/16:00"/>
		<WorkTimeY day="7" periods="10:00/16:00"/>
	</Pvz>
	<Pvz Code="NSK33" PostalCode="630049" Name="На Дуси Ковальчук" CountryCode="1" countryCodeIso="RU" CountryName="Россия" RegionCode="23" RegionName="Новосибирская обл." CityCode="270" City="Новосибирск" WorkTime="Вс 10:00-16:00, 	Сб 10:00-16:00, Пн-Пт 10:00-20:00" Address="ул. Дуси Ковальчук, 179а, 3" FullAddress="Россия, Новосибирская обл., Новосибирск, ул. Дуси Ковальчук, 179а, 3" AddressComment="От метро по ул. Дуси Ковальчук в сторону Университета путей сообщения. Здание рядом с БЦ Колибри, вход с правой стороны." Phone="+79607857869" Email="e.arestova@cdek.ru" qqId="" Note="" coordX="82.916109" coordY="55.06141" Type="PVZ" ownerCode="cdek" IsDressingRoom="true" IsHandout="true" IsReception="true" HaveCashless="true" AllowedCod="true" NearestStation="Ст. м. Заельцовская, пл.Калинина"MetroStation="Ст. м. Заельцовская" Site="">
		<PhoneDetail number="+79607857869"/>
		<OfficeImage number="1" url="https://pvzimage.cdek.ru/images/1368/230_1_NSK33"/>
		<OfficeImage number="2" url="https://pvzimage.cdek.ru/images/1368/231_2_NSK33"/>
		<OfficeImage number="3" url="https://pvzimage.cdek.ru/images/1368/232_3_NSK33"/>
		<OfficeImage number="4" url="https://pvzimage.cdek.ru/images/1368/233_4_NSK33"/>
		<OfficeImage number="5" url="https://pvzimage.cdek.ru/images/1368/234_5_NSK33"/>
		<WorkTimeY day="1" periods="10:00/20:00"/>
		<WorkTimeY day="2" periods="10:00/20:00"/>
		<WorkTimeY day="3" periods="10:00/20:00"/>
		<WorkTimeY day="4" periods="10:00/20:00"/>
		<WorkTimeY day="5" periods="10:00/20:00"/>
		<WorkTimeY day="6" periods="10:00/16:00"/>
		<WorkTimeY day="7" periods="10:00/16:00"/>
		</Pvz>
</PvzList>

4.2. Регистрация заказа

Метод используется для регистрации заказов доставки товаров до клиентов.

Выделяется 2 типа заказов:

• “интернет-магазин” - может быть только у клиента с типом договора “Интернет-магазин”;
• “доставка” может быть создан любым клиентом с договором (доступны только тарифы для обычной доставки).

Форматы данных для типов заказа “интернет-магазин” и “доставка” описаны отдельно.

4.2.1. Описание передаваемых полей запроса

Регистрация заказа от интернет-магазина

Регистрация заказа на доставку

¹ Идентификация города отправителя и города получателя (в случае режима "до двери") производится по следующему алгоритму в порядке приоритетности:

• По уникальному коду города базы СДЭК (ID города). Коды городов базы СДЭК можно получить отправив пустой запрос по методу (Список городов). Значения передаются в атрибутах SendCityCode, RecCityCode.

• По почтовому индексу города. Значения передаются в атрибутах  SendCityPostCode, RecCityPostCode. В паре с почтовым индексом в качестве уточняющих параметров могут быть использованы код страны (атрибуты SendCountryCode, RecCountryCode) и/или наименование города (атрибуты SendCityName, RecCityName): код страны искомого города должен совпадать с указанным в соответствующем атрибуте, а переданное название города должно входить в название искомого. Наименование города можно указывать на языке клиента (поиск будет произведен по всем локализациям).

• По строке адреса, которая формируется путем конкатенации следующих полей: SendCityName/RecCityName + Address.Street + Address.House

Идентификация города получателя (в случае режима "до склада") производится по следующему алгоритму в порядке приоритетности:

• По уникальному коду города базы СДЭК (ID города). Коды городов базы СДЭК можно получить отправив пустой запрос по методу (Список городов). Значение передается в атрибуте RecCityCode.
• По переданному коду ПВЗ (атрибут PvzCode).
• По почтовому индексу города. Значение передается в атрибуте RecCityPostCode. В паре с почтовым индексом в качестве уточняющих параметров могут быть использованы код страны (атрибут RecCountryCode) и/или наименование города (атрибут RecCityName): код страны искомого города должен совпадать с указанным в соответствующем атрибуте, а переданное название города должно входить в название искомого. Наименование города можно указывать на языке клиента (поиск будет произведен по всем локализациям).
  

Чаще всего город отправления фиксируют кодом города, а для определения города  получателя используется почтовый индекс.

Нужно принимать во внимание, что база почтовых индексов в ИС СДЭК может содержат неполную и иногда не точную информацию по почтовым индексам, поэтому пользователь должен иметь возможность скорректировать параметр почтового индекса, если это необходимо.

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

³ В поле комментарий можно писать любые примечания по доставке груза, например если вы разрешаете частичную выдачу груза можно указывать “Частичная доставка разрешена», если запрещаете вскрытие посылки можно указывать «Запрет вскрытия».

⁴ Габариты упаковки необходимо указывать, если упаковка представляет собой коробку или если заказа "до постамата". С учетом габаритов  вычисляется объемный вес по формуле SizeА * SizeВ * SizeС/5000 и определяется подходящая ячейка постамата. Расчет стоимости доставки идет из максимального значения между фактическим и объемным весом.

⁵ В договоре с ИМ определяется условие, кто именно, ИМ или СДЭК, запрашивает у получателя расписание для доставки отправления. В случае, если ИМ самостоятельно запрашивает расписание, данные передаются в тэге <Schedule>. Расписание может быть передано позже, при необходимости (см. метод «Регистрация информации о результате прозвона» ).

На одну дату по одному заказу может быть только одно расписание. Расписание может иметь несколько дней доставки.

⁶ Вызов курьера для забора груза по указанному адресу является не обязательным параметром.

⁷ По тарифам с кодами 1, 10, 11, 12. 136, 137, 138, 139 действует правило: если вес по заказу превышает максимально возможный по выбранному тарифу, то тариф автоматически меняется на тариф "Экспресс" с соответствующим режимом.

⁸ Значение необходимо формировать согласно инструкции на сайте https://честныйзнак.рф

⁹ Количество уникальных позиций товаров не может быть более 126 шт.

^(*)    • Номер телефона отправителя (1.6.15.4) валидируется на соответствие формату телефонов в стране отправителя (телефонный код, количество символов).
Исключение: если телефон не соответствует формату страны отправителя, но соответствует формату телефонов России, Казахстана, Китая или Малазии, заказ будет зарегистрирован успешно.

     • Номер телефона получателя (1.6.18) валидируется на соответствие формату телефонов в стране получателя (телефонный код, количество символов).
Исключение: если телефон не соответствует формату страны отправителя, но соответствует формату телефонов России, Казахстана, Китая или Малазии, заказ будет зарегистрирован успешно.

     • Номер телефона продавца (1.6.23.4) валидируется на соответствие формату телефонов в стране получателя (телефонный код, количество символов), а также соответствие кода оператора пулу номеров активных телефонных операторов.

4.2.2. Формат ответа

Сервер СДЭК вернет результат в виде XML :

Пример 1. Регистрация заказа типа “интернет-магазин”

<?xml version="1.0" encoding="UTF-8"?>
<deliveryrequest account="716b2c7e8f2e1a46ff8fd126adaef97d"
    date="2017-05-05 11:20:45" number="soOEl" ordercount="1" secure="928324323f570dd1ee567e71f32a78e7">
    <callcourier>
        <call comment="comment_soOEl1"
            date="2017-05-06" lunchbeg="14:00"
            lunchend="14:30" sendcitycode="44" sendername="name_soOEl1"
            sendphone="+79138739944" timebeg="10:00" timeend="17:00" weight="20">
            <sendaddress flat="flat_soOEl1" house="house_soOEl1" street="street_soOEl1"/>
        </call>
    </callcourier>
    <order comment="comment-soOEl0" deliveryrecipientcost="0.0"
        deliveryrecipientvatrate="VATX" deliveryrecipientvatsum="0.0"
        number="number-soOEl0" phone="+79138739944" reccitycode="44"
        recipientemail="no-reply@cdek.ru" recipientname="name-soOEl0"
        sendcitycode="44" tarifftypecode="139">
        <address flat="flat-soOEl0" house="house-soOEl0" street="street-soOEl0"/>
        <sender company="company-soOEl0" name="Отправителев">
            <address flat="flat-soOEl0" house="house-soOEl0" street="street-soOEl0"/>
            <phone>+79999999999</phone>
            <phone>+79888888888</phone>
        </sender>
        <seller address="street_soOEl0 1" name="seller-soOEl0" INN="11111111111111111111" Phone="+79777777777" OwnershipForm="249"/>
        <package barcode="barcode-soOEl00" number="soOEl00" sizea="2.0"
            sizeb="3.0" sizec="4.0" weight="100.0">
            <item amount="2" comment="comment-soOEl000" cost="8.0"
                payment="10.0" paymentvatrate="VATX" paymentvatsum="0.0"
                warekey="warekey-soOEl000" weight="1.0"/>
        </package>
        <DeliveryRecipientCostAdv Threshold="2000" Sum="150" VATRate="vat10" VATSum="45.906"/>
		<AddService ServiceCode="30"/>
        <schedule>
            <attempt date="2017-05-05" id="soOEl00"
                timebeg="11:00:00" timeend="13:00:00">
                <address flat="flat-prozvon_adr"
                    house="house-prozvon_adr" street="street-prozvon_adr"/>
            </attempt>
        </schedule>
    </order>
</deliveryrequest>

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Call Number="5296808"/>
    <Call Msg="Добавлено заказов 1"/>
    <Order DispatchNumber="1039548075" Number="number-Eotvl0"/>
    <Order Msg="Добавлено заказов 1"/>
</response>

Пример 2. Регистрация заказа типа “доставка”

<?xml version="1.0" encoding="UTF-8"?>
<deliveryrequest account="716b2c7e8f2e1a46ff8fd126adaef97d" date="2017-03-15 10:17:07"
    number="test_request" ordercount="2" secure="4180a7f32c5f605db27f15e26eec03d7">
    <order comment="test_comment"
       number="number2017_6344227223" phone="+79888888888"
       reccitycode="44" recipientcompany="company-6344227223"
       recipientemail="email_1_G4Akh0@test.ru"
       recipientname="Получатель Получателев" sendcitycode="44" tarifftypecode="1">
       <address flat="flat-G4Akh0" house="house-G4Akh0" street="street-G4Akh0"/>
       <sender name="Отправ Отправителев">
           <address flat="flat-G4Akh0" house="house-G4Akh0" street="street-G4Akh0"/>
           <phone>+79138739876</phone>
           <phone>+79132873910</phone>
       </sender>
       <package barcode="test_package" comment="test_comment"
           sizea="10.0" sizeb="20.0" sizec="30.0" weight="1000.0"/>
    </order>
    <order comment="test_comment"
       number="number2017_6344227225" phone="+79788888888"
       reccitycode="44" recipientcompany="company-6344227225"
       recipientemail="email_1_G4Akh1@test.ru"
       recipientname="Получатель Получателев" sendcitycode="44" tarifftypecode="1">
       <address flat="flat-G4Akh1" house="house-G4Akh1" street="street-G4Akh1"/>
       <sender name="Отправ Отправителев">
           <address flat="flat-G4Akh1" house="house-G4Akh1" street="street-G4Akh1"/>
           <phone>+79133309944</phone>
           <phone>+79138092416</phone>
       </sender>
       <package barcode="test_package" comment="test_comment"
           sizea="10.0" sizeb="20.0" sizec="30.0" weight="1000.0"/>
    </order>
</deliveryrequest>

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Order DispatchNumber="1048179946" Number="number2017_6344227223"/>
    <Order DispatchNumber="1048179941" Number="number2017_6344227225"/>
    <Order Msg="Добавлено заказов 2"/>
</response>

4.3. Метод изменения заказов

Метод используется для изменения созданной накладной. Возможно изменять следующие данные в накладной:

• сумму наложенного платежа;
• данные получателя (имя получателя, телефон, адрес, пункт выдачи заказа);
• данные по международным заказам (если передан блок с паспортными данными получателя, то старые данные будут удалены и сохранены новые);
• дополнительные сборы за доставку;
• все данные мест и позиций товаров (т.е. старые данные будут удалены и сохранены новые).

Условием возможности изменения заказа является отсутствие движения груза на складе СДЭК (т.е. статус заказа «Создан»).

4.3.1. Описание передаваемых полей запроса

¹ Идентификация заказа осуществляется либо по «DispatchNumber», либо по «Number». 

^(*)   • Номер телефона получателя (1.6.7) валидируется на соответствие формату телефонов в стране получателя (телефонный код, количество символов).
Исключение: если телефон не соответствует формату страны отправителя, но соответствует формату телефонов России, Казахстана, Китая или Малазии, заказ будет зарегистрирован успешно.

4.3.2. Форма ответа

Сервер СДЭК вернет результат в виде XML :

Пример. Изменение заказа

<?xml version="1.0" encoding="UTF-8"?>
<updaterequest account="716b2c7e8f2e1a46ff8fd126adaef97d"
    date="2017-05-05 11:20:45" number="soOEl" ordercount="1" secure="928324323f570dd1ee567e71f32a78e7">
    <order deliveryrecipientcost="10.02" deliveryrecipientvatrate="VATX" deliveryrecipientvatsum="0.0" number="177875705">    
        <package barcode="barcode-soOEl00" number="soOEl00" sizea="2.0" sizeb="3.0" sizec="4.0" weight="100.0">
            <item amount="2" comment="comment-soOEl000" cost="8.0" payment="10.0" paymentvatrate="VATX" paymentvatsum="0.0" warekey="warekey-soOEl000" weight="1.0"/>
        </package>
    </order>
</updaterequest>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <Order DispatchNumber="1043190804" Number="177875705"/>
    <Order Msg="Изменено заказов: 1"/>
</response>

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

Метод предназначен для отмены (удаления) заказа по инициативе клиента. Условием возможности удаления заказа является отсутствие движения груза на складе СДЭК (статус заказа «Создан»).

4.4.1. Описание передаваемых полей запроса

¹ Идентификация заказа осуществляется либо по «DispatchNumber», либо по «Number». 

4.4.2. Формат ответа

Сервер СДЭК вернет результат в виде XML :

Пример. Удаление заказа

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<deleterequest number="123" ordercount="1" account="716b2c7e8f2e1a46ff8fd126adaef97d" date="2017-04-18 13:41:51" secure="ddb5b74a058c60bef584d797b1e4d167">
	<order number="number-8ZSO90"/>
</deleterequest>

<?xml version="1.0" encoding="UTF-8"?>
<response>
	<Order DispatchNumber="1104345018" Number="number-8ZSO90"/>
	<Order Msg="Удалено заказов 1"/>
</response>

4.5. Печать квитанции к заказу

Метод позволяет получить файл в формате pdf, содержащий печатные формы квитанций к заказу.

Во избежание перегрузки платформы нельзя передавать более 100 номеров заказов в одном запросе.

4.5.1. Описание передаваемых полей запроса

¹ Идентификация заказа осуществляется либо по «DispatchNumber», либо по двум параметрам «Number», «Date». Если в запросе есть значение атрибута «DispatchNumber», то атрибуты «Number», «Date» игнорируются.

4.5.2. Формат ответа

В ответ сервер СДЭК вернет pdf-файл.
В случае ошибки результат вернется в виде XML :

Пример. Печать квитанции к заказу

<?xml version="1.0" encoding="UTF-8" ?>
<OrdersPrint Date="2018-08-10" Account="716b2c7e8f2e1a46ff8fd126adaef97d" Secure="3ccc65b08c716393378a2e9c4ccbbf18" OrderCount="1" CopyCount="1">
    <Order DispatchNumber="1088986275" />
</OrdersPrint>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <Order ErrorCode="ERROR_ORDERS_NOT_FOUND" Msg="Отправления клиентов не найдены"/>
</response>

4.6. Регистрация заявки на вызов курьера

Данный метод позволяет осуществить вызов курьера для доставки груза.
Курьер может быть вызван в диапазоне с 9:00 до 22:00

4.6.1 Описание передаваемых данных

¹ Идентификация города отправителя производится по следующему алгоритму в порядке приоритетности:

    • По уникальному коду города базы СДЭК (ID города). Коды городов базы СДЭК можно найти в реестрах городов в пакете документации (Список городов). Значение передается в атрибуте SendCityCode.

    • Если код города не передан, то для его определения используются переданные в запросе значения атрибутов SendCityPostCode, SendCountryCode, SendCityName, и строка адреса, которая формируется путем конкатенации следующих полей: Address.Street + Address.House + Address.Flat

Нужно принимать во внимание, что база почтовых индексов в ИС СДЭК может содержат неполную и иногда не точную информацию по почтовым индексам, поэтому пользователь должен иметь возможность скорректировать параметр почтового индекса, если это необходимо.

² Если в запросе не передан DispatchNumber, то формируется заявка на вызов курьера для забора консоли (сразу нескольких заказов с одного адреса отправителя).

^(*) Номер телефона отправителя валидируется на соответствие формату телефонов в стране отправителя (телефонный код, количество символов). 

4.6.2. Формат ответа

Сервер СДЭК вернет результат в виде XML :

Пример. Регистрация заявки на вызов курьера

<?xml version="1.0" encoding="UTF-8"?>
<callcourier account="716b2c7e8f2e1a46ff8fd126adaef97d" callcount="1"
    date="2017-03-13" secure="7ba5875c5c14cd1a344b83fdd8df74b3">
    <call comment="comment_QF6aD1" date="2017-03-14"
       dispatchnumber="1039547805" lunchbeg="14:00" lunchend="14:30"
       sendcitycode="44" sendername="name_QF6aD1"
       sendphone="+79138739944" timebeg="10:00" timeend="17:00" weight="20">
       <address flat="flat_QF6aD1" house="house_QF6aD1" street="street_QF6aD1"/>
    </call>
</callcourier>

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Call Number="5296692"/>
    <Call Msg="Добавлено заявок 1"/>
</response>

4.7. Регистрация информации о результате прозвона

Метод предназначен для передачи от клиента информации, содержащий данные по прозвону получателя заказа типа “интернет-магазин” о договоренности доставки до двери (при создании прозвона до ПВЗ дата не учитывается)

Метод используется в следующих случаях:

• ИМ самостоятельно предоставляет в СДЭК расписание получателя для доставки/забора;
• изменения в заказе адреса доставки;
• изменения суммы по оплате за товар.
  
  

4.7.1. Описание входных параметров