API

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

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

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

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

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

<?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>

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

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

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

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

• barcode - Штрих-код заказа. В случае, если клиент штрих-кодирует свои отправления, и штрих-код отличается от номера заказа, в этом поле указывается штрих-код. В случае наличия нескольких мест, и раздельной их маркировки, в этом поле допустимы маски в виде символов подчеркивания, говорящие о позициях штрих-кода, переменных для разных мест в рамках одного заказа.
  

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

• sender - Информация о отправителе заказа. Не обязательный контейнер.

   <sender>
     <company>Название компании отправителя</company>
     <person>Контактное лицо отправителя</person>
     <phone>Телефон, Email отправителя</phone>
     <town>Город отправителя в формате "Москва город"</town>
     <address>Адрес отправителя</address>
     <date>Дата забора в формате "YYYY-MM-DD"</date>
     <time_min>Желаемое время забора в формате "HH:MM"</time_min>
     <time_max>Желаемое время забора в формате "HH:MM"</time_max>
   </sender>

• receiver - Информация о получателе заказа. Обязательный контейнер.

   <receiver>
     <company>Название компании получателя</company>
     <person>Контактное лицо получателя</person>
     <phone>Телефон, Email получателя</phone>
     <town>Город получателя в формате "Москва город"</town>
     <address>Адрес получателя</address>
     <date>Дата доставки в формате "YYYY-MM-DD"</date>
     <time_min>Желаемое время доставки в формате "HH:MM"</time_min>
     <time_max>Желаемое время доставки в формате "HH:MM"</time_max>
   </receiver>

• company - Компания-получатель. Должно быть заполнено company ИЛИ person!
• person - Контактное лицо. Должно быть заполнено company ИЛИ person!
• phone - Телефон. Можно указывать несколько телефонов, E-mail в этом поле.
• town - Город. В системе города привязываются к справочнику, поэтому город должен иметь правильное полное написание. Так же можно в этом поле указать числовое значение - код населенного пункта из справочника городов. При указании названия возможно появление ошибки, если населенных пунктов с таким названием в справочнике несколько.

• paytype - Тип оплаты заказа получателем. Принимает значения:

CASH	Наличными (по-умолчанию)
CARD	Картой
NO	Без оплаты
OTHER	Прочее (платежные системы и т.д.)

• zipcode - Почтовый индекс.
• weight - Общий вес заказа.
• quantity - Количество мест.
• service - Режим доставки (тип услуги) передается код из соответствующего справочника.
• price - Сумма заказа. В случае наличия контейнера items значение данного параметра будет проигнорировано, и рассчитано автоматически.
• enclosure - Вложение.
• inshprice - Объявленная ценность.
• instruction - Поручение - Примечание.

items - Контейнер для описания вложенных товаров. Не обязательный контейнер.

• item - Название товара.
• quantity - Количество мест.
• mass - Масса товара. В случае наличия контейнера items значение данного параметра будет проигнорировано, и рассчитано автоматически.
• retprice - Цена товара.
• barcode - Штрих-код товара.
• article - Артикул товара.

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

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

<?xml version="1.0" encoding="UTF-8"?>
<neworder>
   <createorder orderno="AB23541" error="0" errormsg="success"></createorder>
   <createorder orderno="55_6542" error="0" errormsg="success"></createorder>
   <createorder orderno="AB23542" error="0" errormsg="success"></createorder>
</neworder>

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

<?xml version="1.0" encoding="UTF-8"?>
<neworder>
   <createorder orderno="AB23541" error="17" errormsg="Such number exists"></createorder>
   <createorder orderno="AB23542" error="13" errormsg="empty company"></createorder>
   <createorder orderno="AB23542" error="14" errormsg="empty person"></createorder>
</neworder>

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

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

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

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

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

0 - Ошибок нет.

1 - Ошибка авторизации. (отсутствуют теги <auth login="" pass=""></auth>, неверный логин или пароль).

2 - Отправлен пустой запрос (отсутствует контейнер <neworder></neworder> в XML документе).

3 - Некорректно указана сумма заказа.

4 - Некорректный общий вес заказа.

5 - Не найден город получатель.

6 - Не найден город отправитель.

7 - Не заполнен адрес получателя.

8 - Не заполнен телефон получателя.

9 - Не заполнено контактное имя получателя.

10 - Не заполнено название компании получателя.

