API модуля мобильных устройств

Для взаимодействия модуля мобильных устройств со сторонними системами предусмотрено XML API. Сторонняя система передает справочники клиентов (компаний-заказчиков доставки), курьеров, и заказы на доставку. Обратно получает статусы заказов, приложенные документы (фото и подписи с экрана), и треки курьеров.

Создание/изменение клиентов

Запрос отправляется по адресу https://home.courierexe.ru/api/clientapi.php

<?xml version="1.0" encoding="UTF-8"?>
  <upload>
    <auth login="login" pass="pass" />
    <table>clients</table>
    <item>
      <code>2681</code>
      <company>Рога и копыта</company>
      <name>Иванов Иван Иванович</name>
      <phone>8-916-123-45-67</phone>
      <address>Варшавское шоссе, 125</address>
      <AskPayType>T</AskPayType>
      <CreateTrans>T</CreateTrans>
      <CheckMessage>По возвратам обращаться тел. 123-45-67</CheckMessage>
    </item>
    <item>
      ...
    </item>
  </upload>

Запрос содержит тег upload - загрузка на сервер. auth - авторизация по login и pass. table - имя таблицы. Далее следуют один или несколько контейнеров item, каждый содержит 1 запись для добавления или изменения на сервере.

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

• code - int, идентификатор записи. Если запись с таким code уже есть - она будет заменена.
• company - наименование компании
• name - ФИО контактного лица
• phone - телефон.
• address - фактический адрес.
• AskPayType - Спрашивать способ оплаты (наличными/картой) при доставке. T - истина, F - ложь.
• CreateTrans - Кассовое обслуживание. T - истина, F - ложь. Если у курьера подключен фискальный регистратор, приложение не позволит сохранить доставку не распечатав чек. Если у курьера нет ФР - приложение укажет на необходимость печати чека на отдельном кассовом аппарате или выдачи заранее распечатанного чека.
• CheckMessage - Дополнительный текст для вывода на чек.

В случае успеха запроса сервер вернет:

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

Создание/изменение курьеров

Запрос отправляется по адресу https://home.courierexe.ru/api/clientapi.php

<?xml version="1.0" encoding="UTF-8"?>
  <upload>
    <auth login="login" pass="pass" />
    <table>kurier</table>
    <item>
      <code>2681</code>
      <name>Иванов Иван Иванович</name>
      <phonem>8-916-123-45-67</phonem>
      <dateput>NULL</dateput>
    </item>
    <item>
      ...
    </item>
  </upload>

Запрос содержит тег upload - загрузка на сервер. auth - авторизация по login и pass. table - имя таблицы. Далее следуют один или несколько контейнеров item, каждый содержит 1 запись для добавления или изменения на сервере.

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

• code - int, идентификатор записи. Если запись с таким code уже есть - она будет заменена.
• name - ФИО курьера
• phonem - телефон курьера. Используется для обратного звонка при интеграции с телефонией.
• dateput - дата увольнения, чтобы блокировать курьера. Если курьер работает - NULL, если уволен - укажите дату увольнения в формате YYYY-MM-DD

В случае успеха запроса сервер вернет:

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

Создание заказов

Запросы отправляются по адресу https://home.courierexe.ru/api/

Запрос создания заказа почти полностью совпадает с обычным API, за исключением нескольких полей:

 <?xml version="1.0" encoding="UTF-8" ?>
 <neworder>
  <auth2 clientcode="655" extra="8" login="MEASOFT2" pass="pass"></auth2>
  <order orderno="11_11_11">
   <code>1851117</code>
   <courier>927</courier>
   <barcode>11_11_11</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>Чип &amp; Дейл</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>
   <return>NO</return>
   <return_service>1</return_service>
   <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 extcode="abc123" quantity="1" mass="0.2" retprice="37.5" barcode="2345625213125">Мяч</item>
      <item extcode="abc124" quantity="2" mass="2" retprice="100" barcode="4645625213138">Обруч</item>
      <item extcode="abc125" quantity="3" mass="0.3" retprice="50" barcode="2345625213126">Погремушка желтая</item>
   </items>
  </order>
 </neworder>

Вместо блока <auth></auth> используется <auth2></auth2>

Поле clientcode - код клиента в системе, от которого создается заказ

При создании нового заказа в блоке <order></order> так же добавлены новые поля:

 <code>1851117</code>      Идентификатор заказа
 <courier>927</courier>    Код курьера

Получение статусов заказов

Запрос отправляется по адресу https://home.courierexe.ru/api/clientapi.php

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

Запрос содержит тег download - загрузка c сервера. auth - авторизация по login и pass. table - имя таблицы.

