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

Формат обмена данными
«Твой Курьер» - Интернет-Магазин
Спецификация требований
Версия 1.2
«Твой Курьер»
cтр. 1 из 33
Содержание
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
«Твой Курьер»
cтр. 2 из 33
1. Общее описание
В документе представлен порядок и формат обмена данными между Компанией «Твой Курьер» и клиентом
Интернет-Магазином (далее ИМ).
2. Протокол обмена
1.
Обмен данными осуществляется по протоколу HTTP.
Кодировка всех запросов CP1251.
Адрес сервера Твой Курьер для отправки запросов:
http://tvoykurier.ru/ishop/xml/
Данные передаются в формате XML, кодировка CP1251.
2.
secure.
Идентификация ИМ осуществляется параметром учетной записи account и секретным кодом
Для обеспечения безопасности при передаче/запросе данных ИМ должен передавать значение поля secure,
вычисляемое по алгоритму:
secure = md5(date.'&'.secure_password), где
secure_password — секретный код, передаваемый компанией Твой Курьер (его можно видеть в личном
кабинете на сайте компании «Твой Курьер»),
date — дата документа.
Дата передается в формате “d.m.Y”, например: 01.01.2014
Учетная запись и секретный код назначаются автоматически при создании личного кабинета. Учетная
запись и секретный код не меняются, поэтому, во избежание возможных проблем, не сообщайте его
посторонним лицам. Программисту, который занимается интеграцией можно сообщить тестовый код, а
затем самостоятельно его сменить на актуальный.
3.
На этапе тестирования интернет-магазину назначается тестовая учетная запись. По завершению
отладки ИМ сообщает о готовности переключиться на реальную учетную запись.
4.
ИМ имеет возможность получать уведомления о результате отправки данных на электронную
почту. Уведомления содержат информацию как об удачной загрузке заказов, так и об ошибках импорта.
Список e-mail адресов Вы можете указать в личном кабинете в разделе «Прочее» >>> «Настройки». Если
нужно указать несколько ящиков, указывайте их через запятую.
5.
Для формирования списка заказов на доставку необходим список городов с идентификационными
номерами по базе Твой Курьер. Список предоставляется вместе с регламентом обмена данными в виде xml
по адресу http://tvoykurier.ru/ishop/xml/city_list.php
6.
Твой Курьер принимает семь типов документов на обработку: «Список заказов на доставку»,
«Список заказов на самовывоз», «Заявка на забор товара с Вашего склада», «Заявка на привоз
товара на наш склад», «Список заказов на отправку Почтой России», «Список заказов на отправку
через постаматы», «Список заказов на удаление». Из них, на сегодняшний день, работают только те
интерфейсы, которые подчеркнуты.
«Список заказов на доставку» - документ, содержащий данные по заказам, которые Заказчик поручает
Исполнителю доставить.
«Список заказов на самовывоз» - документ, содержащий данные по заказам на самовывоз, которые
Заказчик поручает Исполнителю выдать покупателю в пунктах выдачи Исполнителя. Список пунктов
самовывоза в виде xml можно получить по адресу: http://tvoykurier.ru/ishop/xml/pvzlist.php (информация об
этом будет далее).
«Заявка на забор с Вашего склада» - документ, содержащий информацию по вызову курьера, если
необходимо забрать товары со склада ИМ. Груз доставляется до склада Твой Курьер. Условия
формирования документа:

на один день возможно не более одного вызова курьера в одном городе;

диапазон времени для приезда курьера не должен быть меньше 3 часов;
«Твой Курьер»
cтр. 3 из 33
Список товаров (или заказов) не может быть пустым.

«Заявка на привоз товара на наш склад» - документ, содержащий информацию о времени приезда
Вашего представителя на склад Твой Курьер, а так же списке товаров или заказов, которые он привезет.
Список товаров или заказов не может быть пустым.
«Список заказов на отправку Почтой России» - документ, содержащий информацию по заказам, которые
Заказчик поручает Исполнителю доставить на Почту России.
«Список заказов на отправку через постаматы» - документ, содержащий информацию по заказам,
которые Заказчик поручает Исполнителю доставить до постаматов.
«Список заказов на удаление» - документ, содержащий перечень заказов, которые необходимо удалить из
базы Твой Курьер в случае их ошибочного импорта. Условием возможности удаления заказа является
отсутствие какой-либо выполненной работы по данному заказу (статус заказа «В обработке»).
ИМ отправляет POST запрос на адрес:

для документа «Список заказов на доставку»:
http://tvoykurier.ru/ishop/xml/im_integrator_neworder.php;

для документа «Список заказов на самовывоз»:
http://tvoykurier.ru/ishop/xml/im_integrator_newcarry.php;
для документа «Заявка на забор товара с Вашего склада»:

http://tvoykurier.ru/ishop/xml/im_integrator_newexport.php;
для документа «Заявка на привоз товара на наш склад»:

http://tvoykurier.ru/ishop/xml/im_integrator_newselfexport.php;
для документа «Список заказов на отправку Почтой России»:

http://tvoykurier.ru/ishop/xml/im_integrator_newrp.php;
для документа «Список заказов на отправку через постаматы»:

http://tvoykurier.ru/ishop/xml/im_integrator_newpostamat.php;
для документа «Список заказов на удаление»:

http://tvoykurier.ru/ishop/xml/delete_orders.php.
с заполненной переменной $_POST['xml_request'], в которой передается содержимое XML фaйла.
Сервер Твой Курьер вернет результат в виде:

при удачной обработке данных header("http/1.0 200 Ok");
и XML в виде:
<?xml version="1.0" encoding="CP1251"?>
<response><Order Msg="Добавлено заказов CntOrder"/><response/>

при ошибке: header("http/1.0 200 server error")
и XML в виде:
<?xml version="1.0" encoding="CP1251"?>
<response><Order Msg="Error: описание ошибки"/><response/>
Код состояния HTTP не говорит о результате загрузки, необходимо обрабатывать возвращаемый XML.
Если были указаны электронные адреса для отправки уведомлений, будет отправлено письмо c результатом
обработки документов с электронного адреса: noreply@tvoykurier.ru. Не забудьте добавить этот адрес в
белый список адресов, чтобы письма с этого адреса не уходили в СПАМ.
Важно:
 При возникновении ошибки на любом этапе обработки документа, заказы, не имеющие ошибок,
импортируются, по остальным - передается информация в формате XML и на email (в случае, если
он указан в Вашем личном кабинете).
«Твой Курьер»
cтр. 4 из 33
 Изменения в базе Твой Курьер происходят сразу после удачной обработки запроса.
 Ограничений на количество запросов в сутки нет.
 При работе тестового аккаунта изменения, переданные в тестовом режиме, будут аннулированы
