Меасофт - Вклад участника [ru]

API

2014-04-25T14:52:48Z

Wiz: /* Расчет стоимости доставки */

В системе "Курьерская служба 2008" имеется возможность интеграции средствами XML API, по протоколу HTTP POST.

== Общие понятия ==

На стороне курьерской службы имеется веб-сервис. Адрес уточняйте у представителей компании. Авторизационные данные так же уточняйте у представителей компании. Тестовая площадка доступна по адресу http://lk.courierexe.ru/api/ логин test пароль testm
Клиент отправляет запросы к сервису, сервис обрабатывает запросы и возвращает результат выполнения. Все запросы и ответы передаются в формате XML.
Кодировка - UTF-8. Разделитель целой и дробной частей чисел - используется символ точки. Даты представляются в виде YYYY-MM-DD, время - HH:MM.
В силу особенностей языка XML, некоторые символы в тексте должны быть заменены: & на &amp; < на &lt; > на &gt; " на &quot;

== Оформление заказа ==
=== Пример оформления заказа ===

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<neworder>
<auth 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>
</source>

=== Описание элементов для оформления заказа: ===

*'''neworder''' - Корневой контейнер, обязательный элемент.

*'''order''' - Контейнер для описания одного заказа, обязательный элемент.

*'''orderno''' - Номер заказа. Если присваивается клиентом - указывается здесь. Если не присваивается - можно оставить пустым, система сгенерирует свой номер, и вернет его в ответе.

*'''barcode''' - Штрих-код заказа. В случае, если клиент штрих-кодирует свои отправления, и штрих-код отличается от номера заказа, в этом поле указывается штрих-код. В случае наличия нескольких мест, и раздельной их маркировки, в этом поле допустимы маски в виде символов подчеркивания, говорящие о позициях штрих-кода, переменных для разных мест в рамках одного заказа.<br />
''Например'': В заказе номер 123 имеется 20 товарных вложений, которые упакованы в 3 транспортных места. Клиент формирует 3 штрих-кода на транспортные места: CLNT0012301, CLNT0012302, CLNT0012303, где CLNT - префикс клиента, 00123 - номер заказа, 01-03 - номер транспортного места в заказе. В поле barcode нужно указать CLNT00123__ (система поймет, что 2 последних символа могут быть любыми, и будут отражать штрих-коды к одному заказу).

*'''sender''' - Информация о отправителе заказа. Не обязательный контейнер.
<source lang="xml">
<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>
</source>

*'''receiver''' - Информация о получателе заказа. Обязательный контейнер.
<source lang="xml">
<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>
</source>

*'''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''' - Артикул товара.

=== Примеры ответов ===

'''Пример успешного ответа'''

<source lang="xml">
<?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>
</source>

'''Пример ответа с ошибкой'''

<source lang="xml">
<?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>
</source>

'''Пример ответа при ошибке авторизации'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<request>
<error error="1" errormsg="authorization error"></error>
</request>
</source>

'''Пример ответа при ошибке синтаксиса'''

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<request>
<error>column:1 line:11 message:expected '>'</error>
</request>
</source>

=== Коды ошибок при оформлении заказа ===

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 - Заказ с таким номером уже существует.

== Запрос статуса заказов ==

=== Пример запроса статуса заказа ===

<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<statusreq>
<auth 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>
</source>

=== Описание полей запроса статуса ===

'''statusreq''' - Корневой контейнер. Обязательный элемент.
*'''auth''' - Авторизация. Обязательный элемент.
*'''orderno''' - Номер заказа. Не обязательный элемент.
*'''datefrom''' - Дата "с". Обязательный элемент.
*'''dateto''' - Дата "по". Обязательный элемент.
*'''done''' - Может принимать значения:

*Только не доставленные '''ONLY_NOT_DONE'''
*Только доставленные '''ONLY_DONE'''
*Все '''пусто'''

*'''changes''' - может принимать значение только ONLY_LAST. Если указан этот параметр, все остальные игнорируются. Описание данного режима приведено здесь: [[#Передача только изменившихся статусов|Передача только изменившихся статусов]]

=== Примеры ответов ===

'''Пример успешного ответа'''

<source lang="xml">
<?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>
<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</phone>
<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>
</source>

'''Пример ответа если нет заказов'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<statusreq count="0">
</statusreq>
</source>