В случае успеха сервер вернет ответ вида:

<?xml version="1.0" encoding="UTF-8"?>
<download count="1">
  <item>
    <prkey>205115</prkey>
    <extraclientcode>8</extraclientcode>
    <code>19368</code>
    <address>1863405</address>
    <kurierstate>3</kurierstate>
    <kurierundelstate>2</kurierundelstate>
    <kurierstatetime>2016-11-01 15:38</kurierstatetime>
    <kurierdate>2016-11-01</kurierdate>
    <kuriermessage>Иванова, секр.</kuriermessage>
    <kuriertime>15:38</kuriertime>
    <kuriermoney>1560</kuriermoney>
    <ldtime>2016-11-21 23:25:16</ldtime>
  </item>
</download>

• address - код заказа
• kurierstate - Статус доставки (справочник 64)
• kurierundelstate - Причина недоставки (Справочник 6)
• kuriermessage - примечания курьера/ФИО получившего
• kurierdate, kuriertime - дата, время статуса.
• kuriermoney - сумма, полученная курьером.

В случае успешного приема данных необходимо подтвердить получение, послав запрос:

<?xml version="1.0" encoding="UTF-8"?>
  <commitdownload>
    <auth login="login" pass="pass" />
    <table>givn</table>
    <code>19368</code>
  </commitdownload>

Получение изображений к заказам

Запрос отправляется по адресу https://home.courierexe.ru/api/clientapi.php

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

Запрос содержит тег download - загрузка c сервера. auth - авторизация по login и pass. table - имя таблицы.

В случае успеха сервер вернет ответ вида:

<?xml version="1.0" encoding="UTF-8"?>
<download count="1">
  <item>
    <prkey>205115</prkey>
    <extraclientcode>8</extraclientcode>
    <code>-19368</code>
    <item_code>1863405</item_code>
    <type>3</type>
    <file>FFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAFFFFABRRRQAUUUUAfDv8OZ</file>
    <filename>sign.jpg</filename>
    <filesize>215130</filesize>
    <extraID />
    <UID>NULL</UID>
    <ldtime>2015-07-21 23:25:16</ldtime>
  </item>
</download>

В ответе 0 или более контейнеров item с записями. Значимые поля:

• code - отрицательный идентификатор, присвоенный сервером.
• item_code - код заказа.
• file - содержимое файла в кодировке base64
• filename - имя файла

В случае успешного приема данных необходимо подтвердить получение, послав запрос:

<?xml version="1.0" encoding="UTF-8"?>
  <commitdownload>
    <auth login="login" pass="pass" />
    <table>attachment</table>
    <oldcodes>-19368, -19369, -19370</oldcodes>
    <newcodes>123, 124, 125</newcodes>
  </commitdownload>

• oldcodes - коды записей, пришедшие от сервера. Перечисление через запятую.
• newcodes - коды записей, присвоенных в принимающей системе. Последовательность и количество должны соответствовать oldcodes.

В случае успеха подтверждения сервер вернет ответ:

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

До тех пор пока вся последовательность "запрос данных - ответ данными - подтверждение приема - подтверждение подтверждения" не пройдена - данные считаются не переданными, и будут возвращены сервером при следующем запросе.

Получение треков курьеров

Запрос отправляется по адресу https://home.courierexe.ru/api/clientapi.php

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

Запрос содержит тег download - загрузка c сервера. auth - авторизация по login и pass. table - имя таблицы.

В случае успеха сервер вернет ответ вида:

<?xml version="1.0" encoding="UTF-8"?>
<download count="1">
  <item>
    <code>29798426</code>
    <kurier>2249</kurier>
    <phoneid>1160</phoneid>
    <lat>56.4565</lat>
    <lon>34.2777</lon>
    <Accuracy>30</Accuracy>
    <RequestDateTime>2015-07-21 21:02:31</RequestDateTime>
  </item>

Поля:

• code - внутренний идентификатор, присвоенный сервером.
• kurier - код курьера.
• lat - широта.
• lon - долгота.
• Accuracy - точность определения координат в метрах.
• RequestDateTime - дата/время запроса по часам мобильного устройства.

В случае успешного приема данных необходимо подтвердить получение, послав запрос:

<?xml version="1.0" encoding="UTF-8"?>
  <commitdownload>
    <auth login="login" pass="pass" />
    <table>tracking</table>
    <code>29798426</code>
  </commitdownload>

• code - поле code последней успешно добавленной записи. Сервер отметит все записи с таким или меньшим кодом отправленными. В выдаче download для таблицы tracking записи всегда отсортированы по возрастанию поля code.

В случае успеха подтверждения сервер вернет ответ:

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