автоматически в 23.00 по московскому времени.
7.
По запросу ИМ формируется шесть видов документов: «Список пунктов выдачи заказов
(ПВЗ)», «Статусы заказов», «Информация по заказам», «Список городов и их номеров в
базе», «Список регионов и их номеров в базе», «Список стран и их номеров в базе».
Документ «Список пунктов выдачи заказов (ПВЗ)» предоставляет список ПВЗ, действующих на момент
запроса.
ИМ отправляет запрос на
http://tvoykurier.ru/ishop/xml/pvzlist.php?cityid=994,
переменная cityid – код города для которого необходим список ПВЗ, необязательный параметр. При
отсутствии параметра cityid список ПВЗ содержит данные по всем городам. Атрибут ПВЗ используется в
документе «Список заказов на самовывоз».
Отчет «Статусы заказов» передает информацию последнего статуса заказа, по которому были изменения
от даты_времени datefirst включительно по текущий момент или даты_времени datelast.
Всю историю изменений статусов заказов, выбранных по вышеописанным условиям, можно получить при
значении переменной showhistory = 1.
В отчете также предоставляются данные по неудавшимся попыткам доставки в разрезе расписания
доставки, предоставленного Интернет-Магазином.
ИМ отправляет запрос на
http://tvoykurier.ru/status_report_h.php?account=123&secure=c3b51896d86675dc3205a8d7ef833a15&datefirst=1
362782757&showhistory=1
Сервер Твой Курьер вернет XML фaйл в виде «Отчет «Статусы заказов».
Запрос статусов можно делать не чаще одного раза в одну минуту. Рекомендуем выставлять интервал один
раз в 5 или 10 минут.
Отчет «Информация по заказам» предоставляет данные:

по ключевым параметрам заказа, формирующим стоимость услуг Твой Курьер;

