API модуля мобильных устройств — различия между версиями

Материал из Меасофт
Перейти к: навигация, поиск
(→‎Получение статусов заказов)
 
(не показано 11 промежуточных версий этого же участника)
Строка 1: Строка 1:
−
Для взаимодействия модуля мобильных устройств со сторонними системами предусмотрено XML API.
+
Для взаимодействия модуля мобильных устройств со сторонними системами предусмотрено XML API. Сторонняя система передает справочники клиентов (компаний-заказчиков доставки), курьеров, и заказы на доставку. Обратно получает статусы заказов, приложенные документы (фото и подписи с экрана), и треки курьеров.
  
 
== Создание/изменение клиентов ==
 
== Создание/изменение клиентов ==
Строка 16: Строка 16:
 
       <address>Варшавское шоссе, 125</address>
 
       <address>Варшавское шоссе, 125</address>
 
       <AskPayType>T</AskPayType>
 
       <AskPayType>T</AskPayType>
 +
      <CreateTrans>T</CreateTrans>
 +
      <CheckMessage>По возвратам обращаться тел. 123-45-67</CheckMessage>
 
     </item>
 
     </item>
 
     <item>
 
     <item>
Строка 27: Строка 29:
  
 
Описание полей:
 
Описание полей:
−
code - int, идентификатор записи. Если запись с таким code уже есть - она будет заменена.
+
*code - int, идентификатор записи. Если запись с таким code уже есть - она будет заменена.
−
company - наименование компании
+
*company - наименование компании
−
name - ФИО контактного лица
+
*name - ФИО контактного лица
−
phone - телефон.
+
*phone - телефон.
−
address - фактический адрес.
+
*address - фактический адрес.
−
AskPayType - Спрашивать способ оплаты при доставке. T - истина, F - ложь.
+
*AskPayType - Спрашивать способ оплаты (наличными/картой) при доставке. T - истина, F - ложь.
 +
*CreateTrans - Кассовое обслуживание. T - истина, F - ложь. Если у курьера подключен фискальный регистратор, приложение не позволит сохранить доставку не распечатав чек. Если у курьера нет ФР - приложение укажет на необходимость печати чека на отдельном кассовом аппарате или выдачи заранее распечатанного чека.
 +
*CheckMessage - Дополнительный текст для вывода на чек.
  
 
В случае успеха запроса сервер вернет:
 
В случае успеха запроса сервер вернет:
Строка 64: Строка 68:
  
 
Описание полей:
 
Описание полей:
−
code - int, идентификатор записи. Если запись с таким code уже есть - она будет заменена.
+
*code - int, идентификатор записи. Если запись с таким code уже есть - она будет заменена.
−
name - ФИО курьера
+
*name - ФИО курьера
−
phonem - телефон курьера. Используется для обратного звонка при интеграции с телефонией.
+
*phonem - телефон курьера. Используется для обратного звонка при интеграции с телефонией.
−
dateput - дата увольнения, чтобы блокировать курьера. Если курьер работает - NULL, если уволен - укажите дату увольнения в формате YYYY-MM-DD
+
*dateput - дата увольнения, чтобы блокировать курьера. Если курьер работает - NULL, если уволен - укажите дату увольнения в формате YYYY-MM-DD
  
 
В случае успеха запроса сервер вернет:
 
В случае успеха запроса сервер вернет:
Строка 76: Строка 80:
  
 
== Создание заказов ==
 
== Создание заказов ==
−
Запросы отправляются по адресу https://home.courierexe.ru/api2/
+
Запросы отправляются по адресу https://home.courierexe.ru/api/
  
 
Запрос создания заказа почти полностью совпадает с обычным [[API]], за исключением нескольких полей:
 
Запрос создания заказа почти полностью совпадает с обычным [[API]], за исключением нескольких полей:
Строка 85: Строка 89:
 
   <auth2 clientcode="655" extra="8" login="MEASOFT2" pass="pass"></auth2>
 
   <auth2 clientcode="655" extra="8" login="MEASOFT2" pass="pass"></auth2>
 
   <order orderno="11_11_11">
 
   <order orderno="11_11_11">
−
  <coords>
+
  <code>1851117</code>
−
  <lat>55.768679</lat>
+
  <courier>927</courier>
−
  <lon>37.589042</lon>
 
−
  </coords>
 
−
    <code>1851117</code>
 
−
    <courier>927</courier>
 
 
   <barcode>11_11_11</barcode>
 
   <barcode>11_11_11</barcode>
 
   <sender>
 
   <sender>
Строка 123: Строка 123:
 
   <enclosure>Детские игрушки</enclosure>
 
   <enclosure>Детские игрушки</enclosure>
 
   <instruction>Проверить при покупателе, подписать акт</instruction>
 
   <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>
 
   </order>
 
  </neworder>
 
  </neworder>
Строка 129: Строка 133:
  
 
Вместо блока <auth></auth> используется <auth2></auth2>
 
Вместо блока <auth></auth> используется <auth2></auth2>
−
Поле clientcode - код клиента в системе
+
 
 +
Поле clientcode - код клиента в системе, от которого создается заказ
  
  
Строка 135: Строка 140:
 
