Различия

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

--- doc:dev:api:orders [24.08.2017 19:07]
asonkin
+++ doc:dev:api:orders [03.08.2018 17:56] (текущий)
aderyabin [Параметры запроса]
@@ Строка 11: / Строка 11: @@
 ==== Параметры запроса ====
+параметры, которые не отмечены как **get only**, могут быть переданы как get- или как post-параметры.
+  * **apikey** - Секретный ключ для доступа к данным. Обязательный параметр.
+  * **format** (get only) - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр.
+  * **id** (get only) - код клиента, для которого требуется вернуть данные. Если не указан, то возвращаются данные заказов обо всех клиентах.
+  * **datefrom** - получение Поступлений начиная с определенной даты. Формат: ГГГГММДД. Необязательный параметр.
+  * **dateto** - получение Поступлений начиная до определенной даты. Формат: ГГГГММДД. Необязательный параметр.
+  * **days** - задает глубину поиска. Определяет, за какое количество дней от текущей даты надо вернуть документы Поступления. Необязательный параметр.
+  * **external_id** (get only) - (опционально) код клиента во внешней системе, работает аналогично параметру **id**
+==== Ответ сервера ====
+В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info
+==== Пример ответа сервера ====
+Ниже приведен пример ответа сервера в формате XML
+<file xml>
+<?xml version="1.0" encoding="UTF-8"?>
+<root>
+   <success>1</success>
+   <orders>
+      <order>
+         <id>1</id>
+         <paid>0</paid>
+         <customer_id>1928</customer_id>
+         <shipped>0</shipped>
+         <cancelled>0</cancelled>
+         <shipping_address />
+         <shipping_cost>0.00</shipping_cost>
+         <pickup_receipt_id />
+         <comment />
+         <guid />
+         <created_date>2017-08-24 14:07:06</created_date>
+         <amount>512.00</amount>
+         <discount>0.00</discount>
+         <pickup_from_warehouse_id>2</pickup_from_warehouse_id>
+         <pickup_from_warehouse_name>Просвещения проспект</pickup_from_warehouse_name>
+         <delivery_type_id>1</delivery_type_id>
+         <delivery_type_name>Самовывоз</delivery_type_name>
+         <payment_type_id>1</payment_type_id>
+         <payment_type_name>Оплата при получении</payment_type_name>
+         <items>
+            <item>
+               <item_id>787</item_id>
+               <item_name>Коньяк "Father's Old Barrel' 3-летний 40% 0.5 л.</item_name>
+               <image />
+               <quantity>1.000</quantity>
+               <unit_base_price>512.00</unit_base_price>
+               <discount>0.00</discount>
+               <amount>512.00</amount>
+            </item>
+         </items>
+      </order>
+   </orders>
+</root>
+</file>
+===== Пример запроса на получение данных =====
+Пример запроса на получение данных о типах оплаты:
+ http://mycompany.virtpos.ru/api/orders/get_payment_types?apikey=MySecret&format=xml
+==== Параметры запроса ====
+Параметры, которые не отмечены как **get only**, могут быть переданы как get- или как post-параметры.
   * **apikey** - Секретный ключ для доступа к данным. Обязательный параметр.
-  * **format** - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр.
+  * **format** (get only) - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр.
-  * **id** - код клиента, для которого требуется вернуть данные. Если не указан, то возвращаются данные заказов обо всех клиентах.
+==== Ответ сервера ====
-  * **external_id** - (опционально) код клиента во внешней системе, работает аналогично параметру **id**
+В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info
+==== Пример ответа сервера ====
+Ниже приведен пример ответа сервера в формате XML
+<file xml>
+<?xml version="1.0" encoding="UTF-8"?>
+<root>
+   <success>1</success>
+   <payment_types>
+      <type>
+         <id>1</id>
+         <name>Оплата при получении</name>
+      </type>
+   </payment_types>
+</root>
+</file>
+===== Пример запроса на получение данных =====
+Пример запроса на получение данных о типах доставки:
+ http://mycompany.virtpos.ru/api/orders/get_delivery_types?apikey=MySecret&format=xml
+==== Параметры запроса ====
+Параметры, которые не отмечены как **get only**, могут быть переданы как get- или как post-параметры.
+  * **apikey** - Секретный ключ для доступа к данным. Обязательный параметр.
+  * **format** (get only) - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр.
 ==== Ответ сервера ====
@@ Строка 25: / Строка 124: @@
 В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info
