Формат обмена данными
«Твой Курьер» - Интернет-Магазин
Спецификация требований
Версия 1.2
Содержание
1. Общее описание...................................................................................................................... 3
2. Протокол обмена..................................................................................................................... 3
3. Список пунктов выдачи заказов (ПВЗ)...................................................................................... 6
4. Список заказов на доставку..................................................................................................... 7
5. Список заказов на самовывоз................................................................................................ 12
6. Список заказов на отправку Почтой России........................................................................... 15
7. Список заказов на доставку через постаматы........................................................................ 18
8. Список заказов на удаление................................................................................................... 21
9. Отчет «Статусы заказов»........................................................................................................ 22
10. Отчет «Запрос статуса заказа от ИМ к ТК»........................................................................... 24
11. Запрос от ИМ в ТК данных о дисконтной карте ТК................................................................ 25
12. Запрос от ИМ к ТК о стоимости доставки или самовывоза (калькулятор)............................ 26
13. Список постаматов............................................................................................................... 28
14. Коды ошибок........................................................................................................................ 29
15. Приложение.......................................................................................................................... 32
1. Общее описание
В документе представлен порядок и формат обмена данными между Компанией «Твой Курьер» и клиентом Интернет-Магазином (далее ИМ).
2. Протокол обмена
1. Обмен данными осуществляется по протоколу HTTP.
Кодировка всех запросов CP1251.
Адрес сервера Твой Курьер для отправки запросов:
http://*****/ishop/xml/
Данные передаются в формате XML, кодировка CP1251.
2. Идентификация ИМ осуществляется параметром учетной записи account и секретным кодом secure.
Для обеспечения безопасности при передаче/запросе данных ИМ должен передавать значение поля secure, вычисляемое по алгоритму:
secure = md5(date.'&'.secure_password), где
secure_password — секретный код, передаваемый компанией Твой Курьер (его можно видеть в личном кабинете на сайте компании «Твой Курьер»),
date — дата документа.
Дата передается в формате “d. m.Y”, например: 01.01.2014
Учетная запись и секретный код назначаются автоматически при создании личного кабинета. Учетная запись и секретный код не меняются, поэтому, во избежание возможных проблем, не сообщайте его посторонним лицам. Программисту, который занимается интеграцией можно сообщить тестовый код, а затем самостоятельно его сменить на актуальный.
3. На этапе тестирования интернет-магазину назначается тестовая учетная запись. По завершению отладки ИМ сообщает о готовности переключиться на реальную учетную запись.
4. ИМ имеет возможность получать уведомления о результате отправки данных на электронную почту. Уведомления содержат информацию как об удачной загрузке заказов, так и об ошибках импорта. Список e-mail адресов Вы можете указать в личном кабинете в разделе «Прочее» >>> «Настройки». Если нужно указать несколько ящиков, указывайте их через запятую.
5. Для формирования списка заказов на доставку необходим список городов с идентификационными номерами по базе Твой Курьер. Список предоставляется вместе с регламентом обмена данными в виде xml по адресу http://*****/ishop/xml/city_list. php
6. Твой Курьер принимает семь типов документов на обработку: «Список заказов на доставку», «Список заказов на самовывоз», «Заявка на забор товара с Вашего склада», «Заявка на привоз товара на наш склад», «Список заказов на отправку Почтой России», «Список заказов на отправку через постаматы», «Список заказов на удаление». Из них, на сегодняшний день, работают только те интерфейсы, которые подчеркнуты.
«Список заказов на доставку» - документ, содержащий данные по заказам, которые Заказчик поручает Исполнителю доставить.
«Список заказов на самовывоз» - документ, содержащий данные по заказам на самовывоз, которые Заказчик поручает Исполнителю выдать покупателю в пунктах выдачи Исполнителя. Список пунктов самовывоза в виде xml можно получить по адресу: http://*****/ishop/xml/pvzlist. php (информация об этом будет далее).
«Заявка на забор с Вашего склада» - документ, содержащий информацию по вызову курьера, если необходимо забрать товары со склада ИМ. Груз доставляется до склада Твой Курьер. Условия формирования документа:
ñ на один день возможно не более одного вызова курьера в одном городе;
ñ диапазон времени для приезда курьера не должен быть меньше 3 часов;
ñ Список товаров (или заказов) не может быть пустым.
«Заявка на привоз товара на наш склад» - документ, содержащий информацию о времени приезда Вашего представителя на склад Твой Курьер, а так же списке товаров или заказов, которые он привезет. Список товаров или заказов не может быть пустым.
«Список заказов на отправку Почтой России» - документ, содержащий информацию по заказам, которые Заказчик поручает Исполнителю доставить на Почту России.
«Список заказов на отправку через постаматы» - документ, содержащий информацию по заказам, которые Заказчик поручает Исполнителю доставить до постаматов.
«Список заказов на удаление» - документ, содержащий перечень заказов, которые необходимо удалить из базы Твой Курьер в случае их ошибочного импорта. Условием возможности удаления заказа является отсутствие какой-либо выполненной работы по данному заказу (статус заказа «В обработке»).
ИМ отправляет POST запрос на адрес:
ñ для документа «Список заказов на доставку»: http://*****/ishop/xml/im_integrator_neworder. php;
ñ для документа «Список заказов на самовывоз»: http://*****/ishop/xml/im_integrator_newcarry. php;
ñ для документа «Заявка на забор товара с Вашего склада»:
http://*****/ishop/xml/im_integrator_newexport. php;
ñ для документа «Заявка на привоз товара на наш склад»:
http://*****/ishop/xml/im_integrator_newselfexport. php;
ñ для документа «Список заказов на отправку Почтой России»:
http://*****/ishop/xml/im_integrator_newrp. php;
ñ для документа «Список заказов на отправку через постаматы»:
http://*****/ishop/xml/im_integrator_newpostamat. php;
ñ для документа «Список заказов на удаление»:
http://*****/ishop/xml/delete_orders. php.
с заполненной переменной $_POST['xml_request'], в которой передается содержимое XML фaйла.
Сервер Твой Курьер вернет результат в виде:
· при удачной обработке данных header("http/Ok");
и XML в виде:
<?xml version="1.0" encoding="CP1251"?>
<response><Order Msg="Добавлено заказов CntOrder"/><response/>
· при ошибке: header("http/server error")
и XML в виде:
<?xml version="1.0" encoding="CP1251"?>
<response><Order Msg="Error: описание ошибки"/><response/>
Код состояния HTTP не говорит о результате загрузки, необходимо обрабатывать возвращаемый XML.
Если были указаны электронные адреса для отправки уведомлений, будет отправлено письмо c результатом обработки документов с электронного адреса: *****@***ru. Не забудьте добавить этот адрес в белый список адресов, чтобы письма с этого адреса не уходили в СПАМ.
Важно:
ñ При возникновении ошибки на любом этапе обработки документа, заказы, не имеющие ошибок, импортируются, по остальным - передается информация в формате XML и на email (в случае, если он указан в Вашем личном кабинете).
ñ Изменения в базе Твой Курьер происходят сразу после удачной обработки запроса.
ñ Ограничений на количество запросов в сутки нет.
ñ При работе тестового аккаунта изменения, переданные в тестовом режиме, будут аннулированы автоматически в 23.00 по московскому времени.
7. По запросу ИМ формируется шесть видов документов: «Список пунктов выдачи заказов (ПВЗ)», «Статусы заказов», «Информация по заказам», «Список городов и их номеров в базе», «Список регионов и их номеров в базе», «Список стран и их номеров в базе».
Документ «Список пунктов выдачи заказов (ПВЗ)» предоставляет список ПВЗ, действующих на момент запроса.
ИМ отправляет запрос на
http://*****/ishop/xml/pvzlist. php? cityid=994,
переменная cityid – код города для которого необходим список ПВЗ, необязательный параметр. При отсутствии параметра cityid список ПВЗ содержит данные по всем городам. Атрибут ПВЗ используется в документе «Список заказов на самовывоз».
Отчет «Статусы заказов» передает информацию последнего статуса заказа, по которому были изменения от даты_времени datefirst включительно по текущий момент или даты_времени datelast.
Всю историю изменений статусов заказов, выбранных по вышеописанным условиям, можно получить при значении переменной showhistory = 1.
В отчете также предоставляются данные по неудавшимся попыткам доставки в разрезе расписания доставки, предоставленного Интернет-Магазином.
ИМ отправляет запрос на
http://*****/status_report_h. php? account=123&secure=c3b51896d86675dc3205a8d7ef833a15&datefirst=&showhistory=1
Сервер Твой Курьер вернет XML фaйл в виде «Отчет «Статусы заказов».
Запрос статусов можно делать не чаще одного раза в одну минуту. Рекомендуем выставлять интервал один раз в 5 или 10 минут.
Отчет «Информация по заказам» предоставляет данные:
· по ключевым параметрам заказа, формирующим стоимость услуг Твой Курьер;
· о дате последнего изменения суммы заказа.
ИМ отправляет запрос на http://*****/ishop/xml/info_report. php с заполненной переменной $_POST['xml_request'], в которой передается содержимое XML фaйла (описание см. ниже). В результате также возвращается XML (описание см. ниже)
Список «Список городов и их номеров в базе» выдает все города с индексами, в формате XML, содержавшиеся в базе Твой Курьер.
ИМ отправляет запрос на http://*****/ishop/xml/city_list. php
Дополнительный параметр id_country (метод GET), который содержит ID страны, по которому нужно вывести города. Если параметр пуст, то выводятся все города по России.
Дополнительный параметр id_region (метод GET), по которому можно вывести все города и населенные пункты в конкретном регионе любой страны.
Список «Список регионов и их номеров в базе» выдает все регионы с индексами, в формате XML, содержавшиеся в базе Твой Курьер.
ИМ отправляет запрос на http://*****/ishop/xml/region_list. php
Дополнительный параметр id_country, который содержит ID страны, по которому нужно вывести регионы. Если параметр пуст, то выводятся все регионы по России.
Список «Список стран и их номеров в базе» выдает все города с индексами, в формате XML, содержавшиеся в базе Твой Курьер.
ИМ отправляет запрос на http://*****/ishop/xml/country_list. php
Метод GET. Обязательные параметры: account, secure.
Отчет «Запрос статуса заказа от ИМ к ТК» (п. 10):
ИМ отправляет запрос на http://*****/ishop/xml/get_order_status. php с параметрами account и secure и заполненными параметрами id или num_order (ID заказа по базе Твой Курьер или номер заказа по базе Твой Курьер соответственно).
Запрос «Запрос от ИМ в ТК о стоимости доставки или самовывоза (калькулятор)»
ИМ отправляет запрос на http://*****/ishop/xml/im_calc. php с параметрами account и secure, а так же дополнительными параметрами, описанными в п. 12. Всё передаётся методом GET.
Все запросы/вопросы необходимо присылать на e-mail *****@***ru с темой письма «Интеграция Твой Курьер, клиент Название_Вашей_Компании, Номер_Договора,_если_есть».
3. Список пунктов выдачи заказов (ПВЗ)
№ | Тэг/Атрибут | Описание | Тип поля | Обяз. для заполн. |
1. | PvzList | Заголовок документа | да | |
2. | Pvz | ПВЗ | да | |
2.1. | Code | ID пункта выдачи | number | да |
2.2. | Name | Название | varchar(50) | да |
2.3. | CountryCode | Код страны по базе Твой Курьер | number | да |
2.4. | CityCode | Код города по базе Твой Курьер | number | да |
2.5. | City | Название города | varchar(50) | да |
2.6. | WorkTime | Режим работы | varchar(100) | да |
2.7. | Address | Адрес | varchar(255) | да |
2.8. | Phone | Телефон | varchar(100) | да |
2.9. | GPSlong | GPS координата ПВЗ | float | да |
2.10. | GPSlat | GPS координата ПВЗ | float | да |
2.10. | Term | Сроки доставки в ПВЗ | text | да |
2.12. | Desc | Описание, как пройти до пункта выдачи | text | Нет |
2.13 | Type | Тип ПВЗ. Буква английского алфавита | varchar(1) | да |
Пример:
Документ содержит список ПВЗ в городе Москва.
<?xml version="1.0" encoding="UTF-8" ?>
<pvzList>
<pvz code="231" name="Волгоградка" countrycode="1" citycode="994" city="Москва" worktime="пн.-пт. 10-19, сб. 10-17, вс 11-18" address="Волгоградский проспект, д. 32, корп. 13" phone="(4, (4" gpslong="51.35478" gpslat="34.78945" term="пн-пт с 11 до 23” desc="Пройти от метро Волгоградский проспект 100 метров" type="A"/></pvz>
</pvzList>
4. Список заказов на доставку
№ | Тэг/Атрибут | Описание | Тип поля | Обяз. для заполн. |
1. | Orders | Заголовок документа | да | |
1.1. | Type | Тип заказов, передаваемых в документе | varchar(255) | да |
1.2. | Number | Номер акта приема-передачи/ТТН. Если товар не находится на складе Твой Курьер и его необходимо передать, то позже Вы будете создавать заказ на забор товара или заказ на привоз товара, в котором Ваш внутренний номер должен совпадать с данным номером. | varchar(20) | Да |
1.3. | Date | Дата документа | date | да |
1.4. | OrderCount | Общее количество заказов в документе | number | да |
2. | Order | Заказ | да | |
2.1. | Number | Номер отправления клиента или внутренний номер заказа (должен быть уникален в пределах акта приема-передачи). Он не может содержать русские буквы и пробелы, знаки + / \ ? & | varchar(20) | да |
2.2. | Places | Количество мест (коробок, упаковок), передаваемых вместе с этим заказом | number | да |
2.3. | Sendercity | Код города отправителя из базы Твой Курьер | number | да |
2.4. | Recipcity | Код города получателя из базы Твой Курьер | number | да |
2.5. | D_date | Дата, на которую идет доставка. Если отправление идет в регион или другую страну и Вы не знаете сроки доставки, то пишите день, когда товар будет на складе. Пример значения: 27.01.2013 | d. m.Y | да |
2.6. | B_time | РЕКОМЕНДУЕМОЕ время доставки товара ( с ). Значения могут быть только от 10 до 18 включительно | number | да |
2.7. | E_time | РЕКОМЕНДУЕМОЕ время доставки товара ( по ). Значения могут быть только от 13 до 22 включительно. Имейте ввиду, что на данный момент доставка осуществляется до 19 часов. Временной промежуток должен быть не менее 3 часов, то есть с 10 до 13 или с 11 до 20, но не с 10 до 11 или с 18 до 19 | number | да |
2.8. | Dim_x | Габариты груза. Длина (в сантиметрах)* | number | нет |
2.9. | Dim_y | Габариты груза. Ширина (в сантиметрах)* | number | нет |
2.10. | Dim_z | Габариты груза. Высота (в сантиметрах)* | number | Нет |
2.11. | TK_card_num | Номер дисконтной карты ТК, по которой покупатель получил скидку. ВНИМАНИЕ!!! Данное поле либо остается пустым, либо в него пишется только номер дисконтной карты ТК (карта, организатором которой является компания Твой Курьер). Просим не писать в это поле номер любой Вашей дисконтной карты. | varchar(100) | Нет |
2.12. | Comments | Комментарий по заказу | text | нет |
2.13. | Incl_delivery | Включить в бланк цену доставки | да | |
2.13.1. | Val | Значение 1 или 0 – включить или не включать | number | да |
2.13.2. | Price | Стоимость доставки для клиента в рублях | double | да |
3. | Goods | Товары. Минимум один товар в заказе должен присутствовать | да | |
3.1. | Number | Порядок сортировки товаров для отображения в сопроводительных документах | number | да |
3.2. | Barcode | Штрих-код упаковки | varchar(100) | да |
3.3. | Name | Наименование вложения | text | да |
3.4. | Weight | Вес в кг (за единицу) | double | да |
3.5. | Quantity | Количество единиц | number | да |
3.6. | Сost | Стоимость товара, закупочная цена (за единицу) | double | да |
3.7. | Price | Стоимость товара для покупателя (за единицу) | double | да |
3.8. | Bundling | Комплектация данной единицы товара. Значение 1 или 0 – комплектовать или не комплектовать | number | да |
4. | Service | Дополнительные услуги | да | |
4.1. | Cash | Услуга «наложенный платеж». Включается всегда (значение 1), когда требуется забрать денежные средства от покупателя. Если услуга выключена (значение 0), то денежные средства с покупателя браться не будут. Рекомендуем включать услугу автоматически, если стоимость товара по данному заказу более 0 рублей. | number | да |
4.2. | Cheque | Услуга «кассовое обслуживание». В системе управления магазином рекомендуем эту настройку вывести в раздел Настройки в виде галочки. Помните, что товары без чеков не доставляются. Не включать эту услугу Вы можете только тогда, когда сами выбиваете кассовые чеки для покупателей и прикладываете их к товару. Услуга может быть включена только если у Вас подписан агентский договор. Значения 0 или 1. | number | да |
4.3. | Dcall | Услуга «доп. прозвон получателя». Значения 0 или 1. | number | нет |
4.4. | Sms | Услуга «SMS уведомление» о результатах выполнения заказа, то есть о конечном статусе заказа. Значение 0 или 1 | number | нет |
4.5. | Sms_phone | Номер телефона для услуги 4.4., строго в формате 7ХХХХХХХХХХ, где Х – цифры от 0 до 9. Если услуга 4.4. включена, то данное поле обязательно для заполнения. | varchar(11) | нет |
4.6. | Express | Услуга «экспресс доставка» (доставка день в день). Данная услуга будет введена в начале осени 2013 года. Значение 0 или 1. | number | нет |
4.7. | Pack | Услуга упаковки. Значение 0 или 1. | number | нет |
5. | Contacts | Контактные данные покупателя | да | |
5.1. | Name | Получатель (ФИО) | varchar(255) | да |
5.2. | Compname | Название компании получателя | varchar(255) | нет |
5.2. | Country | Код страны получателя из базы Твой Курьер | number | да |
5.3. | City | Код города получателя из базы Твой Курьер | number | да |
5.4. | Ul | Улица получателя. | varchar(200) | да |
5.5. | Home | Дом получателя | varchar(100) | нет |
5.6. | Corp | Корпус получателя | varchar(100) | нет |
5.7. | Flat | Квартира или офис получателя. Если квартира, то очень рекомендуем до цифры подставлять кв. | varchar(100) | нет |
5.8. | Flour | Этаж получателя | varchar(100) | нет |
5.9. | Kod | Код домофона получателя | varchar(100) | нет |
5.10. | Phones | Телефоны получателя. Если несколько, то через запятую. | text | да |
* Габариты упаковки необходимо указывать, если упаковка представляет собой коробку. С учетом габаритов вычисляется объемный вес по формуле А * В * С/5000, где A, B, C – длина, ширина, высота упаковки. Расчет стоимости доставки идет из максимального значения между фактическим и объемным весом. Рекомендуем в системах управления ИМ сделать доп. поля к каждому товару с длиной, шириной и высотой и заполнять их по необходимости.
|
Из за большого объема этот материал размещен на нескольких страницах:
1 2 3 4 5 6 7 |
