API
В системе "Курьерская служба 2008" имеется возможность интеграции средствами XML API, по протоколу HTTP POST.
Общие понятия
На стороне курьерской службы имеется веб-сервис. Адрес уточняйте у представителей компании. Авторизационные данные так же уточняйте у представителей компании. Тестовая площадка доступна по адресу http://lk.courierexe.ru/api/ логин test пароль testm Клиент отправляет запросы к сервису, сервис обрабатывает запросы и возвращает результат выполнения. Все запросы и ответы передаются в формате XML. Кодировка - UTF-8. Разделитель целой и дробной частей чисел - используется символ точки. Даты представляются в виде YYYY-MM-DD, время - HH:MM. В силу особенностей языка XML, некоторые символы в тексте должны быть заменены: & на & < на < > на > " на "
Оформление заказа
Пример оформления заказа
<?xml version="1.0" encoding="UTF-8"?>
<neworder>
<auth extra="8" login="login" pass="pass"></auth>
<order orderno="111111">
<barcode>111111</barcode>
<sender>
<company>МВД</company>
<person>Иванов И.И.</person>
<phone>123-45-67</phone>
<town>Санкт-Петербург</town>
<address>Петровка 38 офис 35</address>
<date>2014-03-22</date>
<time_min>09:00</time_min>
<time_max>14:00</time_max>
</sender>
<receiver>
<company>МВД</company>
<person>Чип & Дейл</person>
<phone>123-45-67</phone>
<zipcode>125480</zipcode>
<town>Санкт-Петербург</town>
<address>Петровка 38 офис 35</address>
<date>2014-03-22</date>
<time_min>09:00</time_min>
<time_max>14:00</time_max>
</receiver>
<weight>5.1</weight>
<quantity>2</quantity>
<paytype>CASH</paytype>
<service>2</service>
<price>387.5</price>
<inshprice>387.5</inshprice>
<enclosure>Детские игрушки</enclosure>
<instruction>Проверить при покупателе, подписать акт</instruction>
<items>
<item quantity="1" mass="0.2" retprice="37.5" barcode="2345625213125" article="1">Мяч</item>
<item quantity="2" mass="2" retprice="100" barcode="4645625213138" article="2">Обруч</item>
<item quantity="3" mass="0.3" retprice="50" barcode="2345625213126" article="3">Погремушка желтая</item>
</items>
</order>
</neworder>
Описание элементов для оформления заказа:
- neworder - Корневой контейнер, обязательный элемент.
- order - Контейнер для описания одного заказа, обязательный элемент.
- orderno - Номер заказа. Если присваивается клиентом - указывается здесь. Если не присваивается - можно оставить пустым, система сгенерирует свой номер, и вернет его в ответе.
- barcode - Штрих-код заказа. В случае, если клиент штрих-кодирует свои отправления, и штрих-код отличается от номера заказа, в этом поле указывается штрих-код. В случае наличия нескольких мест, и раздельной их маркировки, в этом поле допустимы маски в виде символов подчеркивания, говорящие о позициях штрих-кода, переменных для разных мест в рамках одного заказа.
Например: В заказе номер 123 имеется 20 товарных вложений, которые упакованы в 3 транспортных места. Клиент формирует 3 штрих-кода на транспортные места: CLNT0012301, CLNT0012302, CLNT0012303, где CLNT - префикс клиента, 00123 - номер заказа, 01-03 - номер транспортного места в заказе. В поле barcode нужно указать CLNT00123__ (система поймет, что 2 последних символа могут быть любыми, и будут отражать штрих-коды к одному заказу).
- sender - Информация о отправителе заказа. Не обязательный контейнер.
<sender>
<company>Название компании отправителя</company>
<person>Контактное лицо отправителя</person>
<phone>Телефон, Email отправителя</phone>
<town>Город отправителя в формате "Москва город"</town>
<address>Адрес отправителя</address>
<date>Дата забора в формате "YYYY-MM-DD"</date>
<time_min>Желаемое время забора в формате "HH:MM"</time_min>
<time_max>Желаемое время забора в формате "HH:MM"</time_max>
</sender>
- receiver - Информация о получателе заказа. Обязательный контейнер.
<receiver>
<company>Название компании получателя</company>
<person>Контактное лицо получателя</person>
<phone>Телефон, Email получателя</phone>
<town>Город получателя в формате "Москва город"</town>
<address>Адрес получателя</address>
<date>Дата доставки в формате "YYYY-MM-DD"</date>
<time_min>Желаемое время доставки в формате "HH:MM"</time_min>
<time_max>Желаемое время доставки в формате "HH:MM"</time_max>
</receiver>
- company - Компания-получатель. Должно быть заполнено company ИЛИ person!
- person - Контактное лицо. Должно быть заполнено company ИЛИ person!
- phone - Телефон. Можно указывать несколько телефонов, E-mail в этом поле.
- town - Город. В системе города привязываются к справочнику, поэтому город должен иметь правильное полное написание. Так же можно в этом поле указать числовое значение - код населенного пункта из справочника городов. При указании названия возможно появление ошибки, если населенных пунктов с таким названием в справочнике несколько.
- paytype - Тип оплаты заказа получателем. Принимает значения:
CASH | Наличными (по-умолчанию) |
CARD | Картой |
NO | Без оплаты |
OTHER | Прочее (платежные системы и т.д.) |
- zipcode - Почтовый индекс.
- weight - Общий вес заказа.
- quantity - Количество мест.
- service - Режим доставки (тип услуги) передается код из соответствующего справочника.
- price - Сумма заказа. В случае наличия контейнера items значение данного параметра будет проигнорировано, и рассчитано автоматически.
- enclosure - Вложение.
- inshprice - Объявленная ценность.
- instruction - Поручение - Примечание.
items - Контейнер для описания вложенных товаров. Не обязательный контейнер.
- item - Название товара.
- quantity - Количество мест.
- mass - Масса товара. В случае наличия контейнера items значение данного параметра будет проигнорировано, и рассчитано автоматически.
- retprice - Цена товара.
- barcode - Штрих-код товара.
- article - Артикул товара.
Примеры ответов
Пример успешного ответа
<?xml version="1.0" encoding="UTF-8"?>
<neworder>
<createorder orderno="AB23541" error="0" errormsg="success"></createorder>
<createorder orderno="55_6542" error="0" errormsg="success"></createorder>
<createorder orderno="AB23542" error="0" errormsg="success"></createorder>
</neworder>
Пример ответа с ошибкой
<?xml version="1.0" encoding="UTF-8"?>
<neworder>
<createorder orderno="AB23541" error="17" errormsg="Such number exists"></createorder>
<createorder orderno="AB23542" error="13" errormsg="empty company"></createorder>
<createorder orderno="AB23542" error="14" errormsg="empty person"></createorder>
</neworder>
Пример ответа при ошибке авторизации
<?xml version="1.0" encoding="utf-8"?>
<request>
<error error="1" errormsg="authorization error"></error>
</request>
Пример ответа при ошибке синтаксиса
<?xml version="1.0" encoding="UTF-8"?>
<request>
<error>column:1 line:11 message:expected '>'</error>
</request>
Коды ошибок при оформлении заказа
0 - Ошибок нет.
1 - Ошибка авторизации. (отсутствуют теги <auth login="" pass=""></auth>, неверный логин или пароль).
2 - Отправлен пустой запрос (отсутствует контейнер <neworder></neworder> в XML документе).
3 - Некорректно указана сумма заказа.
4 - Некорректный общий вес заказа.
5 - Не найден город получатель.
6 - Не найден город отправитель.
7 - Не заполнен адрес получателя.
8 - Не заполнен телефон получателя.
9 - Не заполнено контактное имя получателя.
10 - Не заполнено название компании получателя.
11 - Некорректная сумма объявленной ценности.
12 - Артикул не найден.
13 - Не заполнено название компании отправителя.
14 - Не заполнено контактное имя отправителя.
15 - Не заполнен телефон отправителя.
16 - Не заполнен адрес отправителя.
17 - Заказ с таким номером уже существует.
Запрос статуса заказов
Пример запроса статуса заказа
<?xml version="1.0" encoding="UTF-8" ?>
<statusreq>
<auth extra="8" login="login" pass="pass"></auth>
<client>CLIENT</client>
<orderno>1234</orderno>
<ordercode>34234</ordercode>
<givencode>234534</givencode>
<datefrom>2014-04-03</datefrom>
<dateto>2014-04-03</dateto>
<done>ONLY_NOT_DONE</done>
<changes>ONLY_LAST</changes>
</statusreq>
Описание полей запроса статуса
statusreq - Корневой контейнер. Обязательный элемент.
- auth - Авторизация. Обязательный элемент.
- orderno - Номер заказа. Не обязательный элемент.
- datefrom - Дата "с". Обязательный элемент.
- dateto - Дата "по". Обязательный элемент.
- done - Может принимать значения:
- Только не доставленные ONLY_NOT_DONE
- Только доставленные ONLY_DONE
- Все пусто
- changes - может принимать значение только ONLY_LAST. Если указан этот параметр, все остальные игнорируются. Описание данного режима приведено здесь: Передача только изменившихся статусов
Примеры ответов
Пример успешного ответа
<?xml version="1.0" encoding="UTF-8"?>
<statusreq count="23">
<order orderno="111111" ordercode="34534234" givencode="2345334">
<barcode>111111</barcode>
<sender>
<company>МВД</company>
<person>Иванов И.И.</person>
<phone>123-45-67</phone>
<contacts>
<phone>+74951234567</phone>
</contacts>
<town code="23432">Санкт-Петербург</town>
<address>Петровка 38 офис 35</address>
<date>2014-03-22</date>
<time_min>09:00</time_min>
<time_max>14:00</time_max>
</sender>
<receiver>
<company>МВД</company>
<person>Иванов И.И.</person>
<phone>123-45-67 - Иван (916)234.45.21 Петр,mvd@mail.ru</phone>
<contacts>
<phone>+74951234567</phone>
<phone>+79162344521</phone>
<email>mvd@mail.ru</email>
</contacts>
<zipcode>125480</zipcode>
<town code="23432">Санкт-Петербург</town>
<address>Петровка 38 офис 35</address>
<date>2014-03-22</date>
<time_min>09:00</time_min>
<time_max>14:00</time_max>
<coords lat="55.680327" lon="37.604456"></coords>
</receiver>
<weight>5.1</weight>
<quantity>2</quantity>
<paytype>CASH</paytype>
<service>2</service>
<price>387.5</price>
<inshprice>387.5</inshprice>
<enclosure>Детские игрушки</enclosure>
<instruction>Проверить при покупателе, подписать акт</instruction>
<currcoords lat="55.680327" lon="37.604456" accuracy="50" RequestDateTime="2014-04-21 18:07:45"></currcoords>
<deliveryprice total="158.6">
<>..</> (price details are not yet supported)
..
</deliveryprice>
<status>DELIVERY</status>
<customstatecode>2<customstatecode>
<deliveredto>Иванова, секр.</deliveredto>
<delivereddate>2014-03-22</delivereddate>
<deliveredtime>12:45</deliveredtime>
<items>
<item code="34533" quantity="1" mass="0.2" retprice="37.5" barcode="2345625213125" article="1" returns="0">Мяч</item>
<item code="34456" quantity="2" mass="2" retprice="100" barcode="4645625213138" article="2" returns="0">Обруч</item>
<item code="34421" quantity="3" mass="0.3" retprice="50" barcode="2345625213126" article="3" returns="0">Погремушка желтая</item>
</items>
</order>
</statusreq>
Пример ответа если нет заказов
<?xml version="1.0" encoding="utf-8"?>
<statusreq count="0">
</statusreq>
Пример ответа при ошибке авторизации
<?xml version="1.0" encoding="utf-8"?>
<request>
<error error="1" errormsg="authorization error"></error>
</request>
Пример ответа при ошибке синтаксиса
<?xml version="1.0" encoding="UTF-8"?>
<request>
<error>column:1 line:11 message:expected '>'</error>
</request>
Описание полей ответа статусов
Все поля ответа соответствуют структуре order при создании заказа, с некоторыми добавлениями:
- атрибут ordercode контейнера order - внутренний код заказа в системе, применяется для некоторых внутренних операций.
- атрибут givencode контейнера order - внутренний код заказа в системе, применяется для некоторых внутренних операций.
- атрибут returns контейнера item - Количество данного товара, от которого отказался получатель. Не нулевое только в случае частичного
отказа.
- атрибут code контейнера item - внутренний код строки заказа в системе, применяется для некоторых внутренних операций.
- coords в контейнере receiver - координаты получателя.
- currcoords - текущие координаты заказа. Атрибуты:
lat - широта lon - долгота accuracy - точность в метрах RequestDateTime - дата/время последнего обновления координат.
- deliveryprice - стоимость доставки в валюте расчетов с клиентом.
- status - статус доставки.
- customstatecode - код статуса клиента. Используется, если клиент предлагает свои коды статусов доставки/причин недоставки.
- deliveredto - Данные о вручении, либо причина недоставки.
- delivereddate - Дата вручения.
- deliveredtime - Время вручения. В случае недоставки может быть пустым.
Статус может принимать следующие значения:
NEW - Новый
ACCEPTED - Получен складом
DELIVERY - Доставляется
COMPLETE - Доставлен
CANCELED - Не доставлен
PARTIALLY - Доставлен частично
Примечание: В будущем планируется расширение используемого набора статусов.
Передача только изменившихся статусов
Для получения только изменившихся статусов отправьте запрос
<?xml version="1.0" encoding="UTF-8" ?>
<statusreq>
<auth login="login" pass="pass"></auth>
<changes>ONLY_LAST</changes>
</statusreq>
Система выдает все заказы, в которых, с момента последнего запроса в этом режиме, изменилось хотя бы одно из полей:
orderno status delivereddate deliveredtime deliveredto receiver->date receiver->address price
После успешной обработки ответа необходимо отметить полученные статусы успешно полученными, отправив запрос
<?xml version="1.0" encoding="UTF-8" ?>
<commitlaststatus>
<auth login="login" pass="pass"></auth>
</commitlaststatus>
В случае успеха Вы получите ответ
<?xml version="1.0" encoding="UTF-8" ?>
<commitlaststatus>
<error error="0" errormsg="OK"></error>
</commitlaststatus>
Данный способ передачи статусов гарантирует полную корректную передачу статусов, даже в случае, если в нашей системе статус изменился в промежутке времени между запросом статусов и подтверждением их получения. Если система не получила подтверждение успешной передачи статуса, она будет считать информацию не переданной, и выдаст ее при повторном запросе.
Внимание! При данном способе передачи система просматривает заказы, оформленные за последние 3 месяца. Если заказ сделан ранее - изменение статуса по нему не попадет в результат выполнения данного запроса.
Внимание! Система всегда выдает текущий статус. Т.е. Вы можете одним запросом получить статус "NEW", а следующим - "COMPLETE". В помежутке между запросами отправление могло пройти через несколько промежуточных статусов.
Внимание! Система не гарантирует последовательность прохождения заказом набора статусов. Т.е. Вы можете получить статус "COMPLETE", а следующим запросом - "NEW" - такое может произойти, например, если оператор ошибочно отметил заказ выполненным, а затем исправил ошибку.
Справочник городов
Пример запроса справочника городов:
<?xml version="1.0" encoding="UTF-8"?>
<townlist>
<codesearch>
<zipcode>110000</zipcode> (not yet supported)
<code>123</code>
</codesearch>
<conditions>
<city>Краснодарский край</city>
<namecontains>новгород</namecontains>
<namestarts>Моск</namestarts>
<name>Москва</name> (not yet supported)
<fullname>Москва город</fullname>
</conditions>
<limit>
<limitfrom>30</limitfrom>
<limitcount>10</limitcount>
<countall>YES</countall>
</limit>
</townlist>
Внутри контейнера townlist все элементы могут как отсутствовать, так и комбинироваться. Поиск не чувствителен к регистру.
- codesearch - Поиск по кодам. В случае использования - контейнеры conditions и limit игнорируются.
zipcode - Поиск по индексу. Система найдет первый населенный пункт, который соответствует указанному индексу. Поскольку один почтовый индекс может распространяться на несколько населенных пунктов - поиск может выдать не тот пункт, который ожидается. Данный параметр может не поддерживаться в конкретной установке системы. code - Поиск по коду в системе.
- conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".
city - Поиск по всем населенным пунктам региона. namecontains - Поиск населенных пунктов, название которых содержит указанный текст. namestarts - Поиск населенных пунктов, название которых начинается с указанного текста. name - Поиск населенных пунктов, название которых соответствует указанному тексту. fullname - Поиск населенных пунктов, название вместе с типом населенного пункта которых соответствует указанному тексту.
- limit - Ограничивает вывод результата.
limitfrom - Задает номер записи результата, начиная с которой выдавать ответ. По-умолчанию - 0. limitcount- Задает количество записей результата, которые нужно вернуть. По-умолчанию - 10000. countall - YES указывает на необходимость подсчета общего количества найденных совпадений. Это может замедлять выполнение запроса. Если отключено - в ответе не указываются totalcount и totalpages.
Пример ответа:
<?xml version="1.0" encoding="UTF-8"?>
<townlist count="3" page="1" totalcount="3" totalpages="1">
<town>
<code>26379</code>
<city>
<code>23</code>
<name>Краснодарский край</name>
</city>
<name>Сочи город</name>
<shortname>Сочи</shortname> (not yet supported)
<typename>город</typename> (not yet supported)
</town>
<town>
<code>40331</code>
<city>
<code>32</code>
<name>Брянская область</name>
</city>
<name>Сочилов хутор</name>
<shortname>Сочилов</shortname>
<typename>хутор</typename>
</town>
<town>
<code>114016</code>
<city>
<code>60</code>
<name>Псковская область</name>
</city>
<name>Сочихино деревня</name>
<shortname>Сочихино</shortname>
<typename>деревня</typename>
</town>
</townlist>
В ответе города сортируются по популярности, важности (районные центры и т.д.), и только затем - по алфавиту.
Справочник регионов
Пример запроса справочника:
<?xml version="1.0" encoding="UTF-8"?>
<regionlist>
<codesearch>
<code>77</code>
</codesearch>
<conditions>
<namecontains>край</namecontains>
<namestarts>Моск</namestarts>
<fullname>Московская область</fullname>
<ourcountry>YES</ourcountry>
</conditions>
</regionlist>
Пример ответа:
<?xml version="1.0" encoding="UTF-8"?>
<regionlist count="99">
<city>
<code>23</code>
<name>Краснодарский край</name>
</city>
<city>
<code>32</code>
<name>Брянская область</name>
</city>
<city>
<code>60</code>
<name>Псковская область</name>
</city>
</regionlist>
Справочник улиц
Пример запроса справочника городов:
<?xml version="1.0" encoding="UTF-8"?>
<streetlist>
<conditions>
<town>Москва город</town>
<namecontains>Хохло</namecontains>
<namestarts>Академика Х</namestarts>
<name>Академика Хохлова</name>
<fullname>Академика Хохлова ул.</fullname>
</conditions>
<limit>
<limitfrom>30</limitfrom>
<limitcount>10</limitcount>
<countall>YES</countall>
</limit>
</streetlist >
- conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".
town - Обязательное поле. Название или код населенного пункта. namecontains - Поиск населенных пунктов, название которых содержит указанный текст. namestarts - Поиск населенных пунктов, название которых начинается с указанного текста. name - Поиск населенных пунктов, название которых соответствует указанному тексту. fullname - Поиск населенных пунктов, название вместе с типом населенного пункта которых соответствует указанному тексту.
- limit - Ограничивает вывод результата.
limitfrom - Задает номер записи результата, начиная с которой выдавать ответ. По-умолчанию - 0. limitcount- Задает количество записей результата, которые нужно вернуть. По-умолчанию - 10000. countall - YES указывает на необходимость подсчета общего количества найденных совпадений. Это может замедлять выполнение запроса. Если отключено - в ответе не указываются totalcount и totalpages.
Пример ответа:
<?xml version="1.0" encoding="UTF-8"?>
<streetlist count="1" page="1" totalcount="3" totalpages="1">
<street>
<name>Академика Хохлова ул.</name>
<shortname>Академика Хохлова</shortname>
<typename>ул.</typename>
</street>
</streetlist>
В ответе улицы сортируются по алфавиту.
Справочник номенклатуры
Пример запроса справочника номенклатуры:
<?xml version="1.0" encoding="UTF-8" ?>
<itemlist>
<auth login="login" pass="pass"></auth>
<codesearch>
<code>123456</code>
<article>FD343</article>
<barcode>2345625213125</barcode>
</codesearch>
<conditions>
<namecontains>телевизор</namecontains>
<namestarts>sony</namestarts>
<name>Sony KDL-55W905 ЖК-телевизор</name>
<quantity>EXISTING_ONLY</quantity>
</conditions>
<limit>
<limitfrom>30</limitfrom>
<limitcount>10</limitcount>
<countall>YES</countall>
</limit>
</itemlist>
Внутри контейнера itemlistвсе элементы могут как отсутствовать, так и комбинироваться. Поиск не чувствителен к регистру.
- codesearch - Поиск по кодам. В случае использования - контейнеры conditions и limit игнорируются.
code - Поиск по внутреннему коду системы. article - Поиск по артикулу. barcode - Поиск по штрих-коду.
- conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".
namecontains - Поиск товаров, название которых содержит указанный текст. namestarts - Поиск товаров, название которых начинается с указанного текста. name - Поиск товаров, название которых соответствует указанному тексту. quantity - Наличие на складе. Принимает значения EXISTING_ONLY - Только в наличии, NOT_EXISTING_ONLY - Только не в наличии, ALL - Все. Это поле может быть недоступным в некоторых установках.
- limit - Ограничивает вывод результата.
limitfrom - Задает номер записи результата, начиная с которой выдавать ответ. limitcount - Задает количество записей результата, которые нужно вернуть.
Пример ответа:
<?xml version="1.0" encoding="UTF-8"?>
<itemlist count="3" totalcount="3" page="1" totalpages="1">
<item>
<code>123456</code>
<article>FD343</article>
<barcode>2345625213125</barcode>
<name>Sony KDL-55W905 ЖК-телевизор</name>
<retprice>65000</retprice>
<weight>5.1</weight>
<length>50</length>
<width>30</width>
<height>40</height>
<CountInPallet>30</CountInPallet>
<HasSerials>1</HasSerials>
<CountryOfOrigin>Малайзия</CountryOfOrigin> (not yer supported)
<Message>Хороший телевизор</Message>
<Message2>Снова хороший телевизор</Message2>
<quantity>12</quantity>
<reserved>3</reserved> (not yet supported)
<item>
...
</itemlist>
Описание полей:
- code - Внутренний идентификатор, присвоенный системой.
- article - Артикул, назначенный клиентом (поставщиком).
- barcode - Штрих-код производителя.
- name - Наименование.
- retprice - Розничная цена по-умолчанию. При оформлении заказа цена используется та, которая указана в заказе.
- weight - Масса в килограммах.
- length - Длина в сантиметрах.
- width - Ширина в сантиметрах.
- height - Высота в сантиметрах.
- CountInPallet - Количество штук в паллете.
- HasSerials - Требует учета серийных номеров. Принимает значения 1 - да, 0 - нет.
- CountryOfOrigin - Наименование страны происхождения на русском языке.
- Message - Комментарий.
- Message2 - Дополнительный комментарий.
- quantity - Количество на складе. Товары, уже собранные в заказы в этом количестве не присутствуют, считаются покинувшими товарный склад. Это поле может быть недоступным в некоторых установках.
- reserved - Количество зарезервированного товара. Может превышать остаток на складе, если покупатели ждут следующей поставки. Это поле может быть недоступным в некоторых установках.
Справочник пунктов самовывоза (not yet supported)
Справочник типов доставки
Пример запроса типов доставки:
<?xml version="1.0" encoding="UTF-8" ?>
<services>
</services>
Пример ответа справочника типов доставки:
<?xml version="1.0" encoding="UTF-8" ?>
<services count="2">
<service>
<code>1</code>
<name>Эконом</name>
</service>
<service>
<code>2</code>
<name>Срочно</name>
</service>
</services>
Расчет стоимости доставки
Пример запроса стоимости доставки:
<?xml version="1.0" encoding="UTF-8" ?>
<calculator>
<auth login="login" pass="pass" />
<calc townfrom="Воронеж город" townto="Москва город" mass="3.7" mode="2" />
</calculator>
Пример ответа стоимости доставки:
<?xml version="1.0" encoding="UTF-8" ?>
<calculator>
<calc townfrom="Воронеж город" townto="Москва город" mass="3.7" price="4080.43"/>
</calculator>