+==== Пример ответа сервера ====
+Ниже приведен пример ответа сервера в формате XML
+<file xml>
+<?xml version="1.0" encoding="UTF-8"?>
+<root>
+   <success>1</success>
+   <delivery_types>
+      <type>
+         <id>1</id>
+         <name>Самовывоз</name>
+      </type>
+   </delivery_types>
+</root>
+</file>
+===== Пример запроса на добавление данных =====
+Пример запроса на добавление заказа:
+ http://mycompany.virtpos.ru/api/orders/add_order?apikey=MySecret&format=xml&id=1
+==== Параметры запроса ====
+Параметры, которые не отмечены как **get only**, могут быть переданы как get- или как post-параметры.
+  * **apikey** - Секретный ключ для доступа к данным. Обязательный параметр.
+  * **format** (get only) - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр.
+  * **id** (get only) - код клиента, для которого требуется добавить заказ. Обязательный параметр.
+  * **external_id** (get only) - (опционально) код клиента во внешней системе, работает аналогично параметру **id**
+  * **order** - непосредственно заказ, в формате JSON.
+Пример параметра order:
+<file JSON>
+{
+   "shipping_address": "Дом 3, корпус 5",
+   "shipping_cost": "130.00",
+   "comment": "После шести",
+   "pickup_from_warehouse_id": "2",
+   "delivery_type_id": "1",
+   "payment_type_id": "1",
+   "items": [
+      {
+         "item_id": "787",
+         "quantity": "2.000",
+         "unit_base_price": "320.72",
+         "discount": "0"
+      },
+      {
+         "item_id": "789",
+         "quantity": "3.450",
+         "unit_base_price": "100.10",
+         "discount": "10.2"
+      }
+   ]
+}
+</file>
+==== Ответ сервера ====
+В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info
 ==== Пример ответа сервера ====
@@ Строка 35: / Строка 197: @@
 <root>
    <success>1</success>
-   <orders>
+   <order>
-      <paid>0</paid>
+      <delivery_type_id>1</delivery_type_id>
+      <payment_type_id>1</payment_type_id>
       <customer_id>3</customer_id>
-      <shipped>0</shipped>
-      <cancelled>0</cancelled>
       <shipping_address>Дом 3, корпус 5</shipping_address>
       <shipping_cost>130.00</shipping_cost>
+      <pickup_from_warehouse_id>2</pickup_from_warehouse_id>
       <pickup_receipt_id />
       <comment>После шести</comment>
+      <items>
+         <item>
+            <item_id>787</item_id>
+            <quantity>2.000</quantity>
+            <unit_base_price>320.72</unit_base_price>
+            <discount>0</discount>
+            <amount>641.44</amount>
+         </item>
+         <item>
+            <item_id>789</item_id>
+            <quantity>3.450</quantity>
+            <unit_base_price>100.10</unit_base_price>
+            <discount>10.2</discount>
+            <amount>335.15</amount>
+         </item>
+      </items>
+   </order>
+</root>
+</file>
+===== Пример запроса на обновление данных =====
+Пример запроса на добавление заказа:
+ http://mycompany.virtpos.ru/api/orders/update_order?apikey=MySecret&format=xml&id=1
+==== Параметры запроса ====
+Параметры, которые не отмечены как **get only**, могут быть переданы как get- или как post-параметры.
+  * **apikey** - Секретный ключ для доступа к данным. Обязательный параметр.
+  * **format** (get only) - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр.
+  * **id** (get only) - id заказа, который требуется обновить. Обязательный параметр.
+  * **external_id** (get only) - (опционально) код заказа во внешней системе, работает аналогично параметру **id**
+  * **order** - непосредственно данные заказа, которые требуется обновить, в формате JSON.
+Пример параметра order (можно обновить любые параметры заказа доступные через /api/orders/):
+<file JSON>
+{
+   "paid": 1,
+   "shipped": 1,
+   "cancelled": 0,
+}
+</file>
+==== Ответ сервера ====
+В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info
+==== Пример ответа сервера ====
+Ниже приведен пример ответа сервера в формате XML
+<file xml>
+<?xml version="1.0" encoding="UTF-8"?>
+<root>
+   <success>1</success>
+   <order>
+      <id>1</id>
+      <paid>0</paid>
+      <customer_id>1928</customer_id>
+      <shipped>0</shipped>
+      <cancelled>0</cancelled>
+      <shipping_address />
+      <shipping_cost>0.00</shipping_cost>
+      <pickup_receipt_id />
+      <comment />
       <guid />