11 - Некорректная сумма объявленной ценности.

12 - Артикул не найден.

13 - Не заполнено название компании отправителя.

14 - Не заполнено контактное имя отправителя.

15 - Не заполнен телефон отправителя.

16 - Не заполнен адрес отправителя.

17 - Заказ с таким номером уже существует.

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

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

<?xml version="1.0" encoding="UTF-8" ?>
<statusreq>
  <auth login="login" pass="pass"></auth>
  <client>CLIENT</client>
  <orderno>1234</orderno>
  <ordercode>34234</ordercode>
  <givencode>234534</givencode>
  <datefrom>2014-04-03</datefrom>
  <dateto>2014-04-03</dateto>
  <done>ONLY_NOT_DONE</done>
  <changes>ONLY_LAST</changes>
</statusreq>

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

statusreq - Корневой контейнер. Обязательный элемент.

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

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

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

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

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

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

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

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

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

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

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

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

Описание полей ответа статусов

Все поля ответа соответствуют структуре order при создании заказа, с некоторыми добавлениями:

• атрибут ordercode контейнера order - внутренний код заказа в системе, применяется для некоторых внутренних операций.
• атрибут givencode контейнера order - внутренний код заказа в системе, применяется для некоторых внутренних операций.
• атрибут returns контейнера item - Количество данного товара, от которого отказался получатель. Не нулевое только в случае частичного

отказа.

• атрибут code контейнера item - внутренний код строки заказа в системе, применяется для некоторых внутренних операций.
• coords в контейнере receiver - координаты получателя.
• currcoords - текущие координаты заказа. Атрибуты:

  lat - широта
  lon - долгота
  accuracy - точность в метрах
  RequestDateTime - дата/время последнего обновления координат.

• deliveryprice - стоимость доставки в валюте расчетов с клиентом.
• status - статус доставки.
• customstatecode - код статуса клиента. Используется, если клиент предлагает свои коды статусов доставки/причин недоставки.
• deliveredto - Данные о вручении, либо причина недоставки.
• delivereddate - Дата вручения.
• deliveredtime - Время вручения. В случае недоставки может быть пустым.

Статус может принимать следующие значения:

NEW - Новый

ACCEPTED - Получен складом

DELIVERY - Доставляется

COMPLETE - Доставлен

CANCELED - Не доставлен

PARTIALLY - Доставлен частично

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

Передача только изменившихся статусов

Для получения только изменившихся статусов отправьте запрос

<?xml version="1.0" encoding="UTF-8" ?>
<statusreq>
  <auth login="login" pass="pass"></auth>
  <changes>ONLY_LAST</changes>
</statusreq>

Система выдает все заказы, в которых, с момента последнего запроса в этом режиме, изменилось хотя бы одно из полей:

orderno
status
delivereddate
deliveredtime
deliveredto
receiver->date
receiver->address
price

После успешной обработки ответа необходимо отметить полученные статусы успешно полученными, отправив запрос

<?xml version="1.0" encoding="UTF-8" ?>
<commitlaststatus>
  <auth login="login" pass="pass"></auth>
</commitlaststatus>

В случае успеха Вы получите ответ

<?xml version="1.0" encoding="UTF-8" ?>
<commitlaststatus>
  <error error="0" errormsg="OK"></error>
</commitlaststatus>

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

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

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

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

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

Пример запроса справочника городов:

<?xml version="1.0" encoding="UTF-8"?>
<townlist>
  <codesearch>
    <zipcode>110000</zipcode>  (not yet supported)
    <code>123</code>
  </codesearch>
  <conditions>
    <city>Краснодарский край</city>
    <namecontains>новгород</namecontains>
    <namestarts>Моск</namestarts>
    <name>Москва</name>  (not yet supported)
    <fullname>Москва город</fullname>
  </conditions>
  <limit>
    <limitfrom>30</limitfrom>
    <limitcount>10</limitcount>
    <countall>YES</countall>
  </limit>
</townlist>

Внутри контейнера townlist все элементы могут как отсутствовать, так и комбинироваться. Поиск не чувствителен к регистру.

• codesearch - Поиск по кодам. В случае использования - контейнеры conditions и limit игнорируются.

 zipcode - Поиск по индексу. Система найдет первый населенный пункт, который соответствует указанному индексу. Поскольку один почтовый индекс может распространяться на несколько населенных пунктов - поиск может выдать не тот пункт, который ожидается. Данный параметр может не поддерживаться в конкретной установке системы.
 code - Поиск по коду в системе.

• conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".

 city - Поиск по всем населенным пунктам региона.
 namecontains - Поиск населенных пунктов, название которых содержит указанный текст.
 namestarts - Поиск населенных пунктов, название которых начинается с указанного текста.
 name - Поиск населенных пунктов, название которых соответствует указанному тексту.
 fullname - Поиск населенных пунктов, название вместе с типом населенного пункта которых соответствует указанному тексту.

• limit - Ограничивает вывод результата.

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

Пример ответа:

<?xml version="1.0" encoding="UTF-8"?>
<townlist count="3" page="1" totalcount="3" totalpages="1">
  <town>
     <code>26379</code>
     <city>
       <code>23</code>
       <name>Краснодарский край</name>
     </city>
     <name>Сочи город</name>
     <shortname>Сочи</shortname>  (not yet supported)
     <typename>город</typename>  (not yet supported)
  </town>
  <town>
     <code>40331</code>
     <city>
       <code>32</code>
       <name>Брянская область</name>
     </city>
     <name>Сочилов хутор</name>
     <shortname>Сочилов</shortname>
     <typename>хутор</typename>
  </town>
  <town>
     <code>114016</code>
     <city>
       <code>60</code>
       <name>Псковская область</name>
     </city>
     <name>Сочихино деревня</name>
     <shortname>Сочихино</shortname>
     <typename>деревня</typename>
  </town>
</townlist>

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

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

Пример запроса справочника:

<?xml version="1.0" encoding="UTF-8"?>
<regionlist>
  <codesearch>
    <code>77</code>
  </codesearch>
  <conditions>
    <namecontains>край</namecontains>
    <namestarts>Моск</namestarts>
    <fullname>Московская область</fullname>
    <ourcountry>YES</ourcountry>
  </conditions>
</regionlist>

Пример ответа:

<?xml version="1.0" encoding="UTF-8"?>
<regionlist count="99">
     <city>
       <code>23</code>
       <name>Краснодарский край</name>
     </city>
     <city>
       <code>32</code>
       <name>Брянская область</name>
     </city>
     <city>
       <code>60</code>
       <name>Псковская область</name>
     </city>
</regionlist>

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

Пример запроса справочника городов:

<?xml version="1.0" encoding="UTF-8"?>
<streetlist>
  <conditions>
    <town>Москва город</town>
    <namecontains>Хохло</namecontains>
    <namestarts>Академика Х</namestarts>
    <name>Академика Хохлова</name>
    <fullname>Академика Хохлова ул.</fullname>
  </conditions>
  <limit>
    <limitfrom>30</limitfrom>
    <limitcount>10</limitcount>
    <countall>YES</countall>
  </limit>
</streetlist >

• conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".

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

• limit - Ограничивает вывод результата.

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

Пример ответа:

<?xml version="1.0" encoding="UTF-8"?>
<streetlist count="1" page="1" totalcount="3" totalpages="1">
  <street>
     <name>Академика Хохлова ул.</name>
     <shortname>Академика Хохлова</shortname>
     <typename>ул.</typename>
  </street>
</streetlist>

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

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

Пример запроса справочника номенклатуры:

<?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>

Внутри контейнера itemlistвсе элементы могут как отсутствовать, так и комбинироваться. Поиск не чувствителен к регистру.

• codesearch - Поиск по кодам. В случае использования - контейнеры conditions и limit игнорируются.

 article - Поиск по артикулу.
 barcode - Поиск по штрих-коду.

• conditions - Задает условия поиска. Все вложенные элементы одновременно накладывают условие "И".

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

• limit - Ограничивает вывод результата.

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

Пример ответа:

<?xml version="1.0" encoding="UTF-8"?>
<itemlist count="3" totalcount="3" page="1" totalpages="1">
  <item>
    <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>

Описание полей:

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

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

• name - Наименование.

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример запроса типов доставки:

<?xml version="1.0" encoding="UTF-8" ?>
<services>
</services>

Пример ответа справочника типов доставки:

<?xml version="1.0" encoding="UTF-8" ?>
<services count="2">
  <service>
     <code>1</code>
     <name>Эконом</name>
  </service>
  <service>
     <code>2</code>
     <name>Срочно</name>
  </service>
</services>