'''Пример ответа при ошибке авторизации'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<request>
<error error="1" errormsg="authorization error"></error>
</request>
</source>

'''Пример ответа при ошибке синтаксиса'''

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<request>
<error>column:1 line:11 message:expected '>'</error>
</request>
</source>

=== Описание полей ответа статусов ===
Все поля ответа соответствуют структуре 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 - Доставлен частично

''Примечание:'' В будущем планируется расширение используемого набора статусов.

=== Передача только изменившихся статусов ===
Для получения только изменившихся статусов отправьте запрос
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<statusreq>
<auth login="login" pass="pass"></auth>
<changes>ONLY_LAST</changes>
</statusreq>
</source>

Система выдает все заказы, в которых, с момента последнего запроса в этом режиме, изменилось хотя бы одно из полей:
orderno
status
delivereddate
deliveredtime
deliveredto
receiver->date
receiver->address
price

После успешной обработки ответа необходимо отметить полученные статусы успешно полученными, отправив запрос
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<commitlaststatus>
<auth login="login" pass="pass"></auth>
</commitlaststatus>
</source>

В случае успеха Вы получите ответ
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<commitlaststatus>
<error error="0" errormsg="OK"></error>
</commitlaststatus>
</source>

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

''Внимание!'' При данном способе передачи система просматривает заказы, оформленные за последние 3 месяца. Если заказ сделан ранее - изменение статуса по нему не попадет в результат выполнения данного запроса.

''Внимание!'' Система всегда выдает текущий статус. Т.е. Вы можете одним запросом получить статус "NEW", а следующим - "COMPLETE". В помежутке между запросами отправление могло пройти через несколько промежуточных статусов.

''Внимание!'' Система не гарантирует последовательность прохождения заказом набора статусов. Т.е. Вы можете получить статус "COMPLETE", а следующим запросом - "NEW" - такое может произойти, например, если оператор ошибочно отметил заказ выполненным, а затем исправил ошибку.

== Справочник городов ==

'''Пример запроса справочника городов:'''
<source lang="xml">
<?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>
</source>

Внутри контейнера townlist все элементы могут как отсутствовать, так и комбинироваться. Поиск не чувствителен к регистру.
*codesearch - Поиск по кодам. В случае использования - контейнеры conditions и limit игнорируются.
'''zipcode''' - Поиск по индексу. Система найдет первый населенный пункт, который соответствует указанному индексу. Поскольку один почтовый индекс может распространяться на несколько населенных пунктов - поиск может выдать не тот пункт, который ожидается. Данный параметр может не поддерживаться в конкретной установке системы.
'''code''' - Поиск по коду в системе.

*conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".
'''city''' - Поиск по всем населенным пунктам региона.
'''namecontains''' - Поиск населенных пунктов, название которых содержит указанный текст.
'''namestarts''' - Поиск населенных пунктов, название которых начинается с указанного текста.
'''name''' - Поиск населенных пунктов, название которых соответствует указанному тексту.
'''fullname''' - Поиск населенных пунктов, название вместе с типом населенного пункта которых соответствует указанному тексту.

*limit - Ограничивает вывод результата.
'''limitfrom''' - Задает номер записи результата, начиная с которой выдавать ответ. По-умолчанию - 0.
'''limitcount'''- Задает количество записей результата, которые нужно вернуть. По-умолчанию - 10000.
'''countall''' - YES указывает на необходимость подсчета общего количества найденных совпадений. Это может замедлять выполнение запроса. Если отключено - в ответе не указываются totalcount и totalpages.

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

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

== Справочник регионов ==

'''Пример запроса справочника:'''
<source lang="xml">
<?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>
</source>

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

== Справочник улиц ==

'''Пример запроса справочника городов:'''
<source lang="xml">
<?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 >
</source>

*conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".
'''town''' - Обязательное поле. Название или код населенного пункта.
'''namecontains''' - Поиск населенных пунктов, название которых содержит указанный текст.
'''namestarts''' - Поиск населенных пунктов, название которых начинается с указанного текста.
'''name''' - Поиск населенных пунктов, название которых соответствует указанному тексту.
'''fullname''' - Поиск населенных пунктов, название вместе с типом населенного пункта которых соответствует указанному тексту.

*limit - Ограничивает вывод результата.
'''limitfrom''' - Задает номер записи результата, начиная с которой выдавать ответ. По-умолчанию - 0.
'''limitcount'''- Задает количество записей результата, которые нужно вернуть. По-умолчанию - 10000.
'''countall''' - YES указывает на необходимость подсчета общего количества найденных совпадений. Это может замедлять выполнение запроса. Если отключено - в ответе не указываются totalcount и totalpages.

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

В ответе улицы сортируются по алфавиту.

== Справочник номенклатуры ==

'''Пример запроса справочника номенклатуры:'''
<source lang="xml">
<?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>
</source>

Внутри контейнера itemlistвсе элементы могут как отсутствовать, так и комбинироваться. Поиск не чувствителен к регистру.
*codesearch - Поиск по кодам. В случае использования - контейнеры conditions и limit игнорируются.
'''code''' - Поиск по внутреннему коду системы.
'''article''' - Поиск по артикулу.
'''barcode''' - Поиск по штрих-коду.

*conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".
'''namecontains''' - Поиск товаров, название которых содержит указанный текст.
'''namestarts''' - Поиск товаров, название которых начинается с указанного текста.
'''name''' - Поиск товаров, название которых соответствует указанному тексту.
'''quantity''' - Наличие на складе. Принимает значения EXISTING_ONLY - Только в наличии, NOT_EXISTING_ONLY - Только не в наличии, ALL - Все. ''Это поле может быть недоступным в некоторых установках.''

*limit - Ограничивает вывод результата.
'''limitfrom''' - Задает номер записи результата, начиная с которой выдавать ответ.
'''limitcount''' - Задает количество записей результата, которые нужно вернуть.

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

'''Описание полей:'''
*'''code''' - Внутренний идентификатор, присвоенный системой.

*'''article''' - Артикул, назначенный клиентом (поставщиком).

*'''barcode''' - Штрих-код производителя.

*'''name''' - Наименование.

*'''retprice''' - Розничная цена по-умолчанию. При оформлении заказа цена используется та, которая указана в заказе.

*'''weight''' - Масса в килограммах.

*'''length''' - Длина в сантиметрах.

*'''width''' - Ширина в сантиметрах.

*'''height''' - Высота в сантиметрах.

*'''CountInPallet''' - Количество штук в паллете.

*'''HasSerials''' - Требует учета серийных номеров. Принимает значения 1 - да, 0 - нет.

*'''CountryOfOrigin''' - Наименование страны происхождения на русском языке.

*'''Message''' - Комментарий.

*'''Message2''' - Дополнительный комментарий.

*'''quantity''' - Количество на складе. Товары, уже собранные в заказы в этом количестве не присутствуют, считаются покинувшими товарный склад. ''Это поле может быть недоступным в некоторых установках.''

*'''reserved''' - Количество зарезервированного товара. Может превышать остаток на складе, если покупатели ждут следующей поставки. ''Это поле может быть недоступным в некоторых установках.''

== Справочник пунктов самовывоза (not yet supported) ==

== Справочник типов доставки ==

'''Пример запроса типов доставки:'''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<services>
</services>
</source>

'''Пример ответа справочника типов доставки:'''
<source lang="xml">
<?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>
</source>

== Расчет стоимости доставки ==

'''Пример запроса стоимости доставки:'''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<calculator>
<auth login="login" pass="pass" />
<calc townfrom="Воронеж город" townto="Москва город" mass="3.7" mode="2" />
</calculator>
</source>

'''Пример ответа стоимости доставки:'''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<calculator>
<calc townfrom="Воронеж город" townto="Москва город" mass="3.7" price="4080.43"/>
</calculator>
</source>

API

2014-04-25T14:52:21Z

Wiz: /* Расчет стоимости доставки */

В системе "Курьерская служба 2008" имеется возможность интеграции средствами XML API, по протоколу HTTP POST.

== Общие понятия ==

На стороне курьерской службы имеется веб-сервис. Адрес уточняйте у представителей компании. Авторизационные данные так же уточняйте у представителей компании. Тестовая площадка доступна по адресу http://lk.courierexe.ru/api/ логин test пароль testm
Клиент отправляет запросы к сервису, сервис обрабатывает запросы и возвращает результат выполнения. Все запросы и ответы передаются в формате XML.
Кодировка - UTF-8. Разделитель целой и дробной частей чисел - используется символ точки. Даты представляются в виде YYYY-MM-DD, время - HH:MM.
В силу особенностей языка XML, некоторые символы в тексте должны быть заменены: & на &amp; < на &lt; > на &gt; " на &quot;

== Оформление заказа ==
=== Пример оформления заказа ===

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<neworder>
<auth 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>
</source>

=== Описание элементов для оформления заказа: ===

*'''neworder''' - Корневой контейнер, обязательный элемент.

*'''order''' - Контейнер для описания одного заказа, обязательный элемент.

*'''orderno''' - Номер заказа. Если присваивается клиентом - указывается здесь. Если не присваивается - можно оставить пустым, система сгенерирует свой номер, и вернет его в ответе.

*'''barcode''' - Штрих-код заказа. В случае, если клиент штрих-кодирует свои отправления, и штрих-код отличается от номера заказа, в этом поле указывается штрих-код. В случае наличия нескольких мест, и раздельной их маркировки, в этом поле допустимы маски в виде символов подчеркивания, говорящие о позициях штрих-кода, переменных для разных мест в рамках одного заказа.<br />
''Например'': В заказе номер 123 имеется 20 товарных вложений, которые упакованы в 3 транспортных места. Клиент формирует 3 штрих-кода на транспортные места: CLNT0012301, CLNT0012302, CLNT0012303, где CLNT - префикс клиента, 00123 - номер заказа, 01-03 - номер транспортного места в заказе. В поле barcode нужно указать CLNT00123__ (система поймет, что 2 последних символа могут быть любыми, и будут отражать штрих-коды к одному заказу).

*'''sender''' - Информация о отправителе заказа. Не обязательный контейнер.
<source lang="xml">
<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>
</source>

*'''receiver''' - Информация о получателе заказа. Обязательный контейнер.
<source lang="xml">
<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>
</source>

*'''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''' - Артикул товара.

=== Примеры ответов ===

'''Пример успешного ответа'''

<source lang="xml">
<?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>
</source>

'''Пример ответа с ошибкой'''

<source lang="xml">
<?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>
</source>

'''Пример ответа при ошибке авторизации'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<request>
<error error="1" errormsg="authorization error"></error>
</request>
</source>

'''Пример ответа при ошибке синтаксиса'''

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<request>
<error>column:1 line:11 message:expected '>'</error>
</request>
</source>

=== Коды ошибок при оформлении заказа ===

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 - Заказ с таким номером уже существует.

== Запрос статуса заказов ==

=== Пример запроса статуса заказа ===

<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<statusreq>
<auth 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>
</source>

=== Описание полей запроса статуса ===

'''statusreq''' - Корневой контейнер. Обязательный элемент.
*'''auth''' - Авторизация. Обязательный элемент.
*'''orderno''' - Номер заказа. Не обязательный элемент.
*'''datefrom''' - Дата "с". Обязательный элемент.
*'''dateto''' - Дата "по". Обязательный элемент.
*'''done''' - Может принимать значения:

*Только не доставленные '''ONLY_NOT_DONE'''
*Только доставленные '''ONLY_DONE'''
*Все '''пусто'''

