Общее описание
В документе представлен порядок и формат обмена данными между Компанией «СДЭК» и клиентом Интернет-Магазином (далее ИМ).
Ответы на часто-задаваемый вопросы можно увидеть тут: http://www.cdek.ru/faq/
Запросы на генерацию учетной записи, вопросы и пожелания клиентов принимаем на email [email protected].
-
Протокол обмена
2.1. Обмен данными осуществляется по протоколу HTTP.
Адрес сервера СДЭК для отправки запросов:
http://gw.edostavka.ru:11443
Резервный сервер для запросов: http://lk.cdek.ru:11443, можно использовать при не доступности основного.
Данные передаются в формате XML, при этом необходимо учитывать, что в значениях полей нельзя использовать символы разметки XML ( < > & " ' ), кодировка UTF-8.
2.2. Идентификация ИМ осуществляется двумя параметрами: учетная запись account и секретный код secure_password.
Для обеспечения безопасности при передаче/запросе данных ИМ должен передавать значение поля secure, вычисляемое по алгоритму:
secure = md5(date.'&'.secure_password), где
secure_password — секретный код, предоставляемый СДЭКом,
date — дата документа (для всех запросов - значение параметра Date xml-запроса, кроме запроса «Статусы заказов» в формате get-запроса, где используется значение параметра DateFirst).
Во всех модулях дата_время передается в формате UTC( 0000-00-00T00:00:00 ), если иное не указано в описании.
Важно: Учетная запись для интеграции не совпадает с учетной записью доступа в Личный Кабинет.
Важно: формат и значение параметра «Date» («DateFirst») должно быть одно и тоже как в запросе, так и при хешировании поля secure, иначе в ответ вы получите сообщение, что ИМ не идентифицирован. Т.е. если параметр Date в запросе указано в формате UTC(0000-00-00T00:00:00), то и при хешировании должно быть то же самое значение. Если время не важно, то можно использовать только дату при формировании параметра Date в запросе. Во всех ответных данных используется полный формате UTC(0000-00-00T00:00:00).
Учетная запись и секретный код назначаются СДЭК-ом по запросу ИМ на email [email protected].
2.3. На этапе тестирования интернет-магазину назначается тестовая учетная запись. При тестировании заказы клиента не отображаются в личном кабинете клиента на сайте www.cdek.ru. По завершению отладки ИМ сообщает о готовности переключиться на реальную учетную запись, при этом у клиента обязательно должен быть договор со СДЭК.
2.4. ИМ имеет возможность получать уведомления о результате отправки данных на электронную почту. Уведомления содержат информацию как об удачной загрузке заказов, так и об ошибках передачи данных. Список e-mail адресов передается СДЭКу вместе с запросом на учетную запись.
2.5. Для формирования списка заказов на доставку необходим список городов с идентификационными номерами по базе СДЭК. Список предоставляется СДЭКом вместе с регламентом обмена данными.
2.6. СДЭК принимает пять типов документов на обработку: «Список заказов на доставку», «Прозвон получателя», «Вызов курьера», «Список заказов на удаление», «Печатная форма квитанции к заказу».
«Список заказов на доставку» - документ, содержащий данные по заказам в акте приема-передачи/ТТН (товарно-транспортная накладная). На основании данных заказов в базе СДЭК создаются накладные, номера которых можно получить с помощью отчета «Статусы заказов».
«Прозвон получателя» - документ, содержащий данные по прозвону получателя о договоренности доставки до двери или забора со склада, в зависимости от режима доставки.
Документ используется в следующих случаях:
-
ИМ самостоятельно предоставляет СДЭК расписание получателя для доставки/забора;
-
изменении в заказе реквизитов получателя ( контактное лицо, адрес доставки, телефон);
-
изменении суммы по оплате за товар, доставку.
Данные передаются уже по существующим в базе СДЭК заказам. Также в документе «Список заказов на доставку» возможна передача данных «Прозвон получателя» по новым заказам. Расписание доставки может быть передано только на один день.
Если попытка доставки по расписанию была неудачной, ИМ снова отправляет расписание доставки. Отчет о неудачных попытках доставки предоставляется ИМ в документе «Статусы заказов» (Причины задержки).
«Вызов курьера» - документ, содержащий информацию по вызову курьера, если необходимо забрать груз со склада ИМ. Груз доставляется до склада СДЭК. Условия формирования документа:
-
на один день возможно не более одного вызова курьера на один адрес;
-
диапазон времени для приезда курьера не должен быть меньше 3 часов.
Предварительно осуществляется прозвон интернет-магазина по указанному контактному телефону для подтверждения вызова курьера, уточнения информации.
«Список заказов на удаление» - документ, содержащий перечень заказов, которые необходимо удалить из базы СДЭК в случае их ошибочного импорта. Условием возможности удаления заказа является отсутствие движения груза на складе СДЭК (статус заказа «Создан»).
«Печатная форма квитанции к заказу» - документ, содержащий перечень заказов, по которым необходимо сформировать файл в формате pdf, содержащий печатные формы квитанций к заказу. Формат квитанции приложен к данному документу.
ИМ отправляет POST запрос на адрес:
-
для документа «Список заказов на доставку» http://gw.edostavka.ru:11443/new_orders.php;
-
для документа «Прозвон получателя» http://gw.edostavka.ru:11443/new_schedule.php;
-
для документа «Вызов курьера» http://gw.edostavka.ru:11443/call_courier.php;
-
для документа «Список заказов на удаление» http://gw.edostavka.ru:11443/delete_orders.php.
-
для документа «Печатная форма квитанции к заказу» http://gw.edostavka.ru:11443/orders_print.php.
с заполненной переменной $_POST['xml_request'], в которой передается содержимое XML фaйла.
Сервер СДЭК вернет результат в виде:
-
при удачной обработке данных header("http/1.0 200 Ok");
и XML в виде:
-
при ошибке: header("http/1.0 200 server error")
и XML в виде:
Код состояния HTTP не говорит о результате загрузки, необходимо обрабатывать возвращаемый XML.
Примечание: формат удачной обработки приведен схематически и соответствует ответу на запрос по документу «Список заказов на доставку», формат ошибки приведен схематически и соответствует всем некорректным обращениям.
Если при создании учетной записи были указаны электронные адреса для отправки уведомлений, то по результату выполнения запроса, так же будет отправлено письмо c результатом обработки документов с электронного адреса: [email protected].
Важно:
-
При возникновении ошибки на любом этапе обработки документа, изменения аннулируются, документ может быть принят только полностью. Исключение составляет документ «Список заказов на доставку»: заказы, не имеющие ошибок, импортируются, по остальным - передается информация в формате XML или на email (при передаче СДЭКу email-адреса для уведомлений).
-
Изменения в базе СДЭК происходят сразу после удачной обработки запроса. То есть другие необходимые запросы по загруженным заказам можно осуществлять сразу, после получения положительного ответа.
-
Ограничений на количество запросов в сутки нет.
-
При работе тестового аккаунта изменения, переданные в тестовом режиме, будут аннулированы автоматически в 23.00 по NSK. Поэтому проверку тестовых данных необходимо проверять в те же сутки.
-
При работе боевого аккаунта накладные в статусе «Создан», по которым нет изменений в течении 30 дней с момента формирования заказа, удаляются автоматически по истечении этого срока. Поэтому отправку запроса на создание заказов на доставку необходимо осуществлять перед реальной отправкой товара.
2.7. По запросу ИМ формируется три вида документов: «Список пунктов выдачи заказов (ПВЗ)», «Статусы заказов», «Информация по заказам».
Документ «Список пунктов выдачи заказов (ПВЗ) предоставляет список ПВЗ, действующих на момент запроса.
ИМ отправляет GET запрос на
http://gw.edostavka.ru:11443/pvzlist.php, с заполненными переменными $_GET['cityid'], $_GET['citypostcode' ], где cityid – код города по базе СДЭК(см. файл «City_XXX_YYYYMMDD.xls», где XXX – трехбуквенный код страны, YYYYMMDD – дата формирования файла), citypostcode — почтовый индекс города, для которого необходим список ПВЗ, оба параметра необязательны, если указаны оба приоритет отдается cityid. При отсутствии обоих параметров список ПВЗ содержит данные по всем городам. Атрибут ПВЗ используется в документе «Список заказов на доставку» для заказов с режим доставки «до склада».
Примеры запросов:
Для примеров используем Cityid=44 — код города Москва, Сitypostcode=656065 — почтовый индекс города Барнаул.
http://gw.edostavka.ru:11443/pvzlist.php — в результате получим список всех активных ПВЗ на дату формирования запроса.
http://gw.edostavka.ru:11443/pvzlist.php?cityid=44 — в результате получим список всех активных ПВЗ в г. Москва на дату формирования запроса.
http://gw.edostavka.ru:11443/pvzlist.php?citypostcode=656065 — в результате получим список всех активных ПВЗ в г. Барнаул на дату формирования запроса.
http://gw.edostavka.ru:11443/pvzlist.php?cityid=44&citypostcode=656065 — в результате получим список всех активных ПВЗ в г. Москва на дату формирования запроса.
Отчет «Статусы заказов» предоставляет
-
последний статус заказа в указанном периоде;
-
полную историю статусов заказа (при передаче атрибута ShowHistory);
-
данные о вручении посылки (когда, кому);
-
неудавшиеся попытки доставки в разрезе расписания доставки, предоставленного Интернет-магазином.
Запрос можно формировать как за период, в который интересует изменения статусов, так и по конкретному списку посылок.
ИМ отправляет POST запрос на http://gw.edostavka.ru:11443/status_report_h.php с заполненной переменной $_POST['xml_request'], в которой передается содержимое XML фaйла (описание см. ниже). В результате также возвращается XML (описание см. ниже).
Либо отправляет GET запрос с заполненными переменными $_GET['account'], $_GET['secure'], $_GET['datefirst'], $_GET['datelast'], $_GET['showhistory']. Пример запроса:
http://gw.edostavka.ru:11443/status_report_h.php?account=abcd1234567890efgh&secure=abcd1234567890efghxwz&datefirst=2010-10-1T00:00:00&showhistory=1
, где datefirst – дата начала запрашиваемого периода изменения статусов, datelast – дата окончания. datelast – необязательный параметр, в случае его отсутствия используется текущая дата_время осуществления запроса. Для формирования secure используется параметр datefirst.
Запрос статусов можно делать так часто, как этого требуется ИМ.
Отчет «Информация по заказам» предоставляет данные:
-
по ключевым параметрам заказа, формирующим стоимость услуг СДЭК;
-
о дате последнего изменения суммы заказа.
ИМ отправляет POST запрос на http://gw.edostavka.ru:11443/info_report.php с заполненной переменной $_POST['xml_request'], в которой передается содержимое XML фaйла (описание см. ниже). В результате также возвращается XML (описание см. ниже)
2.8. Все запросы/вопросы необходимо присылать на e-mail [email protected] с темой письма «Интеграция СДЭК, клиент Название_Вашей_Компании, Номер_Договора_если_есть».
Алгоритм работы ИМ с интеграцией СДЭК:
-
ИМ отгружает заказы, готовые на доставку: документ «Список заказов на доставку»;
-
Если по условиям договора, ИМ самостоятельно прозванивает получателя, необходимо передать СДЭК информацию о договоренности доставки/забора: «Прозвон получателя». Данные необходимо передавать по факту наличия груза в городе получателя. Эта информация доступна с помощью отчета «Статусы заказов»;
-
Если необходимо вызвать курьера для забора груза на склад СДЭК, необходимо отправить документ «Вызов курьера»;
-
При необходимости отменить заказ, по которому еще не была осуществлена работа (статус заказа «Создан»), нужно отправить запрос на удаление: документ «Список заказов на удаление»;
-
Статусы заказа в периоде, история изменений статусов, проблемы доставки могут быть получены в отчете «Статусы заказов».
-
|