о дате последнего изменения суммы заказа.
ИМ отправляет запрос на http://tvoykurier.ru/ishop/xml/info_report.php с заполненной переменной
$_POST['xml_request'], в которой передается содержимое XML фaйла (описание см. ниже). В результате
также возвращается XML (описание см. ниже)
Список «Список городов и их номеров в базе» выдает все города с индексами, в формате XML,
содержавшиеся в базе Твой Курьер.
ИМ отправляет запрос на http://tvoykurier.ru/ishop/xml/city_list.php
Дополнительный параметр id_country (метод GET), который содержит ID страны, по которому нужно
вывести города. Если параметр пуст, то выводятся все города по России.
Дополнительный параметр id_region (метод GET), по которому можно вывести все города и населенные
пункты в конкретном регионе любой страны.
Список «Список регионов и их номеров в базе» выдает все регионы с индексами, в формате XML,
содержавшиеся в базе Твой Курьер.
ИМ отправляет запрос на http://tvoykurier.ru/ishop/xml/region_list.php
Дополнительный параметр id_country, который содержит ID страны, по которому нужно вывести регионы.
Если параметр пуст, то выводятся все регионы по России.
Список «Список стран и их номеров в базе» выдает все города с индексами, в формате XML,
содержавшиеся в базе Твой Курьер.
ИМ отправляет запрос на http://tvoykurier.ru/ishop/xml/country_list.php
Метод GET. Обязательные параметры: account, secure.
«Твой Курьер»
cтр. 5 из 33
Отчет «Запрос статуса заказа от ИМ к ТК» (п. 10):
ИМ отправляет запрос на http://tvoykurier.ru/ishop/xml/get_order_status.php с параметрами account и secure и
заполненными параметрами id или num_order (ID заказа по базе Твой Курьер или номер заказа по базе Твой
Курьер соответственно).
Запрос «Запрос от ИМ в ТК о стоимости доставки или самовывоза (калькулятор)»
ИМ отправляет запрос на http://tvoykurier.ru/ishop/xml/im_calc.php с параметрами account и secure, а так же
дополнительными параметрами, описанными в п. 12. Всё передаётся методом GET.
Все запросы/вопросы необходимо присылать на e-mail integrator@tvoykurier.ru с темой письма «Интеграция
Твой Курьер, клиент Название_Вашей_Компании, Номер_Договора,_если_есть».
«Твой Курьер»
cтр. 6 из 33
3. Список пунктов выдачи заказов (ПВЗ)
№
Тэг/Атрибут
Описание
Тип поля
Обяз. для
заполн.
1.
PvzList
Заголовок документа
да
2.
Pvz
ПВЗ
да
2.1.
Code
ID пункта выдачи
2.2.
Name
Название
2.3.
CountryCode
2.4.
number
да
varchar(50)
да
Код страны по базе Твой Курьер
number
да
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="(495)
«Твой Курьер»
cтр. 7 из 33
9-433-433, (495) 642-5466" 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
да
«Твой Курьер»
cтр. 8 из 33
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
да
Goods
Товары. Минимум один товар в заказе
должен присутствовать
3.
3.1.
Number
Порядок
сортировки
товаров
для
отображения
в
сопроводительных
документах
3.2.
Barcode
Штрих-код упаковки
3.3.
Name
Наименование вложения
3.4.
Weight
3.5.
да
number
да
varchar(100)
да
text
да
Вес в кг (за единицу)
double
да
Quantity
Количество единиц
number
да
3.6.
Сost
Стоимость товара, закупочная цена (за
единицу)
double
да
3.7.
Price
Стоимость товара для покупателя (за
единицу)
double
да
3.8.
Bundling
Комплектация данной единицы товара.
Значение 1 или 0 – комплектовать или не
комплектовать
number
да
4.
4.1.
Service
Cash
Дополнительные услуги
Услуга
«наложенный
платеж».
Включается всегда (значение 1), когда
требуется забрать денежные средства от
покупателя. Если услуга выключена
(значение 0), то денежные средства с
покупателя браться не будут. Рекомендуем
включать услугу автоматически, если
«Твой Курьер»
да
number
cтр. 9 из 33
да
стоимость товара по данному заказу более
0 рублей.
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
нет
Contacts
Контактные данные покупателя
5.
да
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)
нет
«Твой Курьер»
cтр. 10 из 33
5.9.
Kod
Код домофона получателя
5.10.
Phones
Телефоны получателя. Если несколько, то
через запятую.
varchar(100)
нет
text
да
* Габариты упаковки необходимо указывать, если упаковка представляет собой коробку. С учетом
габаритов вычисляется объемный вес по формуле А * В * С/5000, где A, B, C – длина, ширина, высота
упаковки. Расчет стоимости доставки идет из максимального значения между фактическим и объемным
весом. Рекомендуем в системах управления ИМ сделать доп. поля к каждому товару с длиной, шириной и
высотой и заполнять их по необходимости.
Пример:
Файл содержит данные по двум заказам.
В первом заказе наложенный платеж не включает стоимость за доставку, которую ИМ берет с покупателя.
Второй заказ содержит два места, один товар в подарок и скидку на 500 рублей.
<?xml version="1.0" encoding="UTF-8" ?>
<orders type="delivery" number="1575" date="2013-01-27 15:53:49" ordercount="2">
<order number="R87512" places="1" sendercity="994" recipcity="994" d_date="27.01.2013"
b_time="11" e_time="14" dim_x="20" dim_y="43" dim_z="25" tk_card_num="0000-0001-1234"
comments="комментарий к заказу">
<goods number="1" barcode="158575" name="Телефон Sampsung 3310" weight="1.2" quantity="2"
cost="2020.00" price="3157.40" bundling="1"></goods>
<goods number="2" barcode="1902" name="Телевизор TV P7956RT" weight="7.1" quantity="1"
cost="4530.00" price="7150.00" bundling="0"></goods>
<goods number="3" barcode="1585" name="Приставка 652" weight="2.0" quantity="1" cost="530.00"
price="1530.50" bundling="1"></goods>
<incl_delivery val="0" price="0"></incl_delivery>
<service cash="1" cheque="1" dcall="0" sms="1" sms_phone="79151234567" pack="0"
express="0"></service>
<contacts name="Иванов Иван Иванович" country="1" city="994" ul="Тверская" home="20/1"
corp="2" flat="110" flour="3" kod="30K2596" phones="8-495-1234567, +7 916 1234567"></contacts>
</order>
<order number="R87513" places="2" sendercity="994" recipcity="994" d_date="27.01.2013"
b_time="11" e_time="14" dim_x="20" dim_y="43" dim_z="25" tk_card_num="0000-0001-1234"
comments="комментарий к заказу">
<goods number="1" barcode="158575" name="Телефон Sampsung 3310" weight="1.2" quantity="2"
cost="2020.00" price="3157.40" bundling="1"></goods>
<goods number="2" barcode="1902" name="Телевизор TV P7956RT" weight="7.1" quantity="1"
cost="4530.00" price="7150.00" bundling="0"></goods>
<!-- если приставка - это подарок, то цена (price)= 0, cost в данном случае для материальной
ответственности за данный товар -->
<goods number="3" barcode="1585" name="Приставка 652" weight="2.0" quantity="1" cost="530.00"
price="0.00" bundling="1"></goods>
<!-- например, если Вы хотите сделать скидку покупателю на 1000 рублей, то добавляете товар
"скидка" с отрицательной стоимостью, название товара в этом случае ОБЯЗАНО быть «скидка» или
«Скидка», иначе программа не пропустит отрицательную стоимость! -->
<goods number="3" barcode="0" name="Скидка" weight="0.1" quantity="1" cost="0.00" price="1000.00" bundling="0"></goods>
<incl_delivery val="1" price="350.50"></incl_delivery>
<service cash="1" cheque="1" dcall="1" sms="0" sms_phone="0" pack="1" express="0"></service>
<contacts name="Иванов Иван Иванович" compname="Ромашка" country="1" city="994" ul="Тверская"
home="20/1" corp="2" flat="110" flour="3" kod="30K2596" phones="8-495-1234567, +7 916
1234567"></contacts>
</order>
</orders>
«Твой Курьер»
cтр. 11 из 33
5. Список заказов на самовывоз
№
Тэг/Атрибут
Описание
Тип поля
Обяз. для
заполн.
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.
E-date
Конечная дата самовывоза. Срок не более
2-х недель.
d.m.Y
да
2.7.
Id_pvz
Номер пункта самовывоза по базе Твой
Курьер.
number
да
2.8.
Dim_x
Габариты груза. Длина (в сантиметрах)*
number
нет
2.9.
Dim_y
Габариты груза. Ширина (в сантиметрах)*
number
нет
2.10.
Dim_z
Габариты груза. Высота (в сантиметрах)*
number
нет
2.11.
TK_card_num
Номер дисконтной карты ТК, по которой
покупатель получил скидку.
ВНИМАНИЕ!!! Данное поле либо
остается пустым, либо в него пишется
varchar(100)
Нет
«Твой Курьер»
cтр. 12 из 33
только номер дисконтной карты ТК
(карта, организатором которой является
компания Твой Курьер). Просим не писать
в это поле номер любой Вашей
дисконтной карты.
2.12.
2.13.
Comments
Incl_delivery
Комментарий по заказу
нет
Text
Включить в бланк цену доставки
да
2.13.1.
Val
Значение 1 или 0 – включить или не
включать
number
да
2.13.2.
Price
Стоимость доставки для клиента в рублях
double
да
Goods
Товары. Минимум один товар в заказе
должен присутствовать
3.
3.1.
Number
Порядок
сортировки
товаров
для
отображения
в
сопроводительных
документах
3.2.
Barcode
Штрих-код упаковки
3.3.
Name
Наименование вложения
3.4.
Weight
3.5.
да
number
да
varchar(100)
да
Text
да
Вес в кг (за единицу)
double
да
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
Услуга «кассовое обслуживание». В
системе
управления
магазином
рекомендуем эту настройку вывести в
раздел Настройки в виде галочки.
Помните, что товары без чеков не
доставляются. Не включать эту услугу Вы
можете только тогда, когда сами
number
да
«Твой Курьер»
cтр. 13 из 33
выбиваете кассовые чеки для покупателей
и прикладываете их к товару. Услуга
может быть включена только если у Вас
подписан агентский договор. Значения 0
или 1.
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.
Pack
Услуга упаковки. Значение 0 или 1.
number
нет
Contacts
Контактные данные покупателя
5.
5.1.
Name
Получатель (ФИО)
5.2.
Phones
Телефоны получателя. Если несколько, то
через запятую.
да
varchar(255)
да
Text
да
* Габариты упаковки необходимо указывать, если упаковка представляет собой коробку. С учетом
габаритов вычисляется объемный вес по формуле А * В * С/5000, где A, B, C – длина, ширина, высота
упаковки. Расчет стоимости доставки идет из максимального значения между фактическим и объемным
весом. Рекомендуем в системах управления ИМ сделать доп. поля к каждому товару с длиной, шириной и
высотой и заполнять их по необходимости.
Пример:
<?xml version="1.0" encoding="UTF-8" ?>
<orders type="carry" number="1575" date="2013-01-27 15:53:49" ordercount="1">
<order number="100058745" places="2" sendercity="994" recipcity="994" d_date="27.01.2013"
e_date="30.01.2011" dim_x="20" dim_y="43" dim_z="25" tk_card_num="0000-0001-1234" id_pvz="21"
comments="комментарий">
<goods number="1" barcode="158575" name="Телефон Sampsung 3310" weight="1.2" quantity="2"
cost="2020.00" price="3157.40" bundling="1"></goods>
<goods number="2" barcode="1902" name="Телевизор TV P7956RT" weight="7.1" quantity="1"
cost="4530.00" price="7150.00" bundling="0"></goods>
<goods number="3" barcode="1585" name="Приставка 652" weight="2.0" quantity="1" cost="530.00"
price="1529.90" bundling="1"></goods>
<incl_delivery val="1" price="350"></incl_delivery>
<service cash="1" cheque="1" dcall="0" sms="0" sms_phone="" pack="0"></service>
<contacts name="Иванов Иван Иванович" phones="8-495-1234567, +7 916 1234567"></contacts>
</order>
</orders>
«Твой Курьер»
cтр. 14 из 33
6. Список заказов на отправку Почтой России
№
Тэг/Атрибут
Описание
Тип поля
Обяз. для
заполн.
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.
Type
Тип отправки, значения: 1-посылка; 2бандероль, 1-й класс.
number
да
2.5.
D_date
Дата, когда нужно отправить. Дата
должна быть не ранее, чем товар
поступит на склад Твой Курьер.
Пример значения: 27.01.2013
d.m.Y
да
2.6.
Dim_x
Габариты груза. Длина (в сантиметрах)*
number
нет
2.7.
Dim_y
Габариты груза. Ширина (в сантиметрах)*
number
нет
2.8.
Dim_z
Габариты груза. Высота (в сантиметрах)*
number
нет
2.9.
TK_card_num
Номер дисконтной карты ТК, по которой
покупатель получил скидку.
ВНИМАНИЕ!!! Данное поле либо
остается пустым, либо в него пишется
только номер дисконтной карты ТК
(карта, организатором которой является
компания Твой Курьер). Просим не писать
в это поле номер любой Вашей
дисконтной карты.
varchar(100)
Нет
2.10.
Incl_delivery
Включить в бланк цену доставки
«Твой Курьер»
да
cтр. 15 из 33
2.10.1.
Val
Значение 1 или 0 – включить или не
включать
number
да
2.10.2.
Price
Стоимость доставки для клиента в рублях
double
да
Goods
Товары. Минимум один товар в заказе
должен присутствовать
3.
3.1.
Number
Порядок
сортировки
товаров
для
отображения
в
сопроводительных
документах
3.2.
Barcode
Штрих-код упаковки
3.3.
Name
Наименование вложения
3.4.
Weight
3.5.
да
number
да
varchar(100)
да
text
да
Вес в кг (за единицу)
double
да
Quantity
Количество единиц
number
да
3.6.
Сost
Стоимость товара, закупочная цена (за
единицу)
double
да
3.7.
Price
Стоимость товара для покупателя (за
единицу)
double
да
3.8.
Bundling
Комплектация данной единицы товара.
Значение 1 или 0 – комплектовать или не
комплектовать
number
да
4.
Service
Дополнительные услуги Почты
России
да
4.1.
Cash
Услуга
«наложенный
платеж».
Включается всегда (значение 1), когда
требуется забрать денежные средства от
покупателя. Если услуга выключена
(значение 0), то денежные средства с
покупателя браться не будут.
number
нет
4.2.
Declare_cost
Услуга
«Объявленная стоимость».
В
системе
управления
магазином
рекомендуем эту настройку вывести в
раздел Настройки в виде галочки.
Значения 0 или 1.
number
нет
4.3.
Fragile
Услуга «Хрупкий груз». Значения 0 или 1.
number
нет
5.
Contacts
Контактные данные покупателя
5.1.
Name
Получатель (ФИО)
5.2.
Index
Индекс Почты России
5.2.
Region
5.3.
City
да
varchar(255)
да
number
да
Регион покупателя НЕ из базы Твой
Курьер
varchar(255)
да
Город получателя НЕ из базы Твой
Курьер
varchar(255)
да
«Твой Курьер»
cтр. 16 из 33
5.4.
Address
Адрес получателя
text
да
5.6.
Phones
Телефоны получателя. Если несколько, то
через запятую.
text
да
* Габариты упаковки необходимо указывать, если упаковка представляет собой коробку. С учетом
габаритов вычисляется объемный вес по формуле А * В * С/5000, где A, B, C – длина, ширина, высота
упаковки. Расчет стоимости доставки идет из максимального значения между фактическим и объемным
весом. Рекомендуем в системах управления ИМ сделать доп. поля к каждому товару с длиной, шириной и
высотой и заполнять их по необходимости.
Пример:
<?xml version="1.0" encoding="UTF-8" ?>
<orders type="rp" number="1575" date="2013-01-27 15:53:49" OrderCount="1">
<order number="R87512" type="1" places="2" sendercity="994" d_date="27.01.2013" dim_x="20"
dim_y="43" dim_z="25" tk_card_num="0000-0001-1234">
<goods number="1" barcode="158575" name="Телефон Sampsung 3310" weight="1.2" quantity="2"
cost="2020.00" price="3157.40" bundling="1"></goods>
<goods number="2" barcode="1902" name="Телевизор TV P7956RT" weight="7.1" quantity="1"
cost="4530.00" price="7150.00" bundling="0"></goods>
<incl_delivery val="1" price="350.30"></incl_delivery>
<service cash="1" declare_cost="1" fragile="1"></service>
<contacts name="Иванов Иван Иванович" index="104578" region="Камчатский край"
city="Петропавловск Камчатский" address="ул. Парковая д. 23, кв. 10" phones="8-495-1234567, +7
916 1234567"></contacts>
</order>
</orders>
«Твой Курьер»
cтр. 17 из 33
7. Список заказов на доставку через постаматы
№
Тэг/Атрибут
Описание
Тип поля
Обяз. для
заполн.
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.
id_postamat
ID постамата по базе Твой Курьер
number
да
2.5.
D_date
Дата, когда нужно отправить. Дата
должна быть не ранее, чем товар
поступит на склад Твой Курьер.
Пример значения: 27.01.2013
d.m.Y
да
2.6.
Dim_x
Габариты груза. Длина (в сантиметрах)*
number
да
2.7.
Dim_y
Габариты груза. Ширина (в сантиметрах)*
number
да
2.8.
Dim_z
Габариты груза. Высота (в сантиметрах)*
number
да
2.9.
TK_card_num
Номер дисконтной карты ТК, по которой
покупатель получил скидку.
ВНИМАНИЕ!!! Данное поле либо
остается пустым, либо в него пишется
только номер дисконтной карты ТК
(карта, организатором которой является
компания Твой Курьер). Просим не писать
в это поле номер любой Вашей
дисконтной карты.
varchar(100)
Нет
2.10.
Incl_delivery
Включить в бланк цену доставки
«Твой Курьер»
да
cтр. 18 из 33
2.10.1.
Val
Значение 1 или 0 – включить или не
включать
number
да
2.10.2.
Price
Стоимость доставки для клиента в рублях
double
да
Goods
Товары. Минимум один товар в заказе
должен присутствовать
3.
3.1.
Number
Порядок
сортировки
товаров
для
отображения
в
сопроводительных
документах
3.2.
Barcode
Штрих-код упаковки
3.3.
Name
Наименование вложения
3.4.
Weight
3.5.
да
number
да
varchar(100)
да
text
да
Вес в кг (за единицу)
double
да
Quantity
Количество единиц
number
да
3.6.
Сost
Стоимость товара, закупочная цена (за
единицу)
double
да
3.7.
Price
Стоимость товара для покупателя (за
единицу)
double
да
3.8.
Bundling
Комплектация данной единицы товара.
Значение 1 или 0 – комплектовать или не
комплектовать
number
да
4.
Service
Дополнительные услуги
да
4.1.
Cash
Услуга
«наложенный
платеж».
Включается всегда (значение 1), когда
требуется забрать денежные средства от
покупателя. Если услуга выключена
(значение 0), то денежные средства с
покупателя браться не будут.
number
нет
4.2.
Declare_cost
Услуга
«Объявленная стоимость».
В
системе
управления
магазином
рекомендуем эту настройку вывести в
раздел Настройки в виде галочки.
Значения 0 или 1.
number
нет
4.3.
Fragile
Услуга «Хрупкий груз». Значения 0 или 1.
number
нет
5.
Contacts
Контактные данные покупателя
5.1.
Name
Получатель (ФИО)
5.2.
Phones
Телефоны получателя. Если несколько, то
через запятую.
да
varchar(255)
да
text
да
* Габариты упаковки необходимо указывать, если упаковка представляет собой коробку. С учетом
габаритов вычисляется объемный вес по формуле А * В * С/5000, где A, B, C – длина, ширина, высота
упаковки. Расчет стоимости доставки идет из максимального значения между фактическим и объемным
весом. Рекомендуем в системах управления ИМ сделать доп. поля к каждому товару с длиной, шириной и
высотой и заполнять их по необходимости.
«Твой Курьер»
cтр. 19 из 33
Пример:
<?xml version="1.0" encoding="UTF-8" ?>
<orders type="postamat" number="1575" date="2013-01-27 15:53:49" OrderCount="1">
<order number="R87512" places="2" sendercity="994" d_date="27.01.2013" dim_x="20" dim_y="43"
dim_z="25" tk_card_num="0000-0001-1234" id_postamat="10">
<goods number="1" barcode="158575" name="Телефон Sampsung 3310" weight="1.2" quantity="2"
cost="2020.00" price="3157.40" bundling="1"></goods>
<goods number="2" barcode="1902" name="Телевизор TV P7956RT" weight="7.1" quantity="1"
cost="4530.00" price="7150.00" bundling="0"></goods>
<incl_delivery val="1" price="350.30"></incl_delivery>
<service cash="1" declare_cost="1" fragile="1"></service>
<contacts name="Иван Иванович" phones="8-495-1234567, +7 916 1234567"></contacts>
</order>
</orders>
«Твой Курьер»
cтр. 20 из 33
8. Список заказов на удаление
№
Тэг/Атрибут
Описание
1.
DeleteRequest
Заголовок документа
1.1.
Number
Номер акта
1.2.
Date
Дата документа (дата заказа)
1.5.
OrderCount
Общее количество заказов для удаления в
документе
2.
Order
Отправление (заказ)
2.1.
Number
Номер отправления по базе ТК
Тип поля
Обяз. для
заполн.
да
varchar(20)
да
date
да
number
да
да
varchar(20)
да
Удалить можно только те заказы, которые не находятся в конечных или промежуточных статусах, то есть
фактически только в статусах «В обработке» или «Отмена».
Пример:
Документ содержит данные для удаления двух заказов.
<?xml version="1.0" encoding="UTF-8" ?>
<deleterequest number="236" date="2013-08-05" ordercount=”2”>
<order number="01-12345" />
<order number="01-12344" />
</deleterequest>
«Твой Курьер»
cтр. 21 из 33
9. Отчет «Статусы заказов»
Твой Курьер в момент изменения статуса заказа информирует об этом ИМ. Для этого необходимо в личном
кабинете в разделе «API интеграция» включить соответствующую опцию и прописать адрес скрипта,
который отвечает за это на стороне ИМ.
Твой Курьер в момент смены статуса заказа посылает запрос по адресу:
http://адрес_из_настроек_личного_кабинета
Передаваемые параметры (методом POST):
account=ID_аккаунта
secure=API ключ
Так же дополнительно передаются через POST переменные
order_id=номер внутреннего заказа ИМ
order_status=ID статуса
для более упрощенной формы, но мы не рекомендуем пользоваться этими параметрами, так как в этом
случае Вы не сможете видеть, от каких именно товаров отказались и в каком количестве.
Отправляемые Твоим Курьером данные: xml, аналогичный п. 4-7, в зависимости от типа заказа. Примеры
ниже.
Примечание: статусы заказов, отправленных через Почту России не отслеживаются. Как только заказ
передан на почту, статус заказа будет «Выполнен».
Дополнительные параметры:
№
Тэг/Атрибут
Описание
Тип поля
Обяз. для
заполн.
да
1.
Order
1.1.
Status
ID статуса данного заказа по базе Твой
Курьер в настоящее время
Number
да
1.2.
Price
Стоимость услуг компании Твой Курьер
Double
да
2.
Goods
2.1.
Status
Статус данного товара:
0 – нет на складе, 1 – поступил на склад
ТК, 2 – отгружен на доставку, 3 –
возвращен заказчику, 4 – куплен, 5 – отказ
покупателем и возврат на склад.
Рекомендуем эти опции сделать
настраиваемыми в личном кабинете
интернет-магазина. Эти опции могут
меняться крайне редко, но при их
изменении статусы товаров могут
меняться не корректно.
Number
да
2.2.
Quantity_back
Количество единиц товара, от которых
отказались. Если купили все, то 0.
Number
да
да
Примеры:
1.
Тип заказа – доставка
«Твой Курьер»
cтр. 22 из 33
<?xml version="1.0" encoding="UTF-8" ?>
<order number="R87512" places="2" sendercity="994" recipcity="994" d_date="27.01.2013"
b_time="11" e_time="14" dim_x="20" dim_y="43" dim_z="25" status="12" price="217.40">
<goods number="1" barcode="158575" name="Телефон Sampsung 3310" weight="1.2" quantity="2"
cost="2020.00" price="3157.40" bundling="1" status=”5” quantity_back="1"></goods>
<goods number="2" barcode="1902" name="Телевизор TV P7956RT" weight="7.1" quantity="1"
cost="4530.00" price="7150.00" bundling="0" status=”5” quantity_back="1"></goods>
<goods number="3" barcode="1585" name="Приставка 652" weight="2.0" quantity="1"
cost="530.00" price="0.00" bundling="1" status=”4” quantity_back="0"></goods>
<goods number="3" barcode="0" name="Скидка" weight="0.1" quantity="1" cost="-1000.00"
price="0.00" bundling="0" status=”4” quantity_back="0"></goods>
<incl_delivery val="1" price="350.30"></incl_delivery>
<service cash="1" cheque="1" dcall="1" sms="1" pack="0" sms_phone="79151234567"
express="0"></service>
<contacts name="Иванов Иван Иванович" compname="Ромашка" country="1" city="994"
ul="Тверская" home="20/1" corp="2" flat="110" flour="3" kod="30K2596" phones="8-495-1234567, +7
916 1234567"></contacts>
</order>
2.
Тип заказа – самовывоз
<?xml version="1.0" encoding="UTF-8" ?>
<order number="100058745" places="2" sendercity="994" recipcity="994" d_date="27.01.2013"
e_date="30.01.2011" dim_x="20" dim_y="43" dim_z="25" id_pvz="21" status="12" price="110.40">
<goods number="1" barcode="158575" name="Телефон Sampsung 3310" weight="1.2"
quantity="2" cost="2020.00" price="3157.40" bundling="1" status=”5” quantity_back="1"></goods>
<goods number="2" barcode="1902" name="Телевизор TV P7956RT" weight="7.1" quantity="1"
cost="4530.00" price="7150.00" bundling="0" status=”5” quantity_back="1"></goods>
<goods number="3" barcode="1585" name="Приставка 652" weight="2.0" quantity="1"
cost="530.00" price="1529.90" bundling="1" status=”4” quantity_back="0"></goods>
<incl_delivery val="1" price="350"></incl_delivery>
<service cash="1" cheque="1" dcall="0" sms="0" pack="0" sms_phone=""></service>
<contacts name="Иванов Иван Иванович" phones="8-495-1234567, +7 916 1234567"></contacts>
</order>
3.
Тип заказа – Почта России
<?xml version="1.0" encoding="UTF-8" ?>
<order number="R87512" type="1" places="2" sendercity="994" d_date="27.01.2013" dim_x="20"
dim_y="43" dim_z="25" status="11" price="110.40">
<goods number="1" barcode="158575" name="Телефон Sampsung 3310" weight="1.2"
quantity="2" cost="2020.00" price="3157.40" bundling="1" status=”4” quantity_back="0"></goods>
<goods number="2" barcode="1902" name="Телевизор TV P7956RT" weight="7.1" quantity="1"
cost="4530.00" price="7150.00" bundling="0" status=”4” quantity_back="0"></goods>
<incl_delivery val="1" price="350.30"></incl_delivery>
<service cash="1" declare_cost="1" fragile="1"></service>
<contacts name="Иванов Иван Иванович" index="104578" region="Камчатский край"
city="Петропавловск Камчатский" address="ул. Парковая д. 23, кв. 10" phones="8-495-1234567, +7
916 1234567"></contacts>
</order>
4.
Тип заказа – постаматы
<?xml version="1.0" encoding="UTF-8" ?>
<order number="R87512" places="2" sendercity="994" d_date="27.01.2013" dim_x="20" dim_y="43"
dim_z="25" id_postamat="10" status="11" price="310.20">
<goods number="1" barcode="158575" name="Телефон Sampsung 3310" weight="1.2"
quantity="2" cost="2020.00" price="3157.40" bundling="1" status=”4” quantity_back="0"></goods>
<goods number="2" barcode="1902" name="Телевизор TV P7956RT" weight="7.1" quantity="1"
cost="4530.00" price="7150.00" bundling="0" status=”4” quantity_back="0"></goods>
<incl_delivery val="1" price="350.30"></incl_delivery>
<service cash="1" declare_cost="1" fragile="1"></service>
<contacts name="Иван Иванович" phones="8-495-1234567, +7 916 1234567"></contacts>
</order>
«Твой Курьер»
cтр. 23 из 33
10. Отчет «Запрос статуса заказа от ИМ к ТК»
Магазин отправляет запрос на сервер Твой Курьер по адресу:
http://tvoykurier.ru/ishop/xml/get_order_status.php с параметрами account и secure и заполненными
параметрами:
id=ID заказа по базе Твой Курьер
ИЛИ (именно ИЛИ)
num_order=номер заказа по базе Твой Курьер
В ответ скрипт возвращает одну цифру – ID статуса данного заказа.
Все переменные отправляются методом GET.
«Твой Курьер»
cтр. 24 из 33
11. Запрос от ИМ в ТК данных о дисконтной карте ТК
Если Вы участвуете в программе «Дисконтная карта ТК», необходимо в настройках Вашего магазина
сделать соответствующую галочку под названием «Участвовать в программе «Дисконтная карта ТК».
В случае если данная опция участия в программе дисконтной карты ТК включена, в общедоступной части
Вашего магазина, при оформлении заказа Вашим покупателем, программа обязательно должна предлагать
покупателю ввести номер дисконтной карты ТК и ФИО владельца. После того, как покупатель ввел номер
карты, программа должна:
1.
Сделать запрос на сервер Твой Курьер о существовании такой карты и размере скидки, которую
Вы предлагаете Вашему клиенту по данной карте. В запросе необходимо указать полную сумму
заказа без учета стоимости доставки, для возможности делать магазином переменного процента
скидки от суммы заказа. Например:
В личном кабинете Твой Курьер Вы можете указать фиксированный процент скидки по карте
ТК, например 5%.
Так же Вы можете указать переменный процент скидки по карте ТК. Например, на заказ
итоговой суммой от 0 до 5000 скидка 3%, на заказ от 5001 до 8000 скидка 5%, на заказ от 8001
до 15000 скидка 7%, на заказ свыше 15001 скидка 10% и т. д.;
2.
В случае если от сервера ТК придет положительный результат, программа ИМ должна
пересчитать покупателю стоимость его заказа в соответствии с той скидкой, которую рассчитал
сервер ТК и запомнить в свою базу знаний данные карты и размер скидки.
3.
В случае если от сервера ТК придет отрицательный результат, программа ИМ должна сообщить
покупателю фразу, полученную с сервера ТК из поля reply.
Рекомендуем все вышеперечисленные запросы реализовывать с помощью технологии AJAX (без
перезагрузки страницы).
Номер, указанный покупателем в заказе обязан быть передан серверу ТК при передаче данных о заказе для
того, чтобы сервер ТК мог вести сводную статистику о накопительных бонусах на картах покупателей и об
итоговых суммах совершенных заказов по любой карте ТК.
По правилам участия в программе «Дисконтная карта ТК», картой ТК может воспользоваться любой, в том
числе, не только ее владелец, то есть ФИО владельца карты не обязана совпадать с ФИО покупателя товара.
Адрес запроса: http://tvoykurier.ru/ishop/xml/im_integrator_tkcardinfo.php
Параметры запроса:
num=номер_дисконтной_карты_ТК (только цифры и допускается символ ‘-‘)
account=ID_аккаунта
secure=API _ключ_из_личного_кабинета
order_summ=итоговая_сумма_по_заказу
Пример ответа сервера в случае, если карта зарегистрирована в базе:
<?xml version="1.0" encoding="UTF-8" ?>
<card number="0000-0001-1234" fio="Иванов Иван Иванович" discount="3" date_register="27.01.2013"
status="1" reply="">
Пример ответа сервера в случае, если карта НЕ зарегистрирована в базе:
<?xml version="1.0" encoding="UTF-8" ?>
<card number="0000-0001-1234" fio="" discount="0" date_register="00.00.0000" status="0"
reply="Вы ввели не верный номер карты. Пожалуйста, проверьте введенные Вами данные.">
«Твой Курьер»
cтр. 25 из 33
12. Запрос от ИМ в ТК о стоимости доставки или
самовывоза (калькулятор)
Запрос отправляется по адресу: http://tvoykurier.ru/ishop/xml/im_calc.php
Крайне Вам рекомендуем пользоваться калькулятором в пользовательской части магазина на этапе, когда
Ваш клиент переходит к оформлению заказа в корзине, выбирает способ доставки, после чего Вы можете
ему рассчитать итоговую стоимость доставки и, при необходимости, прибавить к ней свою.
Все переменные передаются методом GET. Помимо основных переменных account и secure так же
присутствуют дополнительные:
№
Переменная
Описание
Тип поля
Обяз. для
заполн.
1.
quantity
Количество товаров (массив через
запятую и без пробелов).
Пример: 10,1,12
String
да
2.
weight
Вес товаров (массив через запятую и без
пробелов)
Пример: 0.01,1,5
String
да
3.
price
Массив цен товаров (через запятую и без
пробелов)
String
Да
String
да
Пример: 1200,100.5,500
4.
bundling
Комплектация (через запятую и без
пробелов)
Пример: 1,0,1
5.
incl_deliv
Включить в бланк цену доставки (1 или 0)
Boolean
Нет
6.
client_d_price
Цена доставки для клиента (1 или 0)
Integer
нет, если
incl_deliv 0
7.
cheque
Услуга ЧЕК или Кассовое обслуживание
(1 или 0)
Boolean
нет
8.
cash
Услуга Наложенный платеж (1 или 0)
Boolean
нет
9.
sms
Услуга SMS (1 или 0)
Boolean
нет
10.
dcall
Услуга дополнительного прозвона клиента
(1 или 0)
Boolean
нет
11.
pack
Услуга дополнительной упаковки (1 или
0)
Boolean
нет
12.
express
Услуга экспресс доставки день в день (1
или 0)
Boolean
нет
Пока не введена и калькулятором не
обрабатывается.
«Твой Курьер»
cтр. 26 из 33
13.
b_time*
Время доставки С (например с 10)
Integer
нет
14.
e_time*
Время доставки ДО (например до 18)
Integer
нет
15.
weekend
Доставка в выходной день (1 или 0)
Boolean
нет
16.
carry
Самовывоз или доставка (ВНИМАНИЕ!!!)
Boolean
нет
Если 0, то самовывоз, если 1, то доставка.
Это не ошибка, именно всё наоборот.
17.
office
ID пункта выдачи заказов
Integer
нет, если
carry=1
18.
city_from
ID города, откуда идет доставка
Integer
да
19.
city_to
ID города, куда идет доставка
Integer
да
20.
dist_country
Расстояние от города (км)
Integer
нет
21.
country
ID страны. На данный момент значение
всегда 1.
Integer
да
* эти параметры могут стать обязательными, как только введется услуга вечерней доставки (с 19 до 22) за
дополнительную плату. Рекомендуем эти параметры пока забить статично с 10 до 18
Возвращаемые значения:
Double;Double;Double – стоимость услуги Твоего Курьера;Общая сумма для получения от
покупателя;Общий вес всех товаров
Пример:
405.11;12900.50;2.1
«Твой Курьер»
cтр. 27 из 33
13. Список постоматов
№
Тэг/Атрибут
Описание
Тип поля
Обяз. для
заполн.
1.
PostomatList
Заголовок документа
да
2.
Postomat
Постомат
да
2.1.
Code
ID постамата
2.2.
Name
Название
2.3.
CountryCode
2.4.
number
да
varchar(50)
да
Код страны по базе Твой Курьер
number
да
CityCode
Код города по базе Твой Курьер
number
да
2.5.
City
Название города
varchar(50)
да
2.6.
WorkTime
Режим работы
varchar(100)
да
2.7.
Address
Адрес
varchar(255)
да
2.9.
GPSlong
GPS координата ПВЗ
float
да
2.10.
GPSlat
GPS координата ПВЗ
float
да
2.11.
Desc
Описание, как пройти до постамата
text
Нет
Пример:
Документ содержит список ПВЗ в городе Москва.
<?xml version="1.0" encoding="UTF-8" ?>
<postomatlist>
<postomat code="231" name="Волгоградка" countrycode="1" citycode="994" city="Москва"
worktime="круглосуточно" address="Волгоградский проспект, д. 32, корп. 26" gpslong="51.35478"
gpslat="34.78945" desc="Первый вагон из центра, метро Волгоградский проспект, 10 метров от метро
с правой стороны"/></pvz>
</postomatlist>
«Твой Курьер»
cтр. 28 из 33
14. Коды ошибок
Код ошибки
Расшифровка ошибки
ERR_INVALID_XML
Неверный формат XML. #var1
Интернет-магазин не идентифицирован:
Account=#var1, Secure=#var2
ERR_AUTH
ERR_NEED_ATTRIBUTE
ERR_SENDCITYCODE
ERR_RECCITYCODE
ERR_SENDCITYPOSTCODE
ERR_RECCITYPOSTCODE
ERR_SENDCITYPOSTCODE_DUBL
ERR_RECCITYPOSTCODE_DUBL
ERR_NOT_FOUND_SENDCITY
ERR_NOT_FOUND_RECCITY
ERR_INVALID_TARIFFTYPECODE
ERR_INVALID_SERVICECODE
ERR_NOT_FOUND_TARIFFTYPECODE
ERR_NOT_EQUAL_ORDERCOUNT
ERR_NOT_EQUAL_CALLCOUNT
ERR_ORDER_DUBL
ERR_SCHEDULE_DUBL
ERR_CALL_DUBL
ERR_ORDER_DUBL_EXISTS
ERR_FIRST_DUBL_EXISTS
ERR_CASH_LIMIT
ERR_CASH_NO
ERR_INVALID_WEIGHT
Отсутствие обязательного атрибута: #var1
Код города отправителя отсутствует в базе
ТВОЙ КУРЬЕР: SendCityCode=#var1
Код города получателя отсутствует в базе
ТВОЙ КУРЬЕР: RecCityCode=#var1
Почтовый индекс города отправителя
отсутствует в базе ТВОЙ КУРЬЕР:
SendCityPostCode=#var1
Почтовый индекс города получателя
отсутствует в базе ТВОЙ КУРЬЕР:
RecCityPostCode=#var1
Невозможно однозначно идентифицировать
город отправителя по почтовому индексу:
SendCityPostCode=#var1
Невозможно однозначно идентифицировать
город получателя по почтовому индексу:
RecCityPostCode=#var1
Отсутствуют параметры для идентификации
города отправителя: SendCityCode,
SendCityPostCode
Отсутствуют параметры для идентификации
города получателя: RecCityCode,
RecCityPostCode
Тариф не идентифицирован по коду:
TariffTypeCode=#var1
Дополнительная услуга не идентифицирована
по коду: ServiceCode=#var1
Тариф по переданному направлению не
существует: TariffTypeCode=#var1
Количество передаваемых заказов не
соответствует контрольному значению:
OrderCount=#var1
Количество передаваемых заявок на вызов
курьера не соответствует контрольному
значению: CallCount=#var1
Дублирование заказа в документе:
Number=#var1
Дублирование номеров заказов в документе:
Number=#var1
Дублирование вызова курьера на одну дату :
Date=#var1
Заказ существует в базе ТВОЙ КУРЬЕР:
Number=#var1
Заявка на вызов курьера существует в базе
ТВОЙ КУРЬЕР на дату: Date=#var1
Ограничение суммы наложенного платежа в
городе получателя в размере: #var1
Получение наложенного платежа в городе
невозможно: #var1
Значение веса должно быть положительным:
Weight= #var1
«Твой Курьер»
cтр. 29 из 33
ERR_INVALID_PAYMENT
ERR_INVALID_COST
ERR_INVALID_AMOUNT
ERR_INVALID_DELIVERYRECIPIENTCOST
Невалидное значение габаритов: #var1=#var2
Ошибка обращение к базе данных ТВОЙ
КУРЬЕР. #var1
ERR_INVALID_SIZE
ERR_DATABASE
Заказ не может быть изменен в статусе: #var1
Отсутствует упаковка в базе ТВОЙ КУРЬЕР:
Number=#var1
Отсутствует вложение в базе ТВОЙ КУРЬЕР с
артикулом: WareKey=#var1
ERR_SCHEDULE_CHANGE
ERR_PACKAGE_NOTFIND
ERR_ITEM_NOTFIND
Невозможно удалить заказ: Number=#var
заказ не найден в базе ТВОЙ КУРЬЕР:
Number=#var1, Date=#var2
Недостаточно параметров для формирования
отчета. Отсутствуют тэг ChangePeriod или
Order.
Превышено ограничение количества заказов в
одном запросе для формирования файла
(max=100)
Невозможно получить файл. Сервер не
отвечает.
Заказ не найден в базе ТВОЙ КУРЬЕР:
DispachNumber=#var1
Временной диапазон ожидания приезда
курьера указан некорректно: TimeBeg>TimeEnd
Временной диапазон обеденного перерыва
указан некорректно: LunchBeg>LunchEnd
Вызов курьера возможно сделать только на
будущую дату:Date=#var1
На текущую дату уже есть вызов курьера:
Date=#var1
Дата вызова курьера дублируется в файле:
Date=#var1
Невозможно удалить заказ, т. к. есть движение
на складе: Number=#var1
ERR_ORDER_DELETE
ERR_INVALID_NUMBER
ERR_INFOREQUEST
ERR_ORDER_COUNT
ERR_FILE_NOTEXISTS
ERR_INVALID_DISPACHNUMBER
ERR_CALLCOURIER_TIME
ERR_CALLCOURIER_TIMELUNCH
ERR_CALLCOURIER_DATETIME
ERR_CALLCOURIER_DATE_EXISTS
ERR_CALLCOURIER_DATE_DUBL
ERR_DELETEREQUEST_ORDER
ERR_DELETEREQUEST_ORDER_DELETED
ERR_CALLCOURIER_TIME_INTERVAL
ERR_CALLCOURIER_COUNT
ERR_CALLCOURIER_CITY
ERR_INFOREQUEST_DATEBEG
ERR_PVZ_NOTFOUND
ERR_PVZCODE
Значение атрибута должно быть
неотрицательным: Payment=#var1
Значение атрибута должно быть
неотрицательным: Cost=#var1
Невалидное значение количества вложений:
Amount=#var1
Значение доп. сбора за доставку должно быть
неотрицательным: DeliveryRecipientCost=#var1
Заказ удален ранее: Number=#var1
Интервал ожидания курьера между TimeBeg и
TimeEnd должен составлять не менее 3
непрерывных часов
Количество передаваемых заявок не
соответствует контрольному значению:
CallCount=#var1
Вызов курьера в выбранном городе
невозможен:SendCityCode=#var1
Недостаточно параметров для формирования
отчета. Отсутствует параметр DateBeg
В выбранном городе ПВЗ отсутствуют:
cityid=#var1
Код ПВЗ отсутствует в базе ТВОЙ КУРЬЕР:
PvzCode=#var1
«Твой Курьер»
cтр. 30 из 33
ERR_ATTRIBUTE_EMPTY
Не задано значение атрибута:#var1
«Твой Курьер»
cтр. 31 из 33
15. Приложение
Таблица 1. Статусы заказов
Идентификатор Статус
Комментарий
Конечный
0
в обработке
Заказ зарегистрирован в базе данных Твой Курьер, но еще не был
принят оператором
нет
1
Отклонена
Заявка отклонена оператором. Причиной может быть некорректное
заполнение адреса или заявки
да
2
заявка принята
Заявка была проверена оператором и принята в обработку
нет
3
в процессе
Заявка в процессе исполнения
нет
4
Комплектация
Заявка передана на склад и находится в стадии комплектации
нет
5
Сортировка
Товар передан на склад и находится в стадии сортировки
нет
6
товар на складе
Товар поступил на склад
нет
7
нет товара
Товар не поступил на склад, заявка не может быть выполнена
да
8
на доставке
Заказ передан водителю и доставляется до покупателя
нет
9
перенос доставки
Заявка перенесена на другой день
нет
10
Отмена
Заявка отменена
да
11
Выполнен
Заказ был выполнен, весь товар по заказу был куплен покупателем
да
12
частичный отказ
Заказ был выполнен, покупатель отказался от части заказов
да
13
полный отказ
Заказ был выполнен, покупатель отказался от всех заказов
да
14
получатель не найден
Получатель не был найден по данному адресу. Заказ считается
выполненным
да
15
телефон не доступен
Телефон покупателя не был доступен, заказ будет перенесен на
следующий рабочий день
нет
16
телефон не верный
Телефон, переданный Заказчиком, был не верный. Заказ подлежит
оплате.
да
17
не верный адрес
Адрес, переданный заказчиком, был не верный. Заказ подлежит оплате.
да
18
перенос по просьбе
получателя
Заказ перенесен, по просьбе получателя, на другой день
нет
19
Удален
Заказ отменен ИМ после регистрации в системе до прихода груза на
склад Твой Курьер в городе-отправителе
да
20
возвращен на склад
отправителя
Повторно оформлен приход в городе-отправителе (не удалось передать
перевозчику по какой-либо причине)
нет
21
выдан на отправку в г.- Оформлен расход со склада Твой Курьер в городе-отправителе. Груз
отправителе
подготовлен к отправке (консолидирован с другими посылками)
нет
22
сдан перевозчику в г.отправителе
Зарегистрирована отправка в городе-отправителе. Консолидированный
груз передан на доставку (в аэропорт/загружен машину)
нет
23
отправлен в г.-транзит
Зарегистрирована отправка в город-транзит. Проставлены дата и время
отправления у перевозчика
нет
24
встречен в г.-транзите
Зарегистрирована встреча в городе-транзите
нет
25
принят на склад
транзита
Оформлен приход в городе-транзите
нет
26
возвращен на склад
транзита
Повторно оформлен приход в городе-транзите (груз возвращен на
склад)
нет
27
выдан на отправку в г.- Оформлен расход в городе-транзите
транзите
нет
28
сдан перевозчику в г.транзите
Зарегистрирована отправка у перевозчика в городе-транзите
нет
29
отправлен в г.получатель
Зарегистрирована отправка в город-получатель, груз в пути
нет
30
встречен в г.получателе
Зарегистрирована встреча груза в городе-получателе
нет
«Твой Курьер»
cтр. 32 из 33
Идентификатор Статус
Комментарий
Конечный
31
принят на склад
доставки
Оформлен приход на склад города-получателя., ожидает доставки до
двери
нет
32
Принят на склад до
востребования
Оформлен приход на склад города-получателя. Посылка ожидает
забора клиентом - покупателем ИМ
нет
33
Возвращен на склад
доставки
Оформлен повторный приход на склад в городе-получателе. Доставка
не удалась по какой-либо причине, ожидается очередная попытка
доставки
нет
34
Не вручен, возврат
Возврат заказа ИМ или комплектация на повторную доставку по
другому заказу
да
Таблица 2. Дополнительные статусы заказов
Идентификатор
Доп.статус
Услуга доставки оказана(0-нет,
1- да)
1
Не должен выполняться: вес отличается от
заявленного более, чем на X г.
0 Не вручен, возврат
2
Не должен выполняться: фактически нет
отправления (на бумаге есть)
0 Не вручен, возврат
3
Не должен выполняться: дубль номера заказа в
одном акте приема-передачи
0 Не вручен, возврат
4
Не должен выполняться: не доставляем в
данный город/регион
0 Не вручен, возврат
5
Повреждение упаковки, при приемке от
отправителя
0 Не вручен, возврат
6
Повреждение упаковки, у перевозчика
0 Не вручен, возврат
7
Повреждение упаковки, на нашем
складе/доставке у курьера
0 Не вручен, возврат
8
Отказ от получения: Без объяснения
1 Не вручен, возврат
9
Отказ от получения: Претензия к качеству
товара
1 Не вручен, возврат
10
Отказ от получения: Недовложение
1 Не вручен, возврат
11
Отказ от получения: Пересорт
1 Не вручен, возврат
12
Отказ от получения: Не устроили сроки
1 Не вручен, возврат
13
Отказ от получения: Уже купил
1 Не вручен, возврат
14
Отказ от получения: Передумал
1 Не вручен, возврат
15
Отказ от получения: Ошибка оформления
1 Не вручен, возврат
16
Отказ от получения: Повреждение упаковки, у
получателя
1 Не вручен, возврат
17
Отказ от получения: Нет денег
1 Не вручен, возврат
18
Отказ от получения: Товар не подошел/не
понравился
1 Не вручен, возврат
«Твой Курьер»
Соответсвующий
статус
cтр. 33 из 33