-      <created_date>2017-08-24 18:45:08</created_date>
+      <created_date>2017-08-24 14:07:06</created_date>
-      <amount>976.59</amount>
+      <amount>512.00</amount>
-      <discount>10.20</discount>
+      <discount>0.00</discount>
       <pickup_from_warehouse_id>2</pickup_from_warehouse_id>
       <pickup_from_warehouse_name>Просвещения проспект</pickup_from_warehouse_name>
@@ Строка 54: / Строка 285: @@
       <payment_type_id>1</payment_type_id>
       <payment_type_name>Оплата при получении</payment_type_name>
-      <items>
+   </order>
-         <item_id>789</item_id>
-         <item_name>Коньяк "Анри" 3-летний 40,0% 0,5л</item_name>
-         <image />
-         <quantity>3.450</quantity>
-         <unit_base_price>100.10</unit_base_price>
-         <discount>10.20</discount>
-         <amount>335.15</amount>
-         <item_id>787</item_id>
-         <item_name>Коньяк "Father's Old Barrel' 3-летний 40% 0.5 л.</item_name>
-         <image />
-         <quantity>2.000</quantity>
-         <unit_base_price>320.72</unit_base_price>
-         <discount>0.00</discount>
-         <amount>641.44</amount>
-      </items>
-   </orders>
 </root>
 </file>
+===== Пример запроса на добавление товаров в заказ =====
-===== Пример запроса на добавление =====
+ http://mycompany.virtpos.ru/api/orders/add_orders_item?apikey=MySecret&format=xml&id=1
-Пример запроса на получение данных о точке продаж:
+==== Параметры запроса ====
+Параметры, которые не отмечены как **get only**, могут быть переданы как get- или как post-параметры.
+  * **apikey** - Секретный ключ для доступа к данным. Обязательный параметр.
- http://mycompany.virtpos.ru/api/customer/update?apikey=MySecret&create_if_not_exist=0
+  * **format** (get only) - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр.
-==== Параметры запроса ====
+  * **id** (get only) - id заказа, в котрый необходимо добавить товар. Обязательный параметр.
+  * **external_id** (get only) - (опционально) код заказа во внешней системе, работает аналогично параметру **id**
+  * **items** - непосредственно данные товаров, которые требуется добавить в заказ, в формате JSON.
+Пример параметра items:
+<file JSON>
+[
+   {
+      "item_id": "787",
+      "item_external_id": "787634", //используется для поиска order_item по external_id товара
+      "quantity": "2.000",
+      "unit_base_price": "320.72",
+      "discount": "0"
+   },
+   {
+      "item_id": "789",
+      "item_external_id": "787635", //используется для поиска order_item по external_id товара
+      "quantity": "3.450",
+      "unit_base_price": "100.10",
+      "discount": "10.2"
+   }
+]
+</file>
+==== Ответ сервера ====
+В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info
+==== Пример ответа сервера ====
+Ниже приведен пример ответа сервера в формате XML
+<file xml>
+<?xml version="1.0" encoding="UTF-8"?>
+<root>
+   <success>1</success>
+   <orders>
+      <order>
+         <id>1</id>
+         <paid>0</paid>
+         <customer_id>1928</customer_id>
+         <shipped>0</shipped>
+         <cancelled>0</cancelled>
+         <shipping_address />
+         <shipping_cost>0.00</shipping_cost>
+         <pickup_receipt_id />
+         <comment />
+         <guid />
+         <created_date>2017-08-24 14:07:06</created_date>
+         <amount>512.00</amount>
+         <discount>0.00</discount>
+         <pickup_from_warehouse_id>2</pickup_from_warehouse_id>
+         <pickup_from_warehouse_name>Просвещения проспект</pickup_from_warehouse_name>
+         <delivery_type_id>1</delivery_type_id>
+         <delivery_type_name>Самовывоз</delivery_type_name>
+         <payment_type_id>1</payment_type_id>
+         <payment_type_name>Оплата при получении</payment_type_name>
+         <items>
+            <item>
+               <item_id>787</item_id>
+               <item_name>Коньяк "Father's Old Barrel' 3-летний 40% 0.5 л.</item_name>
+               <image />
+               <quantity>1.000</quantity>
+               <unit_base_price>512.00</unit_base_price>
+               <discount>0.00</discount>
+               <amount>512.00</amount>
+            </item>
+            <item>
+               <item_id>789</item_id>
+               <item_name>Коньяк "Father's Old' 5-летний 40% 0.5 л.</item_name>
+               <image />
+               <quantity>1.000</quantity>
+               <unit_base_price>862.00</unit_base_price>
+               <discount>0.00</discount>
+               <amount>862.00</amount>
+            </item>
+         </items>
+      </order>
+   </orders>
+</root>
+</file>
+===== Пример запроса на обновление товаров в заказе =====
+ http://mycompany.virtpos.ru/api/orders/update_orders_item?apikey=MySecret&format=xml&id=1
+==== Параметры запроса ====
+Параметры, которые не отмечены как **get only**, могут быть переданы как get- или как post-параметры.
   * **apikey** - Секретный ключ для доступа к данным. Обязательный параметр.