так же добавлены новые поля:
 
так же добавлены новые поля:
 
<source lang="xml">
 
<source lang="xml">
−
<coords> - координаты
 
−
  <lat>55.768679</lat>
 
−
  <lon>37.589042</lon>
 
−
</coords>
 
 
  <code>1851117</code>      Идентификатор заказа
 
  <code>1851117</code>      Идентификатор заказа
−
  <courier>927</courier> код курьера
+
  <courier>927</courier>   Код курьера
 +
</source>
 +
 
 +
== Получение статусов заказов ==
 +
Запрос отправляется по адресу https://home.courierexe.ru/api/clientapi.php
 +
 
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
  <download>
 +
    <auth login="login" pass="pass" />
 +
    <table>givn</table>
 +
  </download>
 
</source>
 
</source>
  
 +
Запрос содержит тег download - загрузка c сервера. auth - авторизация по login и pass. table - имя таблицы.
  
−
== Получение статусов заказов ==
+
В случае успеха сервер вернет ответ вида:
 +
 
 +
<source lang="xml">
 +
<?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>
 +
</source>
 +
 
 +
*address - код заказа
 +
*kurierstate - Статус доставки (справочник 64)
 +
*kurierundelstate - Причина недоставки (Справочник 6)
 +
*kuriermessage - примечания курьера/ФИО получившего
 +
*kurierdate, kuriertime - дата, время статуса.
 +
*kuriermoney - сумма, полученная курьером.
 +
 
 +
В случае успешного приема данных необходимо подтвердить получение, послав запрос:
 +
 
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
  <commitdownload>
 +
    <auth login="login" pass="pass" />
 +
    <table>givn</table>
 +
    <code>19368</code>
 +
  </commitdownload>
 +
</source>
  
 
== Получение изображений к заказам ==
 
== Получение изображений к заказам ==
 +
Запрос отправляется по адресу https://home.courierexe.ru/api/clientapi.php
 +
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
  <download>
 +
    <auth login="login" pass="pass" />
 +
    <table>attachment</table>
 +
  </download>
 +
</source>
 +
 +
Запрос содержит тег download - загрузка c сервера. auth - авторизация по login и pass. table - имя таблицы.
 +
 +
В случае успеха сервер вернет ответ вида:
 +
 +
<source lang="xml">
 +
<?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>
 +
</source>
 +
 +
В ответе 0 или более контейнеров item с записями. Значимые поля:
 +
*code - отрицательный идентификатор, присвоенный сервером.
 +
*item_code - код заказа.
 +
*file - содержимое файла в кодировке base64
 +
*filename - имя файла
 +
 +
В случае успешного приема данных необходимо подтвердить получение, послав запрос:
 +
 +
<source lang="xml">
 +
<?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>
 +
</source>
 +
 +
*oldcodes - коды записей, пришедшие от сервера. Перечисление через запятую.
 +
*newcodes - коды записей, присвоенных в принимающей системе. Последовательность и количество должны соответствовать oldcodes.
 +
 +
В случае успеха подтверждения сервер вернет ответ:
 +
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<commitdownload error="0">OK</commitdownload>
 +
</source>
 +
 +
До тех пор пока вся последовательность "запрос данных - ответ данными - подтверждение приема - подтверждение подтверждения" не пройдена - данные считаются не переданными, и будут возвращены сервером при следующем запросе.
  
 
== Получение треков курьеров ==
 
== Получение треков курьеров ==
 +
 +
 +
Запрос отправляется по адресу https://home.courierexe.ru/api/clientapi.php
 +
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
  <download>
 +
    <auth login="login" pass="pass" />
 +
    <table>tracking</table>
 +
  </download>
 +
</source>
 +
 +
Запрос содержит тег download - загрузка c сервера. auth - авторизация по login и pass. table - имя таблицы.
 +
 +
В случае успеха сервер вернет ответ вида:
 +
 +
<source lang="xml">
 +
<?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>
 +
</source>
 +
 +
Поля:
 +
*code - внутренний идентификатор, присвоенный сервером.
 +
*kurier - код курьера.
 +
*lat - широта.
 +
*lon - долгота.
 +
*Accuracy - точность определения координат в метрах.
 +
*RequestDateTime - дата/время запроса по часам мобильного устройства.
 +
 +
В случае успешного приема данных необходимо подтвердить получение, послав запрос:
 +
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
  <commitdownload>
 +
    <auth login="login" pass="pass" />
 +
    <table>tracking</table>
 +
    <code>29798426</code>
 +
  </commitdownload>
 +
</source>
 +
 +
*code - поле code последней успешно добавленной записи. Сервер отметит все записи с таким или меньшим кодом отправленными. В выдаче download для таблицы tracking записи всегда отсортированы по возрастанию поля code.
 +
 +
В случае успеха подтверждения сервер вернет ответ:
 +
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<commitdownload error="0">OK</commitdownload>
 +
</source>

Текущая версия на 09:26, 24 января 2020

Для взаимодействия модуля мобильных устройств со сторонними системами предусмотрено 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>
Источник — «https://wiki.courierexe.ru/index.php?title=API_модуля_мобильных_устройств&oldid=9915»