*'''changes''' - может принимать значение только ONLY_LAST. Если указан этот параметр, все остальные игнорируются. Описание данного режима приведено здесь: [[#Передача только изменившихся статусов|Передача только изменившихся статусов]]

=== Примеры ответов ===

'''Пример успешного ответа'''

<source lang="xml">
<?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>
<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</phone>
<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>
</source>

'''Пример ответа если нет заказов'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<statusreq count="0">
</statusreq>
</source>

'''Пример ответа при ошибке авторизации'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<request>
<error error="1" errormsg="authorization error"></error>
</request>
</source>

'''Пример ответа при ошибке синтаксиса'''

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<request>
<error>column:1 line:11 message:expected '>'</error>
</request>
</source>

=== Описание полей ответа статусов ===
Все поля ответа соответствуют структуре 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 - Доставлен частично

''Примечание:'' В будущем планируется расширение используемого набора статусов.

=== Передача только изменившихся статусов ===
Для получения только изменившихся статусов отправьте запрос
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<statusreq>
<auth login="login" pass="pass"></auth>
<changes>ONLY_LAST</changes>
</statusreq>
</source>

Система выдает все заказы, в которых, с момента последнего запроса в этом режиме, изменилось хотя бы одно из полей:
orderno
status
delivereddate
deliveredtime
deliveredto
receiver->date
receiver->address
price

После успешной обработки ответа необходимо отметить полученные статусы успешно полученными, отправив запрос
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<commitlaststatus>
<auth login="login" pass="pass"></auth>
</commitlaststatus>
</source>

В случае успеха Вы получите ответ
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<commitlaststatus>
<error error="0" errormsg="OK"></error>
</commitlaststatus>
</source>

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

''Внимание!'' При данном способе передачи система просматривает заказы, оформленные за последние 3 месяца. Если заказ сделан ранее - изменение статуса по нему не попадет в результат выполнения данного запроса.

''Внимание!'' Система всегда выдает текущий статус. Т.е. Вы можете одним запросом получить статус "NEW", а следующим - "COMPLETE". В помежутке между запросами отправление могло пройти через несколько промежуточных статусов.

''Внимание!'' Система не гарантирует последовательность прохождения заказом набора статусов. Т.е. Вы можете получить статус "COMPLETE", а следующим запросом - "NEW" - такое может произойти, например, если оператор ошибочно отметил заказ выполненным, а затем исправил ошибку.

== Справочник городов ==

'''Пример запроса справочника городов:'''
<source lang="xml">
<?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>
</source>

Внутри контейнера townlist все элементы могут как отсутствовать, так и комбинироваться. Поиск не чувствителен к регистру.
*codesearch - Поиск по кодам. В случае использования - контейнеры conditions и limit игнорируются.
'''zipcode''' - Поиск по индексу. Система найдет первый населенный пункт, который соответствует указанному индексу. Поскольку один почтовый индекс может распространяться на несколько населенных пунктов - поиск может выдать не тот пункт, который ожидается. Данный параметр может не поддерживаться в конкретной установке системы.
'''code''' - Поиск по коду в системе.

*conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".
'''city''' - Поиск по всем населенным пунктам региона.
'''namecontains''' - Поиск населенных пунктов, название которых содержит указанный текст.
'''namestarts''' - Поиск населенных пунктов, название которых начинается с указанного текста.
'''name''' - Поиск населенных пунктов, название которых соответствует указанному тексту.
'''fullname''' - Поиск населенных пунктов, название вместе с типом населенного пункта которых соответствует указанному тексту.

*limit - Ограничивает вывод результата.
'''limitfrom''' - Задает номер записи результата, начиная с которой выдавать ответ. По-умолчанию - 0.
'''limitcount'''- Задает количество записей результата, которые нужно вернуть. По-умолчанию - 10000.
'''countall''' - YES указывает на необходимость подсчета общего количества найденных совпадений. Это может замедлять выполнение запроса. Если отключено - в ответе не указываются totalcount и totalpages.

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

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

== Справочник регионов ==

'''Пример запроса справочника:'''
<source lang="xml">
<?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>
</source>

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

== Справочник улиц ==

'''Пример запроса справочника городов:'''
<source lang="xml">
<?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 >
</source>

*conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".
'''town''' - Обязательное поле. Название или код населенного пункта.
'''namecontains''' - Поиск населенных пунктов, название которых содержит указанный текст.
'''namestarts''' - Поиск населенных пунктов, название которых начинается с указанного текста.
'''name''' - Поиск населенных пунктов, название которых соответствует указанному тексту.
'''fullname''' - Поиск населенных пунктов, название вместе с типом населенного пункта которых соответствует указанному тексту.

*limit - Ограничивает вывод результата.
'''limitfrom''' - Задает номер записи результата, начиная с которой выдавать ответ. По-умолчанию - 0.
'''limitcount'''- Задает количество записей результата, которые нужно вернуть. По-умолчанию - 10000.
'''countall''' - YES указывает на необходимость подсчета общего количества найденных совпадений. Это может замедлять выполнение запроса. Если отключено - в ответе не указываются totalcount и totalpages.

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

В ответе улицы сортируются по алфавиту.

== Справочник номенклатуры ==

'''Пример запроса справочника номенклатуры:'''
<source lang="xml">
<?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>
</source>

Внутри контейнера itemlistвсе элементы могут как отсутствовать, так и комбинироваться. Поиск не чувствителен к регистру.
*codesearch - Поиск по кодам. В случае использования - контейнеры conditions и limit игнорируются.
'''code''' - Поиск по внутреннему коду системы.
'''article''' - Поиск по артикулу.
'''barcode''' - Поиск по штрих-коду.

*conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".
'''namecontains''' - Поиск товаров, название которых содержит указанный текст.
'''namestarts''' - Поиск товаров, название которых начинается с указанного текста.
'''name''' - Поиск товаров, название которых соответствует указанному тексту.
'''quantity''' - Наличие на складе. Принимает значения EXISTING_ONLY - Только в наличии, NOT_EXISTING_ONLY - Только не в наличии, ALL - Все. ''Это поле может быть недоступным в некоторых установках.''

*limit - Ограничивает вывод результата.
'''limitfrom''' - Задает номер записи результата, начиная с которой выдавать ответ.
'''limitcount''' - Задает количество записей результата, которые нужно вернуть.

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

'''Описание полей:'''
*'''code''' - Внутренний идентификатор, присвоенный системой.

*'''article''' - Артикул, назначенный клиентом (поставщиком).

*'''barcode''' - Штрих-код производителя.

*'''name''' - Наименование.

*'''retprice''' - Розничная цена по-умолчанию. При оформлении заказа цена используется та, которая указана в заказе.

*'''weight''' - Масса в килограммах.

*'''length''' - Длина в сантиметрах.

*'''width''' - Ширина в сантиметрах.

*'''height''' - Высота в сантиметрах.

*'''CountInPallet''' - Количество штук в паллете.

*'''HasSerials''' - Требует учета серийных номеров. Принимает значения 1 - да, 0 - нет.

*'''CountryOfOrigin''' - Наименование страны происхождения на русском языке.

*'''Message''' - Комментарий.

*'''Message2''' - Дополнительный комментарий.

*'''quantity''' - Количество на складе. Товары, уже собранные в заказы в этом количестве не присутствуют, считаются покинувшими товарный склад. ''Это поле может быть недоступным в некоторых установках.''

*'''reserved''' - Количество зарезервированного товара. Может превышать остаток на складе, если покупатели ждут следующей поставки. ''Это поле может быть недоступным в некоторых установках.''

== Справочник пунктов самовывоза (not yet supported) ==

== Справочник типов доставки ==

'''Пример запроса типов доставки:'''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<services>
</services>
</source>

'''Пример ответа справочника типов доставки:'''
<source lang="xml">
<?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>
</source>

== Расчет стоимости доставки ==

'''Пример запроса стоимости доставки:'''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<calculator>
<auth login="login" pass="pass" />
<calc townfrom="Воронеж город" townto="Москва город" mass="3" mode="2" />
</calculator>
</source>

'''Пример ответа стоимости доставки:'''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<calculator>
<calc townfrom="Воронеж город" townto="Москва город" mass="3.7" price="4080.43"/>
</calculator>
</source>

API

2014-04-25T14:47:52Z

Wiz: /* Расчет стоимости доставки (not yet supported) */

В системе "Курьерская служба 2008" имеется возможность интеграции средствами XML API, по протоколу HTTP POST.

== Общие понятия ==

На стороне курьерской службы имеется веб-сервис. Адрес уточняйте у представителей компании. Авторизационные данные так же уточняйте у представителей компании. Тестовая площадка доступна по адресу http://lk.courierexe.ru/api/ логин test пароль testm
Клиент отправляет запросы к сервису, сервис обрабатывает запросы и возвращает результат выполнения. Все запросы и ответы передаются в формате XML.
Кодировка - UTF-8. Разделитель целой и дробной частей чисел - используется символ точки. Даты представляются в виде YYYY-MM-DD, время - HH:MM.
В силу особенностей языка XML, некоторые символы в тексте должны быть заменены: & на &amp; < на &lt; > на &gt; " на &quot;

== Оформление заказа ==
=== Пример оформления заказа ===

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<neworder>
<auth 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>
</source>

=== Описание элементов для оформления заказа: ===

*'''neworder''' - Корневой контейнер, обязательный элемент.

*'''order''' - Контейнер для описания одного заказа, обязательный элемент.

*'''orderno''' - Номер заказа. Если присваивается клиентом - указывается здесь. Если не присваивается - можно оставить пустым, система сгенерирует свой номер, и вернет его в ответе.

*'''barcode''' - Штрих-код заказа. В случае, если клиент штрих-кодирует свои отправления, и штрих-код отличается от номера заказа, в этом поле указывается штрих-код. В случае наличия нескольких мест, и раздельной их маркировки, в этом поле допустимы маски в виде символов подчеркивания, говорящие о позициях штрих-кода, переменных для разных мест в рамках одного заказа.<br />
''Например'': В заказе номер 123 имеется 20 товарных вложений, которые упакованы в 3 транспортных места. Клиент формирует 3 штрих-кода на транспортные места: CLNT0012301, CLNT0012302, CLNT0012303, где CLNT - префикс клиента, 00123 - номер заказа, 01-03 - номер транспортного места в заказе. В поле barcode нужно указать CLNT00123__ (система поймет, что 2 последних символа могут быть любыми, и будут отражать штрих-коды к одному заказу).

*'''sender''' - Информация о отправителе заказа. Не обязательный контейнер.
<source lang="xml">
<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>
</source>

*'''receiver''' - Информация о получателе заказа. Обязательный контейнер.
<source lang="xml">
<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>
</source>

*'''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''' - Артикул товара.

=== Примеры ответов ===

'''Пример успешного ответа'''

<source lang="xml">
<?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>
</source>

'''Пример ответа с ошибкой'''

<source lang="xml">
<?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>
</source>

'''Пример ответа при ошибке авторизации'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<request>
<error error="1" errormsg="authorization error"></error>
</request>
</source>

'''Пример ответа при ошибке синтаксиса'''

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<request>
<error>column:1 line:11 message:expected '>'</error>
</request>
</source>

=== Коды ошибок при оформлении заказа ===

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 - Заказ с таким номером уже существует.

== Запрос статуса заказов ==

=== Пример запроса статуса заказа ===

<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<statusreq>
<auth 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>
</source>

=== Описание полей запроса статуса ===

'''statusreq''' - Корневой контейнер. Обязательный элемент.
*'''auth''' - Авторизация. Обязательный элемент.
*'''orderno''' - Номер заказа. Не обязательный элемент.
*'''datefrom''' - Дата "с". Обязательный элемент.
*'''dateto''' - Дата "по". Обязательный элемент.
*'''done''' - Может принимать значения:

*Только не доставленные '''ONLY_NOT_DONE'''
*Только доставленные '''ONLY_DONE'''
*Все '''пусто'''

*'''changes''' - может принимать значение только ONLY_LAST. Если указан этот параметр, все остальные игнорируются. Описание данного режима приведено здесь: [[#Передача только изменившихся статусов|Передача только изменившихся статусов]]

=== Примеры ответов ===

'''Пример успешного ответа'''

<source lang="xml">
<?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>
<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</phone>
<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>
</source>

'''Пример ответа если нет заказов'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<statusreq count="0">
</statusreq>
</source>

'''Пример ответа при ошибке авторизации'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<request>
<error error="1" errormsg="authorization error"></error>
</request>
</source>

'''Пример ответа при ошибке синтаксиса'''

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<request>
<error>column:1 line:11 message:expected '>'</error>
</request>
</source>

=== Описание полей ответа статусов ===
Все поля ответа соответствуют структуре 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 - Доставлен частично

''Примечание:'' В будущем планируется расширение используемого набора статусов.

=== Передача только изменившихся статусов ===
Для получения только изменившихся статусов отправьте запрос
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<statusreq>
<auth login="login" pass="pass"></auth>
<changes>ONLY_LAST</changes>
</statusreq>
</source>

Система выдает все заказы, в которых, с момента последнего запроса в этом режиме, изменилось хотя бы одно из полей:
orderno
status
delivereddate
deliveredtime
deliveredto
receiver->date
receiver->address
price

После успешной обработки ответа необходимо отметить полученные статусы успешно полученными, отправив запрос
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<commitlaststatus>
<auth login="login" pass="pass"></auth>
</commitlaststatus>
</source>

В случае успеха Вы получите ответ
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<commitlaststatus>
<error error="0" errormsg="OK"></error>
</commitlaststatus>
</source>

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

''Внимание!'' При данном способе передачи система просматривает заказы, оформленные за последние 3 месяца. Если заказ сделан ранее - изменение статуса по нему не попадет в результат выполнения данного запроса.

''Внимание!'' Система всегда выдает текущий статус. Т.е. Вы можете одним запросом получить статус "NEW", а следующим - "COMPLETE". В помежутке между запросами отправление могло пройти через несколько промежуточных статусов.

''Внимание!'' Система не гарантирует последовательность прохождения заказом набора статусов. Т.е. Вы можете получить статус "COMPLETE", а следующим запросом - "NEW" - такое может произойти, например, если оператор ошибочно отметил заказ выполненным, а затем исправил ошибку.

== Справочник городов ==

'''Пример запроса справочника городов:'''
<source lang="xml">
<?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>
</source>

Внутри контейнера townlist все элементы могут как отсутствовать, так и комбинироваться. Поиск не чувствителен к регистру.
*codesearch - Поиск по кодам. В случае использования - контейнеры conditions и limit игнорируются.
'''zipcode''' - Поиск по индексу. Система найдет первый населенный пункт, который соответствует указанному индексу. Поскольку один почтовый индекс может распространяться на несколько населенных пунктов - поиск может выдать не тот пункт, который ожидается. Данный параметр может не поддерживаться в конкретной установке системы.
'''code''' - Поиск по коду в системе.

*conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".
'''city''' - Поиск по всем населенным пунктам региона.
'''namecontains''' - Поиск населенных пунктов, название которых содержит указанный текст.
'''namestarts''' - Поиск населенных пунктов, название которых начинается с указанного текста.
'''name''' - Поиск населенных пунктов, название которых соответствует указанному тексту.
'''fullname''' - Поиск населенных пунктов, название вместе с типом населенного пункта которых соответствует указанному тексту.

*limit - Ограничивает вывод результата.
'''limitfrom''' - Задает номер записи результата, начиная с которой выдавать ответ. По-умолчанию - 0.
'''limitcount'''- Задает количество записей результата, которые нужно вернуть. По-умолчанию - 10000.
'''countall''' - YES указывает на необходимость подсчета общего количества найденных совпадений. Это может замедлять выполнение запроса. Если отключено - в ответе не указываются totalcount и totalpages.

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

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

== Справочник регионов ==

'''Пример запроса справочника:'''
<source lang="xml">
<?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>
</source>

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

== Справочник улиц ==

'''Пример запроса справочника городов:'''
<source lang="xml">
<?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 >
</source>

*conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".
'''town''' - Обязательное поле. Название или код населенного пункта.
'''namecontains''' - Поиск населенных пунктов, название которых содержит указанный текст.
'''namestarts''' - Поиск населенных пунктов, название которых начинается с указанного текста.
'''name''' - Поиск населенных пунктов, название которых соответствует указанному тексту.
'''fullname''' - Поиск населенных пунктов, название вместе с типом населенного пункта которых соответствует указанному тексту.

*limit - Ограничивает вывод результата.
'''limitfrom''' - Задает номер записи результата, начиная с которой выдавать ответ. По-умолчанию - 0.
'''limitcount'''- Задает количество записей результата, которые нужно вернуть. По-умолчанию - 10000.
'''countall''' - YES указывает на необходимость подсчета общего количества найденных совпадений. Это может замедлять выполнение запроса. Если отключено - в ответе не указываются totalcount и totalpages.

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

В ответе улицы сортируются по алфавиту.

== Справочник номенклатуры ==

'''Пример запроса справочника номенклатуры:'''
<source lang="xml">
<?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>
</source>

Внутри контейнера itemlistвсе элементы могут как отсутствовать, так и комбинироваться. Поиск не чувствителен к регистру.
*codesearch - Поиск по кодам. В случае использования - контейнеры conditions и limit игнорируются.
'''code''' - Поиск по внутреннему коду системы.
'''article''' - Поиск по артикулу.
'''barcode''' - Поиск по штрих-коду.

*conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".
'''namecontains''' - Поиск товаров, название которых содержит указанный текст.
'''namestarts''' - Поиск товаров, название которых начинается с указанного текста.
'''name''' - Поиск товаров, название которых соответствует указанному тексту.
'''quantity''' - Наличие на складе. Принимает значения EXISTING_ONLY - Только в наличии, NOT_EXISTING_ONLY - Только не в наличии, ALL - Все. ''Это поле может быть недоступным в некоторых установках.''

*limit - Ограничивает вывод результата.
'''limitfrom''' - Задает номер записи результата, начиная с которой выдавать ответ.
'''limitcount''' - Задает количество записей результата, которые нужно вернуть.

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

'''Описание полей:'''
*'''code''' - Внутренний идентификатор, присвоенный системой.

*'''article''' - Артикул, назначенный клиентом (поставщиком).

*'''barcode''' - Штрих-код производителя.

*'''name''' - Наименование.

*'''retprice''' - Розничная цена по-умолчанию. При оформлении заказа цена используется та, которая указана в заказе.

*'''weight''' - Масса в килограммах.

*'''length''' - Длина в сантиметрах.

*'''width''' - Ширина в сантиметрах.

*'''height''' - Высота в сантиметрах.

*'''CountInPallet''' - Количество штук в паллете.

*'''HasSerials''' - Требует учета серийных номеров. Принимает значения 1 - да, 0 - нет.

*'''CountryOfOrigin''' - Наименование страны происхождения на русском языке.

*'''Message''' - Комментарий.

*'''Message2''' - Дополнительный комментарий.

*'''quantity''' - Количество на складе. Товары, уже собранные в заказы в этом количестве не присутствуют, считаются покинувшими товарный склад. ''Это поле может быть недоступным в некоторых установках.''

*'''reserved''' - Количество зарезервированного товара. Может превышать остаток на складе, если покупатели ждут следующей поставки. ''Это поле может быть недоступным в некоторых установках.''

== Справочник пунктов самовывоза (not yet supported) ==

== Справочник типов доставки ==

'''Пример запроса типов доставки:'''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<services>
</services>
</source>

'''Пример ответа справочника типов доставки:'''
<source lang="xml">
<?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>
</source>

== Расчет стоимости доставки ==

'''Пример запроса стоимости доставки:'''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<calculator>
<auth login="login" pass="pass" />
<calc townfrom="Воронеж город" townto="Москва город" mass="3" mode="2" />
</calculator>
</source>

'''Пример ответа стоимости доставки:'''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<calculator>
<calc townfrom="Воронеж город" townto="Москва город" mass="3" price="3255.14"/>
</calculator>
</source>

API

2014-04-25T14:38:02Z

Wiz: /* Расчет стоимости доставки (not yet supported) */

В системе "Курьерская служба 2008" имеется возможность интеграции средствами XML API, по протоколу HTTP POST.

== Общие понятия ==

На стороне курьерской службы имеется веб-сервис. Адрес уточняйте у представителей компании. Авторизационные данные так же уточняйте у представителей компании. Тестовая площадка доступна по адресу http://lk.courierexe.ru/api/ логин test пароль testm
Клиент отправляет запросы к сервису, сервис обрабатывает запросы и возвращает результат выполнения. Все запросы и ответы передаются в формате XML.
Кодировка - UTF-8. Разделитель целой и дробной частей чисел - используется символ точки. Даты представляются в виде YYYY-MM-DD, время - HH:MM.
В силу особенностей языка XML, некоторые символы в тексте должны быть заменены: & на &amp; < на &lt; > на &gt; " на &quot;

== Оформление заказа ==
=== Пример оформления заказа ===

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<neworder>
<auth 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>
</source>

=== Описание элементов для оформления заказа: ===

*'''neworder''' - Корневой контейнер, обязательный элемент.

*'''order''' - Контейнер для описания одного заказа, обязательный элемент.

*'''orderno''' - Номер заказа. Если присваивается клиентом - указывается здесь. Если не присваивается - можно оставить пустым, система сгенерирует свой номер, и вернет его в ответе.

*'''barcode''' - Штрих-код заказа. В случае, если клиент штрих-кодирует свои отправления, и штрих-код отличается от номера заказа, в этом поле указывается штрих-код. В случае наличия нескольких мест, и раздельной их маркировки, в этом поле допустимы маски в виде символов подчеркивания, говорящие о позициях штрих-кода, переменных для разных мест в рамках одного заказа.<br />
''Например'': В заказе номер 123 имеется 20 товарных вложений, которые упакованы в 3 транспортных места. Клиент формирует 3 штрих-кода на транспортные места: CLNT0012301, CLNT0012302, CLNT0012303, где CLNT - префикс клиента, 00123 - номер заказа, 01-03 - номер транспортного места в заказе. В поле barcode нужно указать CLNT00123__ (система поймет, что 2 последних символа могут быть любыми, и будут отражать штрих-коды к одному заказу).

*'''sender''' - Информация о отправителе заказа. Не обязательный контейнер.
<source lang="xml">
<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>
</source>

*'''receiver''' - Информация о получателе заказа. Обязательный контейнер.
<source lang="xml">
<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>
</source>

*'''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''' - Артикул товара.

=== Примеры ответов ===

'''Пример успешного ответа'''

<source lang="xml">
<?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>
</source>

'''Пример ответа с ошибкой'''

<source lang="xml">
<?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>
</source>

'''Пример ответа при ошибке авторизации'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<request>
<error error="1" errormsg="authorization error"></error>
</request>
</source>

'''Пример ответа при ошибке синтаксиса'''

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<request>
<error>column:1 line:11 message:expected '>'</error>
</request>
</source>

=== Коды ошибок при оформлении заказа ===

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 - Заказ с таким номером уже существует.

== Запрос статуса заказов ==

=== Пример запроса статуса заказа ===

<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<statusreq>
<auth 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>
</source>

=== Описание полей запроса статуса ===

'''statusreq''' - Корневой контейнер. Обязательный элемент.
*'''auth''' - Авторизация. Обязательный элемент.
*'''orderno''' - Номер заказа. Не обязательный элемент.
*'''datefrom''' - Дата "с". Обязательный элемент.
*'''dateto''' - Дата "по". Обязательный элемент.
*'''done''' - Может принимать значения:

*Только не доставленные '''ONLY_NOT_DONE'''
*Только доставленные '''ONLY_DONE'''
*Все '''пусто'''

*'''changes''' - может принимать значение только ONLY_LAST. Если указан этот параметр, все остальные игнорируются. Описание данного режима приведено здесь: [[#Передача только изменившихся статусов|Передача только изменившихся статусов]]

=== Примеры ответов ===

'''Пример успешного ответа'''

<source lang="xml">
<?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>
<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</phone>
<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>
</source>

'''Пример ответа если нет заказов'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<statusreq count="0">
</statusreq>
</source>

'''Пример ответа при ошибке авторизации'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<request>
<error error="1" errormsg="authorization error"></error>
</request>
</source>

'''Пример ответа при ошибке синтаксиса'''

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<request>
<error>column:1 line:11 message:expected '>'</error>
</request>
</source>

=== Описание полей ответа статусов ===
Все поля ответа соответствуют структуре 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 - Доставлен частично

''Примечание:'' В будущем планируется расширение используемого набора статусов.

=== Передача только изменившихся статусов ===
Для получения только изменившихся статусов отправьте запрос
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<statusreq>
<auth login="login" pass="pass"></auth>
<changes>ONLY_LAST</changes>
</statusreq>
</source>

Система выдает все заказы, в которых, с момента последнего запроса в этом режиме, изменилось хотя бы одно из полей:
orderno
status
delivereddate
deliveredtime
deliveredto
receiver->date
receiver->address
price

После успешной обработки ответа необходимо отметить полученные статусы успешно полученными, отправив запрос
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<commitlaststatus>
<auth login="login" pass="pass"></auth>
</commitlaststatus>
</source>

В случае успеха Вы получите ответ
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<commitlaststatus>
<error error="0" errormsg="OK"></error>
</commitlaststatus>
</source>

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

''Внимание!'' При данном способе передачи система просматривает заказы, оформленные за последние 3 месяца. Если заказ сделан ранее - изменение статуса по нему не попадет в результат выполнения данного запроса.

''Внимание!'' Система всегда выдает текущий статус. Т.е. Вы можете одним запросом получить статус "NEW", а следующим - "COMPLETE". В помежутке между запросами отправление могло пройти через несколько промежуточных статусов.

''Внимание!'' Система не гарантирует последовательность прохождения заказом набора статусов. Т.е. Вы можете получить статус "COMPLETE", а следующим запросом - "NEW" - такое может произойти, например, если оператор ошибочно отметил заказ выполненным, а затем исправил ошибку.

== Справочник городов ==

'''Пример запроса справочника городов:'''
<source lang="xml">
<?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>
</source>

Внутри контейнера townlist все элементы могут как отсутствовать, так и комбинироваться. Поиск не чувствителен к регистру.
*codesearch - Поиск по кодам. В случае использования - контейнеры conditions и limit игнорируются.
'''zipcode''' - Поиск по индексу. Система найдет первый населенный пункт, который соответствует указанному индексу. Поскольку один почтовый индекс может распространяться на несколько населенных пунктов - поиск может выдать не тот пункт, который ожидается. Данный параметр может не поддерживаться в конкретной установке системы.
'''code''' - Поиск по коду в системе.

*conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".
'''city''' - Поиск по всем населенным пунктам региона.
'''namecontains''' - Поиск населенных пунктов, название которых содержит указанный текст.
'''namestarts''' - Поиск населенных пунктов, название которых начинается с указанного текста.
'''name''' - Поиск населенных пунктов, название которых соответствует указанному тексту.
'''fullname''' - Поиск населенных пунктов, название вместе с типом населенного пункта которых соответствует указанному тексту.

*limit - Ограничивает вывод результата.
'''limitfrom''' - Задает номер записи результата, начиная с которой выдавать ответ. По-умолчанию - 0.
'''limitcount'''- Задает количество записей результата, которые нужно вернуть. По-умолчанию - 10000.
'''countall''' - YES указывает на необходимость подсчета общего количества найденных совпадений. Это может замедлять выполнение запроса. Если отключено - в ответе не указываются totalcount и totalpages.

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

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

== Справочник регионов ==

'''Пример запроса справочника:'''
<source lang="xml">
<?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>
</source>

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

== Справочник улиц ==

'''Пример запроса справочника городов:'''
<source lang="xml">
<?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 >
</source>

*conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".
'''town''' - Обязательное поле. Название или код населенного пункта.
'''namecontains''' - Поиск населенных пунктов, название которых содержит указанный текст.
'''namestarts''' - Поиск населенных пунктов, название которых начинается с указанного текста.
'''name''' - Поиск населенных пунктов, название которых соответствует указанному тексту.
'''fullname''' - Поиск населенных пунктов, название вместе с типом населенного пункта которых соответствует указанному тексту.

*limit - Ограничивает вывод результата.
'''limitfrom''' - Задает номер записи результата, начиная с которой выдавать ответ. По-умолчанию - 0.
'''limitcount'''- Задает количество записей результата, которые нужно вернуть. По-умолчанию - 10000.
'''countall''' - YES указывает на необходимость подсчета общего количества найденных совпадений. Это может замедлять выполнение запроса. Если отключено - в ответе не указываются totalcount и totalpages.

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

В ответе улицы сортируются по алфавиту.

== Справочник номенклатуры ==

'''Пример запроса справочника номенклатуры:'''
<source lang="xml">
<?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>
</source>

Внутри контейнера itemlistвсе элементы могут как отсутствовать, так и комбинироваться. Поиск не чувствителен к регистру.
*codesearch - Поиск по кодам. В случае использования - контейнеры conditions и limit игнорируются.
'''code''' - Поиск по внутреннему коду системы.
'''article''' - Поиск по артикулу.
'''barcode''' - Поиск по штрих-коду.

*conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".
'''namecontains''' - Поиск товаров, название которых содержит указанный текст.
'''namestarts''' - Поиск товаров, название которых начинается с указанного текста.
'''name''' - Поиск товаров, название которых соответствует указанному тексту.
'''quantity''' - Наличие на складе. Принимает значения EXISTING_ONLY - Только в наличии, NOT_EXISTING_ONLY - Только не в наличии, ALL - Все. ''Это поле может быть недоступным в некоторых установках.''

*limit - Ограничивает вывод результата.
'''limitfrom''' - Задает номер записи результата, начиная с которой выдавать ответ.
'''limitcount''' - Задает количество записей результата, которые нужно вернуть.

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

'''Описание полей:'''
*'''code''' - Внутренний идентификатор, присвоенный системой.

*'''article''' - Артикул, назначенный клиентом (поставщиком).

*'''barcode''' - Штрих-код производителя.

*'''name''' - Наименование.

*'''retprice''' - Розничная цена по-умолчанию. При оформлении заказа цена используется та, которая указана в заказе.

*'''weight''' - Масса в килограммах.

*'''length''' - Длина в сантиметрах.

*'''width''' - Ширина в сантиметрах.

*'''height''' - Высота в сантиметрах.

*'''CountInPallet''' - Количество штук в паллете.

*'''HasSerials''' - Требует учета серийных номеров. Принимает значения 1 - да, 0 - нет.

*'''CountryOfOrigin''' - Наименование страны происхождения на русском языке.

*'''Message''' - Комментарий.

*'''Message2''' - Дополнительный комментарий.

*'''quantity''' - Количество на складе. Товары, уже собранные в заказы в этом количестве не присутствуют, считаются покинувшими товарный склад. ''Это поле может быть недоступным в некоторых установках.''

*'''reserved''' - Количество зарезервированного товара. Может превышать остаток на складе, если покупатели ждут следующей поставки. ''Это поле может быть недоступным в некоторых установках.''

== Справочник пунктов самовывоза (not yet supported) ==

== Справочник типов доставки ==

'''Пример запроса типов доставки:'''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<services>
</services>
</source>

'''Пример ответа справочника типов доставки:'''
<source lang="xml">
<?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>
</source>

== Расчет стоимости доставки (not yet supported) ==

'''Пример запроса стоимости доставки:'''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<calculator>
<auth login="login" pass="pass" />
<calc townfrom="Воронеж город" townto="Москва город" mass="3" mode="2" />
</calculator>
</source>

'''Пример ответа стоимости доставки:'''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<calculator>
<calc townfrom="Воронеж город" townto="Москва город" mass="3" price="3255.14"/>
</calculator>
</source>

API

2014-04-25T14:36:41Z

Wiz: /* Расчет стоимости доставки (not yet supported) */

В системе "Курьерская служба 2008" имеется возможность интеграции средствами XML API, по протоколу HTTP POST.

== Общие понятия ==

На стороне курьерской службы имеется веб-сервис. Адрес уточняйте у представителей компании. Авторизационные данные так же уточняйте у представителей компании. Тестовая площадка доступна по адресу http://lk.courierexe.ru/api/ логин test пароль testm
Клиент отправляет запросы к сервису, сервис обрабатывает запросы и возвращает результат выполнения. Все запросы и ответы передаются в формате XML.
Кодировка - UTF-8. Разделитель целой и дробной частей чисел - используется символ точки. Даты представляются в виде YYYY-MM-DD, время - HH:MM.
В силу особенностей языка XML, некоторые символы в тексте должны быть заменены: & на &amp; < на &lt; > на &gt; " на &quot;

== Оформление заказа ==
=== Пример оформления заказа ===

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<neworder>
<auth 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>
</source>

=== Описание элементов для оформления заказа: ===

*'''neworder''' - Корневой контейнер, обязательный элемент.

*'''order''' - Контейнер для описания одного заказа, обязательный элемент.

*'''orderno''' - Номер заказа. Если присваивается клиентом - указывается здесь. Если не присваивается - можно оставить пустым, система сгенерирует свой номер, и вернет его в ответе.

*'''barcode''' - Штрих-код заказа. В случае, если клиент штрих-кодирует свои отправления, и штрих-код отличается от номера заказа, в этом поле указывается штрих-код. В случае наличия нескольких мест, и раздельной их маркировки, в этом поле допустимы маски в виде символов подчеркивания, говорящие о позициях штрих-кода, переменных для разных мест в рамках одного заказа.<br />
''Например'': В заказе номер 123 имеется 20 товарных вложений, которые упакованы в 3 транспортных места. Клиент формирует 3 штрих-кода на транспортные места: CLNT0012301, CLNT0012302, CLNT0012303, где CLNT - префикс клиента, 00123 - номер заказа, 01-03 - номер транспортного места в заказе. В поле barcode нужно указать CLNT00123__ (система поймет, что 2 последних символа могут быть любыми, и будут отражать штрих-коды к одному заказу).

*'''sender''' - Информация о отправителе заказа. Не обязательный контейнер.
<source lang="xml">
<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>
</source>

*'''receiver''' - Информация о получателе заказа. Обязательный контейнер.
<source lang="xml">
<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>
</source>

*'''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''' - Артикул товара.

=== Примеры ответов ===

'''Пример успешного ответа'''

<source lang="xml">
<?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>
</source>

'''Пример ответа с ошибкой'''

<source lang="xml">
<?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>
</source>

'''Пример ответа при ошибке авторизации'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<request>
<error error="1" errormsg="authorization error"></error>
</request>
</source>

'''Пример ответа при ошибке синтаксиса'''

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<request>
<error>column:1 line:11 message:expected '>'</error>
</request>
</source>

=== Коды ошибок при оформлении заказа ===

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 - Заказ с таким номером уже существует.

== Запрос статуса заказов ==

=== Пример запроса статуса заказа ===

<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<statusreq>
<auth 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>
</source>

=== Описание полей запроса статуса ===

'''statusreq''' - Корневой контейнер. Обязательный элемент.
*'''auth''' - Авторизация. Обязательный элемент.
*'''orderno''' - Номер заказа. Не обязательный элемент.
*'''datefrom''' - Дата "с". Обязательный элемент.
*'''dateto''' - Дата "по". Обязательный элемент.
*'''done''' - Может принимать значения:

*Только не доставленные '''ONLY_NOT_DONE'''
*Только доставленные '''ONLY_DONE'''
*Все '''пусто'''

*'''changes''' - может принимать значение только ONLY_LAST. Если указан этот параметр, все остальные игнорируются. Описание данного режима приведено здесь: [[#Передача только изменившихся статусов|Передача только изменившихся статусов]]

=== Примеры ответов ===

'''Пример успешного ответа'''

<source lang="xml">
<?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>
<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</phone>
<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>
</source>

'''Пример ответа если нет заказов'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<statusreq count="0">
</statusreq>
</source>

'''Пример ответа при ошибке авторизации'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<request>
<error error="1" errormsg="authorization error"></error>
</request>
</source>

'''Пример ответа при ошибке синтаксиса'''

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<request>
<error>column:1 line:11 message:expected '>'</error>
</request>
</source>

=== Описание полей ответа статусов ===
Все поля ответа соответствуют структуре 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 - Доставлен частично

''Примечание:'' В будущем планируется расширение используемого набора статусов.

=== Передача только изменившихся статусов ===
Для получения только изменившихся статусов отправьте запрос
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<statusreq>
<auth login="login" pass="pass"></auth>
<changes>ONLY_LAST</changes>
</statusreq>
</source>

Система выдает все заказы, в которых, с момента последнего запроса в этом режиме, изменилось хотя бы одно из полей:
orderno
status
delivereddate
deliveredtime
deliveredto
receiver->date
receiver->address
price

После успешной обработки ответа необходимо отметить полученные статусы успешно полученными, отправив запрос
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<commitlaststatus>
<auth login="login" pass="pass"></auth>
</commitlaststatus>
</source>

В случае успеха Вы получите ответ
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<commitlaststatus>
<error error="0" errormsg="OK"></error>
</commitlaststatus>
</source>

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

''Внимание!'' При данном способе передачи система просматривает заказы, оформленные за последние 3 месяца. Если заказ сделан ранее - изменение статуса по нему не попадет в результат выполнения данного запроса.

''Внимание!'' Система всегда выдает текущий статус. Т.е. Вы можете одним запросом получить статус "NEW", а следующим - "COMPLETE". В помежутке между запросами отправление могло пройти через несколько промежуточных статусов.

''Внимание!'' Система не гарантирует последовательность прохождения заказом набора статусов. Т.е. Вы можете получить статус "COMPLETE", а следующим запросом - "NEW" - такое может произойти, например, если оператор ошибочно отметил заказ выполненным, а затем исправил ошибку.

== Справочник городов ==

'''Пример запроса справочника городов:'''
<source lang="xml">
<?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>
</source>

Внутри контейнера townlist все элементы могут как отсутствовать, так и комбинироваться. Поиск не чувствителен к регистру.
*codesearch - Поиск по кодам. В случае использования - контейнеры conditions и limit игнорируются.
'''zipcode''' - Поиск по индексу. Система найдет первый населенный пункт, который соответствует указанному индексу. Поскольку один почтовый индекс может распространяться на несколько населенных пунктов - поиск может выдать не тот пункт, который ожидается. Данный параметр может не поддерживаться в конкретной установке системы.
'''code''' - Поиск по коду в системе.

*conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".
'''city''' - Поиск по всем населенным пунктам региона.
'''namecontains''' - Поиск населенных пунктов, название которых содержит указанный текст.
'''namestarts''' - Поиск населенных пунктов, название которых начинается с указанного текста.
'''name''' - Поиск населенных пунктов, название которых соответствует указанному тексту.
'''fullname''' - Поиск населенных пунктов, название вместе с типом населенного пункта которых соответствует указанному тексту.

*limit - Ограничивает вывод результата.
'''limitfrom''' - Задает номер записи результата, начиная с которой выдавать ответ. По-умолчанию - 0.
'''limitcount'''- Задает количество записей результата, которые нужно вернуть. По-умолчанию - 10000.
'''countall''' - YES указывает на необходимость подсчета общего количества найденных совпадений. Это может замедлять выполнение запроса. Если отключено - в ответе не указываются totalcount и totalpages.

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

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

== Справочник регионов ==

'''Пример запроса справочника:'''
<source lang="xml">
<?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>
</source>

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

== Справочник улиц ==

'''Пример запроса справочника городов:'''
<source lang="xml">
<?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 >
</source>

*conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".
'''town''' - Обязательное поле. Название или код населенного пункта.
'''namecontains''' - Поиск населенных пунктов, название которых содержит указанный текст.
'''namestarts''' - Поиск населенных пунктов, название которых начинается с указанного текста.
'''name''' - Поиск населенных пунктов, название которых соответствует указанному тексту.
'''fullname''' - Поиск населенных пунктов, название вместе с типом населенного пункта которых соответствует указанному тексту.

*limit - Ограничивает вывод результата.
'''limitfrom''' - Задает номер записи результата, начиная с которой выдавать ответ. По-умолчанию - 0.
'''limitcount'''- Задает количество записей результата, которые нужно вернуть. По-умолчанию - 10000.
'''countall''' - YES указывает на необходимость подсчета общего количества найденных совпадений. Это может замедлять выполнение запроса. Если отключено - в ответе не указываются totalcount и totalpages.

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

В ответе улицы сортируются по алфавиту.

== Справочник номенклатуры ==

'''Пример запроса справочника номенклатуры:'''
<source lang="xml">
<?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>
</source>

Внутри контейнера itemlistвсе элементы могут как отсутствовать, так и комбинироваться. Поиск не чувствителен к регистру.
*codesearch - Поиск по кодам. В случае использования - контейнеры conditions и limit игнорируются.
'''code''' - Поиск по внутреннему коду системы.
'''article''' - Поиск по артикулу.
'''barcode''' - Поиск по штрих-коду.

*conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".
'''namecontains''' - Поиск товаров, название которых содержит указанный текст.
'''namestarts''' - Поиск товаров, название которых начинается с указанного текста.
'''name''' - Поиск товаров, название которых соответствует указанному тексту.
'''quantity''' - Наличие на складе. Принимает значения EXISTING_ONLY - Только в наличии, NOT_EXISTING_ONLY - Только не в наличии, ALL - Все. ''Это поле может быть недоступным в некоторых установках.''

*limit - Ограничивает вывод результата.
'''limitfrom''' - Задает номер записи результата, начиная с которой выдавать ответ.
'''limitcount''' - Задает количество записей результата, которые нужно вернуть.

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

'''Описание полей:'''
*'''code''' - Внутренний идентификатор, присвоенный системой.

*'''article''' - Артикул, назначенный клиентом (поставщиком).

*'''barcode''' - Штрих-код производителя.

*'''name''' - Наименование.

*'''retprice''' - Розничная цена по-умолчанию. При оформлении заказа цена используется та, которая указана в заказе.

*'''weight''' - Масса в килограммах.

*'''length''' - Длина в сантиметрах.

*'''width''' - Ширина в сантиметрах.

*'''height''' - Высота в сантиметрах.

*'''CountInPallet''' - Количество штук в паллете.

*'''HasSerials''' - Требует учета серийных номеров. Принимает значения 1 - да, 0 - нет.

*'''CountryOfOrigin''' - Наименование страны происхождения на русском языке.

*'''Message''' - Комментарий.

*'''Message2''' - Дополнительный комментарий.

*'''quantity''' - Количество на складе. Товары, уже собранные в заказы в этом количестве не присутствуют, считаются покинувшими товарный склад. ''Это поле может быть недоступным в некоторых установках.''

*'''reserved''' - Количество зарезервированного товара. Может превышать остаток на складе, если покупатели ждут следующей поставки. ''Это поле может быть недоступным в некоторых установках.''

== Справочник пунктов самовывоза (not yet supported) ==

== Справочник типов доставки ==

'''Пример запроса типов доставки:'''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<services>
</services>
</source>

'''Пример ответа справочника типов доставки:'''
<source lang="xml">
<?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>
</source>

== Расчет стоимости доставки (not yet supported) ==

'''Пример запроса стоимости доставки:'''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<calculator>
<auth login="login" pass="pass" />
<calc townfrom="Воронеж город" townto="Москва город" mass="3" mode="2" />
</calculator>
</source>

'''Пример ответа стоимости доставки:'''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<calculator>
<calc townfrom="Воронеж город" townto="Москва город" mass="3" price="3255.14"/>
</calculator>
</source>

API

2014-04-23T09:46:56Z

Wiz: /* Примеры ответов */

В системе "Курьерская служба 2008" имеется возможность интеграции средствами XML API, по протоколу HTTP POST.

== Общие понятия ==

На стороне курьерской службы имеется веб-сервис. Адрес уточняйте у представителей компании. Авторизационные данные так же уточняйте у представителей компании.
Клиент отправляет запросы к сервису, сервис обрабатывает запросы и возвращает результат выполнения. Все запросы и ответы передаются в формате XML.
Кодировка - UTF-8. Разделитель целой и дробной частей чисел - используется символ точки. Даты представляются в виде YYYY-MM-DD, время - HH:MM.
В силу особенностей языка XML, некоторые символы в тексте должны быть заменены: & на &amp; < на &lt; > на &gt; " на &quot;

== Оформление заказа ==
=== Пример оформления заказа ===

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<neworder>
<auth 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>
</source>

=== Описание элементов для оформления заказа: ===

*'''neworder''' - Корневой контейнер, обязательный элемент.

*'''order''' - Контейнер для описания одного заказа, обязательный элемент.

*'''orderno''' - Номер заказа. Если присваивается клиентом - указывается здесь. Если не присваивается - можно оставить пустым, система сгенерирует свой номер, и вернет его в ответе.

*'''barcode''' - Штрих-код заказа. В случае, если клиент штрих-кодирует свои отправления, и штрих-код отличается от номера заказа, в этом поле указывается штрих-код. В случае наличия нескольких мест, и раздельной их маркировки, в этом поле допустимы маски в виде символов подчеркивания, говорящие о позициях штрих-кода, переменных для разных мест в рамках одного заказа.<br />
''Например'': В заказе номер 123 имеется 20 товарных вложений, которые упакованы в 3 транспортных места. Клиент формирует 3 штрих-кода на транспортные места: CLNT0012301, CLNT0012302, CLNT0012303, где CLNT - префикс клиента, 00123 - номер заказа, 01-03 - номер транспортного места в заказе. В поле barcode нужно указать CLNT00123__ (система поймет, что 2 последних символа могут быть любыми, и будут отражать штрих-коды к одному заказу).

*'''sender''' - Информация о отправителе заказа. Не обязательный контейнер.
<source lang="xml">
<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>
</source>

*'''receiver''' - Информация о получателе заказа. Обязательный контейнер.
<source lang="xml">
<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>
</source>

*'''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''' - Артикул товара.

=== Примеры ответов ===

'''Пример успешного ответа'''

<source lang="xml">
<?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>
</source>

'''Пример ответа с ошибкой'''

<source lang="xml">
<?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>
</source>

'''Пример ответа при ошибке авторизации'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<request>
<error error="1" errormsg="authorization error"></error>
</request>
</source>

'''Пример ответа при ошибке синтаксиса'''

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<request>
<error>column:1 line:11 message:expected '>'</error>
</request>
</source>

=== Коды ошибок при оформлении заказа ===

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 - Заказ с таким номером уже существует.

== Запрос статуса заказов ==

=== Пример запроса статуса заказа ===

<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<statusreq>
<auth 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> (not yet supported)
</statusreq>
</source>

=== Описание полей запроса статуса ===

'''statusreq''' - Корневой контейнер. Обязательный элемент.
*'''auth''' - Авторизация. Обязательный элемент.
*'''orderno''' - Номер заказа. Не обязательный элемент.
*'''datefrom''' - Дата "с". Обязательный элемент.
*'''dateto''' - Дата "по". Обязательный элемент.
*'''done''' - Может принимать значения:

*Только не доставленные '''ONLY_NOT_DONE'''
*Только доставленные '''ONLY_DONE'''
*Все '''пусто'''

=== Примеры ответов ===

'''Пример успешного ответа'''

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<statusreq count="23">
<auth login="login" pass="pass"></auth>
<order orderno="111111" ordercode="34534234" givencode="2345334">
<barcode>111111</barcode>
<sender>
<company>МВД</company>
<person>Иванов И.И.</person>
<phone>123-45-67</phone>
<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</phone>
<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>
</source>

'''Пример ответа если нет заказов'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<statusreq>
</statusreq>
</source>

'''Пример ответа при ошибке авторизации'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<request>
<error error="1" errormsg="authorization error"></error>
</request>
</source>

'''Пример ответа при ошибке синтаксиса'''

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<request>
<error>column:1 line:11 message:expected '>'</error>
</request>
</source>

=== Описание полей ответа статусов ===
Все поля ответа соответствуют структуре 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 - Доставлен частично

''Примечание:'' В будущем планируется расширение используемого набора статусов.

== Справочник городов ==

'''Пример запроса справочника городов:'''
<source lang="xml">
<?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>
</source>

Внутри контейнера townlist все элементы могут как отсутствовать, так и комбинироваться. Поиск не чувствителен к регистру.
*codesearch - Поиск по кодам. В случае использования - контейнеры conditions и limit игнорируются.
'''zipcode''' - Поиск по индексу. Система найдет первый населенный пункт, который соответствует указанному индексу. Поскольку один почтовый индекс может распространяться на несколько населенных пунктов - поиск может выдать не тот пункт, который ожидается. Данный параметр может не поддерживаться в конкретной установке системы.
'''code''' - Поиск по коду в системе.

*conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".
'''city''' - Поиск по всем населенным пунктам региона.
'''namecontains''' - Поиск населенных пунктов, название которых содержит указанный текст.
'''namestarts''' - Поиск населенных пунктов, название которых начинается с указанного текста.
'''name''' - Поиск населенных пунктов, название которых соответствует указанному тексту.
'''fullname''' - Поиск населенных пунктов, название вместе с типом населенного пункта которых соответствует указанному тексту.

*limit - Ограничивает вывод результата.
'''limitfrom''' - Задает номер записи результата, начиная с которой выдавать ответ. По-умолчанию - 0.
'''limitcount'''- Задает количество записей результата, которые нужно вернуть. По-умолчанию - 10000.
'''countall''' - YES указывает на необходимость подсчета общего количества найденных совпадений. Это может замедлять выполнение запроса. Если отключено - в ответе не указываются totalcount и totalpages.

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

== Справочник регионов ==

'''Пример запроса справочника:'''
<source lang="xml">
<?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>
</source>

'''Пример ответа:'''
<source lang="xml">
<?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>
</source>

== Справочник номенклатуры (not yet supported) ==

'''Пример запроса справочника номенклатуры:'''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<itemlist>
<auth login="login" pass="pass"></auth>
<codesearch>
<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>
</limit>
</itemlist>
</source>

Внутри контейнера itemlistвсе элементы могут как отсутствовать, так и комбинироваться. Поиск не чувствителен к регистру.
*codesearch - Поиск по кодам. В случае использования - контейнеры conditions и limit игнорируются.
'''article''' - Поиск по артикулу.
'''barcode''' - Поиск по штрих-коду.

*conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".
'''namecontains''' - Поиск товаров, название которых содержит указанный текст.
'''namestarts''' - Поиск товаров, название которых начинается с указанного текста.
'''name''' - Поиск товаров, название которых соответствует указанному тексту.
'''quantity''' - Наличие на складе. Принимает значения EXISTING_ONLY - Только в наличии, NOT_EXISTING_ONLY - Только не в наличии, ALL - Все. ''Это поле может быть недоступным в некоторых установках.''

*limit - Ограничивает вывод результата.
'''limitfrom''' - Задает номер записи результата, начиная с которой выдавать ответ.
'''limitcount''' - Задает количество записей результата, которые нужно вернуть.

'''Пример ответа:'''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<itemlist count="3" totalcount="3" page="1" totalpages="1">
<item>
<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>
<Message>Хороший телевизор</Message>
<Message2>Снова хороший телевизор</Message2>
<quantity>12</quantity>
<reserved>3</reserved>
<item>
...
</itemlist>
</source>

'''Описание полей:'''
*'''article''' - Артикул, назначенный клиентом (поставщиком).

*'''barcode''' - Штрих-код производителя.

*'''name''' - Наименование.

*'''retprice''' - Розничная цена по-умолчанию. При оформлении заказа цена используется та, которая указана в заказе.

*'''weight''' - Масса в килограммах.

*'''length''' - Длина в сантиметрах.

*'''width''' - Ширина в сантиметрах.

*'''height''' - Высота в сантиметрах.

*'''CountInPallet''' - Количество штук в паллете.

*'''HasSerials''' - Требует учета серийных номеров. Принимает значения 1 - да, 0 - нет.

*'''CountryOfOrigin''' - Наименование страны происхождения на русском языке.

*'''Message''' - Комментарий.

*'''Message2''' - Дополнительный комментарий.

*'''quantity''' - Количество на складе. Товары, уже собранные в заказы в этом количестве не присутствуют, считаются покинувшими товарный склад. ''Это поле может быть недоступным в некоторых установках.''

*'''reserved''' - Количество зарезервированного товара. Может превышать остаток на складе, если покупатели ждут следующей поставки. ''Это поле может быть недоступным в некоторых установках.''

== Справочник пунктов самовывоза (not yet supported) ==

== Справочник типов доставки ==

'''Пример запроса типов доставки:'''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<services>
</services>
</source>

'''Пример ответа справочника типов доставки:'''
<source lang="xml">
<?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>
</source>

== Расчет стоимости доставки (not yet supported) ==

API

2014-04-18T12:21:07Z

Wiz: /* Справочник городов */

API

2014-04-17T19:59:51Z

Wiz: /* Описание элементов для оформления заказа: */

API

2014-04-17T19:58:34Z

Wiz: /* Описание полей ответа статусов */

API

2014-04-17T19:57:44Z

Wiz: /* Описание полей ответа статусов */

API

2014-04-17T19:56:30Z

Wiz: /* Описание элементов для оформления заказа: */

API

2014-04-17T19:53:43Z

Wiz: /* Описание полей ответа статусов */

API

2014-04-17T19:51:20Z

Wiz: /* Описание полей ответа статусов */

API

2014-04-17T19:48:27Z

Wiz: /* Описание элементов для оформления заказа: */

API

2014-04-17T19:47:27Z

Wiz: /* Примеры ответов */

API

2014-04-17T19:47:00Z

Wiz: /* Примеры ответов */

API

2014-04-17T19:46:41Z

Wiz: /* Пример оформления заказа */

API

2014-04-17T18:21:42Z

Wiz: /* Примеры ответов */

API

2014-04-17T17:13:38Z

Wiz: /* Примеры ответов */

API

2014-04-17T17:12:12Z

Wiz: /* Примеры ответов */

API

2014-04-17T07:04:36Z

Wiz: /* Примеры ответов */

API

2014-04-15T20:47:13Z

Wiz: /* Описание полей ответа статусов */

API

2014-04-15T20:45:41Z

Wiz: /* Описание полей ответа статусов */

API

2014-04-15T20:44:17Z

Wiz: /* Описание полей ответа статусов */

API

2014-04-15T20:41:46Z

Wiz: /* Описание полей запроса статуса */

API

2014-04-15T20:41:11Z

Wiz: /* Описание полей запроса статуса */

API

2014-04-15T20:35:08Z

Wiz: /* Запрос статуса заказов */

API

2014-04-15T20:27:34Z

Wiz:

API

2014-04-15T20:15:43Z

Wiz: /* Примеры ответов */

API

2014-04-15T20:14:29Z

Wiz: /* Примеры ответов */

API

2014-04-15T20:11:06Z

Wiz: /* Примеры ответов */

API

2014-04-15T20:10:40Z

Wiz: /* Примеры ответов */

API

2014-04-15T20:07:41Z

Wiz: /* Примеры ответов */

API

2014-04-15T20:06:16Z

Wiz: /* Пример ответа */

API

2014-04-15T20:05:47Z

Wiz: /* Запрос статуса заказов */

API

2014-04-15T20:01:59Z

Wiz: /* Пример ответа на запрос статуса */

API

2014-04-15T20:01:11Z

Wiz: /* Запрос статуса заказов */

API

2014-04-15T19:58:46Z

Wiz: /* Пример ответа на запрос статуса */

API

2014-04-15T19:46:05Z

Wiz:

API

2014-04-15T19:44:50Z

Wiz:

API

2014-04-15T19:43:30Z

Wiz:

API

2014-04-15T19:35:45Z

Wiz:

API

2014-04-15T19:34:20Z

Wiz: /* Пример запроса статуса заказов */

API

2014-04-15T18:14:30Z

Wiz: /* Пример ответа с ошибкой */

API

2014-04-15T18:11:09Z

Wiz: /* Описание элементов для оформления заказа: */

API

2014-04-15T18:09:33Z

Wiz: /* Пример ответа с ошибкой */

API

2014-04-15T18:03:20Z

Wiz: /* Пример ответа с ошибкой */

API

2014-04-15T18:02:43Z

Wiz: /* Пример ответа с ошибкой */

API

2014-04-15T18:01:31Z

Wiz: /* Пример ответа с ошибкой */

API

2014-04-15T18:00:44Z

Wiz: /* Пример ответа с ошибкой */