-  * **format** - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр.
+  * **format** (get only) - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр.
-  * **id** - код магазина, данные которого надо обновить
+  * **id** (get only) - id заказа, в котором необходимо обновить товар. Обязательный параметр.
-  * **create_if_not_exist** - Если истина, то при неудачном поиске магазин будет добавлен в систему.
+  * **external_id** (get only) - (опционально) код заказа во внешней системе, работает аналогично параметру **id**
-  * **group_name** - Название клиентской группы. Если значение указано, то происходит проверка, есть ли группа с таким именем в справочнике. Если нет, то она будет добавлена. Параметр игнорируется, если указан group_id
-  * Также в качестве параметров могут быть переданы все поля для Клиента (fname, lname, email и т.д.). Поле age(возраст) передавать нельзя - оно рассчитывается автоматически на основе данных о дате рождения клиента.
+  * **items** - непосредственно данные товаров, которые требуется обновить, в формате JSON.
+Пример параметра items:
+<file JSON>
+[
+   {
+      "item_id": "787",
+      "item_external_id": "787634", //используется для поиска order_item по external_id товара
+      "quantity": "2.000",
+      "unit_base_price": "320.72",
+      "discount": "0"
+   },
+   {
+      "item_id": "789",
+      "item_external_id": "787635", //используется для поиска order_item по external_id товара
+      "quantity": "3.450",
+      "unit_base_price": "100.10",
+      "discount": "10.2"
+   }
+]
+</file>
 ==== Ответ сервера ====
-В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info.
+В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info
-Также возвращается id записи, которая была обновлена или добавлена. Флаг isnew равен "1", если запись была создана, и "0" если обновлена.
+==== Пример ответа сервера ====
+Ниже приведен пример ответа сервера в формате XML
-==== Пример ответа сервера ====
 <file xml>
 <?xml version="1.0" encoding="UTF-8"?>
 <root>
-	<success>1</success>
+   <success>1</success>
-	<id>11</id>
+   <orders>
-	<isnew>1</isnew>
+      <order>
+         <id>1</id>
+         <paid>0</paid>
+         <customer_id>1928</customer_id>
+         <shipped>0</shipped>
+         <cancelled>0</cancelled>
+         <shipping_address />
+         <shipping_cost>0.00</shipping_cost>
+         <pickup_receipt_id />
+         <comment />
+         <guid />
+         <created_date>2017-08-24 14:07:06</created_date>
+         <amount>512.00</amount>
+         <discount>0.00</discount>
+         <pickup_from_warehouse_id>2</pickup_from_warehouse_id>
+         <pickup_from_warehouse_name>Просвещения проспект</pickup_from_warehouse_name>
+         <delivery_type_id>1</delivery_type_id>
+         <delivery_type_name>Самовывоз</delivery_type_name>
+         <payment_type_id>1</payment_type_id>
+         <payment_type_name>Оплата при получении</payment_type_name>
+         <items>
+            <item>
+               <item_id>787</item_id>
+               <item_name>Коньяк "Father's Old Barrel' 3-летний 40% 0.5 л.</item_name>
+               <image />
+               <quantity>1.000</quantity>
+               <unit_base_price>512.00</unit_base_price>
+               <discount>0.00</discount>
+               <amount>512.00</amount>
+            </item>
+         </items>
+      </order>
+   </orders>
 </root>
 </file>
-===== updateCard - изменение/добавление дисконтной карты =====
+===== Пример запроса на удаление товаров из заказа =====
-Изменяет существующую (или добавляет новую) дисконтную карту.
-Параметры запроса:
+ http://mycompany.virtpos.ru/api/orders/delete_orders_item?apikey=MySecret&format=xml&id=1
-  * **card_id** - внутренний ID дисконтной карты. Если передан, то карта с указанным ID будет обновлена
-  * **external_id** - ID дисконтной карты во внешней системе (например, в 1С)
-  * **uid** - уникальный номер карты
-  * **card_barcode** - штрих-код карты (цифры для EAN-128). Используется только для поиска карты. Для обновления используйте поле barcode
-  * **create_if_not_exist** - если "1", то будет создана новая карта в том случае, если не удалось найти карту с указанными параметрами. Поиск карты осуществляется по следующему алгоритму. Сначала система ищет карту по внутреннему идентификатору card_id. Если запись не найдена, то происходит поиск по уникальному номеру карты uid. Если запись снова не найден, то по external_id. И, в итоге, по штрихкоду card_barcode.
-  * **uid_ean13** - представление уникального номера uid в виде штрих-кода (нули перед uid, контрольная цифра в после uid). Не рекомендуется использовать этот параметр. Если параметр не передан, он штрих-код будет сгенерирован автоматически.
-  * **barcode** - штрих-код карты. Не рекомендуется использовать этот параметр. Если параметр не передан, он штрих-код будет сгенерирован автоматически.
-  * **medium** - носитель карты. Варианты: "PLASTIC" - пластиковая карта; "MAGNET" - карта с магнитной полосой; "APP" - виртуальная карта в мобильном приложении
-  * **status** - статус карты. Возможные значения: NEW - новая неактивированная карта; ACTIVE - действующая карта; BLOCKED - заблокированная карта
-  * **block_date** - дата блокировки карты
-  * **activate_date** - дата выдачи карты
-  * **type_id** - ID типа карты. Возможные типы карт настраиваются в административной панели системы
-  * **type_name** - Название типа карты. Используется только в том случае, если не передан параметр type_id. Если типа карты с указанным названием еще нет в системе, то он будет создан автоматически
-  * **customer_id** - ID клиента, которому принадлежит эта карта
-  * **customer_external_id** - ID клиента во внешней системе, которому принадлежит эта карта. Используется только в случае, если не передан параметр customer_id
-===== deleteCard - удаление дисконтной карты =====
+==== Параметры запроса ====
-Удаление одной дисконтной карты. Для удаления карты необходимо передать один из следующих параметров:
+Параметры, которые не отмечены как **get only**, могут быть переданы как get- или как post-параметры.
-  * **card_id** - внутренний ID дисконтной карты. Если передан, то карта с указанным ID будет обновлена
+  * **apikey** - Секретный ключ для доступа к данным. Обязательный параметр.
-  * **external_id** - ID дисконтной карты во внешней системе (например, в 1С)
-  * **uid** - уникальный номер карты
-  * **card_barcode** - штрих-код карты (цифры для EAN-128). Используется только для поиска карты. Для обновления используйте поле barcode
+  * **format** (get only) - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр.
+  * **id** (get only) - id заказа, из которого требуется удалить товар. Обязательный параметр.
-===== insertCard - добавление дисконтной карты =====
+  * **external_id** (get only) - (опционально) код заказа во внешней системе, работает аналогично параметру **id**
-Добавление новой дисконтной карты. Параметры запроса аналогичны updateCard
+  * **items** - непосредственно данные товаров, которые требуется удалить, в формате JSON.
+Пример параметра items:
+<file JSON>
+[
+   {
+      "item_id": "789",
+      "item_external_id": "787635", //используется для поиска order_item по external_id товара
+   }
+]
+</file>
+==== Ответ сервера ====
+В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info
+==== Пример ответа сервера ====
+Ниже приведен пример ответа сервера в формате XML
+<file xml>
+<?xml version="1.0" encoding="UTF-8"?>
+<root>
+   <success>1</success>
+   <orders>
+      <order>
+         <id>1</id>
+         <paid>0</paid>
+         <customer_id>1928</customer_id>
+         <shipped>0</shipped>
+         <cancelled>0</cancelled>
+         <shipping_address />
+         <shipping_cost>0.00</shipping_cost>
+         <pickup_receipt_id />
+         <comment />
+         <guid />
+         <created_date>2017-08-24 14:07:06</created_date>
+         <amount>512.00</amount>
+         <discount>0.00</discount>
+         <pickup_from_warehouse_id>2</pickup_from_warehouse_id>
+         <pickup_from_warehouse_name>Просвещения проспект</pickup_from_warehouse_name>
+         <delivery_type_id>1</delivery_type_id>
+         <delivery_type_name>Самовывоз</delivery_type_name>
+         <payment_type_id>1</payment_type_id>
+         <payment_type_name>Оплата при получении</payment_type_name>
+         <items>
+            <item>
+               <item_id>787</item_id>
+               <item_name>Коньяк "Father's Old Barrel' 3-летний 40% 0.5 л.</item_name>
+               <image />
+               <quantity>1.000</quantity>
+               <unit_base_price>512.00</unit_base_price>
+               <discount>0.00</discount>
+               <amount>512.00</amount>
+            </item>
+         </items>
+      </order>
+   </orders>
+</root>
+</file>