API :: Inflow. Получение/изменение документов Поступления
В системе реализован программный интерфейс для получения, добавления, изменения и удаления данных о документах «Поступление». Данные выгружаются по HTTP протоколу. Формат на выбор - XML или JSON.
Пример запроса на получение данных
Глубина запроса по умолчанию - последние 30 дней. Для изменения глубины необходимо использовать параметр days.
Пример запроса на получение данных о документах «Поступление»:
http://mycompany.virtpos.ru/api/inflow?apikey=MySecret&format=xml
Параметры запроса на получение данных
Все параметры кроме format могут быть переданы как get- или post-параметры. Поле format передается только как get.
- apikey - Секретный ключ для доступа к данным. Обязательный параметр.
- format - формат, в котором сервер отдаст данные. Может принимать значения «xml» или «json». Необязательный параметр.
- date - получение Поступлений на определенную дату. Формат: ГГГГММДД. Необязательный параметр.
- datefrom - получение Поступлений начиная с определенной даты. Формат: ГГГГММДД. Необязательный параметр.
- dateto - получение Поступлений начиная до определенной даты. Формат: ГГГГММДД. Необязательный параметр.
- cdatefrom - получение Поступлений, созданных начиная с определенной даты. Формат: ГГГГММДД. Необязательный параметр.
- cdateto - получение Поступлений, созданных до определенной даты. Формат: ГГГГММДД. Необязательный параметр.
- last_update_date - получение Поступлений, обновленных начиная с определенной даты. Формат: ГГГГММДД. Необязательный параметр.
- warehouse_id - код магазина. для которого надо вернуть поступления. Если не указан, то возвращаются Поступления для всех магазинов. Необязательный параметр.
- ext_warehouse_id - код магазина во внешней системе (например, в 1С). Параметр игнорируется, если передан warehouse_id. Необязательный параметр.
- id - ID документа Поступления. Необязательный параметр. Если не указан, возвращаются все документы.
- external_id - код Поступления во внешней системе (например, в 1С). Если указан, возвращается только документ с указанным кодом.
- last_id - Необязательный параметр. Используется для получения новых документов с момента последнего обмена. Если параметр указан, то передаются все более новые поступления (с бОльшим ID)
- days - задает глубину поиска. Определяет, за какое количество дней от текущей даты надо вернуть документы Поступления. Необязательный параметр.
- withitems - принимает значение «1» или «0». Если «1», то возвращает строки поступления, иначе только «шапки» поступлений.
- withadjustment - принимает значение «1» или «0». Если «1», то возвращает документ «Корректировка поступления»
Ответ сервера
В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info
Пример ответа сервера
Ниже приведен пример ответа сервера в формате XML
<?xml version="1.0" encoding="UTF-8"?> <root> <success>1</success> <type>inflow</type> <days_limit>30</days_limit> <count>1</count> <inflows> <inlow> <id>12</id> <warehouse_id>1</warehouse_id> <docdate>2016-10-25 00:00:00</docdate> <waybill>118</waybill> <supplier_id>1</supplier_id> <supplier_external_id>212</supplier_external_id> <supplier_name>Мой поставщик</supplier_name> <supplier_inn>1234567890123</supplier_inn> <supplier_kpp>111</supplier_kpp> <supplier_type>1</supplier_type> <warehouse_external_id>111</warehouse_external_id> <amount>4545.00</amount> <status>accept</status> <comment/> <created_date>2016-11-18 15:37:55</created_date> <created_by>4</created_by> <last_update_date>2016-11-18 15:39:16</last_update_date> <last_update_by>4</last_update_by> <external_id>321</external_id> <accept_date/> <factura_invoice_num/> <factura_invoice_date/> <UPD_num/> <UPD_date/> <correction_num/> <guid>803ad8b6-688c-11e7-849d-74d435ee6043</guid> <items> <item> <line_id>100</line_id> <item_id>431</item_id> <item_ext_id/> <item_name>Открытка с шоколадом</item_name> <quantity>68.000</quantity> <quantity_expected>68.000</quantity_expected> <barcode/> <price>65.0000</price> <amount>4420.00</amount> <manuf_date/> <lot_number/> <guid>803ad8b6-688c-11e7-849d-74d435ee6043</guid> </item> <item> <line_id>101</line_id> <item_id>668</item_id> <item_ext_id/> <item_name>Шоколад "Большой набор"</item_name> <quantity>1.000</quantity> <quantity_expected>1.000</quantity_expected> <barcode/> <price>125.0000</price> <amount>125.00</amount> <manuf_date/> <lot_number/> <guid>803ad8b6-688c-11e7-849d-74d435ee6043</guid> </item> </items> </inlow> </inflows> <adjustment> <id>5</id> <title>Корректировка поступления к товарной накладной №1</title> <created_date>2017-07-03 16:18:55</created_date> <items> <line_id>11</line_id> <item_id>5</item_id> <item_ext_id>eacf7608-892c-11e4-ab28-005056a7771f</item_ext_id> <item_name>Аджика по-абхазски SUNFEEL 250 г.</item_name> <quantity>5.000</quantity> <quantity_expected>1.000</quantity_expected> <line_id>12</line_id> <item_id>9</item_id> <item_ext_id>7c3cbdc3-8d0f-11e4-ab28-005056a7771f</item_ext_id> <item_name>Адреналин Раш, 0.5 л. ж/б</item_name> <quantity>2.000</quantity> <quantity_expected>1.000</quantity_expected> </items> </adjustment> </root>
Структура ответа сервера
Шапка документа
- id - ID документа поступления
- warehouse_id - ID магазина, на который оформлено поступление
- docdate - дата документа поступления
- waybill - номер документа поступления
- supplier_id - ID Поставщика
- supplier_name - название Поставщика
- supplier_type - код типа Поставщика
- supplier_external_id - код Поставщика во внешней системе учета (например, в 1С)
- warehouse_external_id - код Магазина во внешней системе учета (например, в 1С)
- amount - сумма поставки
- status - статус документа поставки (accept – принят, drаft – черновик)
- created_date - дата создания документа поступления (может не совпадать с датой документа Поступления)
- created_by - ID пользователя, создавшего поступление
- last_update_date - дата и время последнего изменения в поступлении
- last_update_by - ID пользователя, сделавшего последние изменения
- external_id - код Поступления во внешней системе (например, в 1С)
- accept_date - дата принятия товара на склад
- factura_invoice_num - номер счёта-фактуры
- factura_invoice_date - дата счёта-фактуры
- UPD_num - номер документа УПД
- UPD_date - дата документа УПД
- correction_num - номер исправления
- guid - GUID документа
Содержание документа (зависит от настройки загружаемых полей и гибких полей на товарный остаток)
- line_id - сквозной ID строки в транзакциях поступлений
- item_id - ID товарной позиции по номенклатурному справочнику
- item_ext_id - идентификатор товара во внешней системе
- item_name - наименование позиции
- quantity - количество
- quantity_expected - ожидаемое количество
- barcode - штрих-код по накладной поступления
- price - цена поступления
- amount - сумма по строке
- manuf_date - дата изготовления
- expir_date - годен до
- lot_number - характеристика (серия, партия и пр) позиции в накладной поступления
- external_id - идентификатор строки товара в Поступлении во внешней системе
- vat_rate - ставка НДС
- vat_sum - сумма НДС
- sum_minus_vat - сумма по строке товарной позиции без НДС
- guid - GUID строки
- onhand_id - ID товарного остатка
Данные о корректировке поступления (adjustment):
- <id> - ID корректировки поступления
- <title> - наименование корректировки поступления
- <created_date> - дата создания корректировки поступления
- <items> - товары корректировки поступления
- <line_id>11</line_id> - id товара в корректировке поступления
- <item_id>5</item_id> - id товара в VirtualPos
- <item_ext_id>eacf7608-892c-11e4-ab28-005056a7771f</item_ext_id> - уникальный id товара
- <item_name>Аджика по-абхазски SUNFEEL 250 г.</item_name> - название товара
- <quantity>5.000</quantity> - фактическое количество товара в корректировке
- <quantity_expected>1.000</quantity_expected> - ожидаемое количество товара в корректировке
Пример запроса на добавление/изменение данных Поступления
Пример запроса на обновление данных о поступлении:
http://mycompany.virtpos.ru/api/inflow/update/?apikey=MySecret&format=xml&id=1&comment=NewComment
Параметры запроса
Если параметр не помечен как «get only», то он может быть передан как get- или как post-параметр.
- apikey - Секретный ключ для доступа к данным. Обязательный параметр.
- format (get only) - формат, в котором сервер отдаст данные. Может принимать значения «xml» или «json». Необязательный параметр.
- id (get only) - идентификатор поступления, данные которого нужно обновить
- external_id (get only) - код поступления во внешней системе учета (например, в 1С)
- create_if_not_exist (get only) - Если истина, то при неудачном поиске поступление будет добавлен в систему.
- supplier_external_id - код Поставщика во внешней системе. Необязательный параметр; если указан, то будет осуществлен поиск Поставщика по указанному коду и добавление ссылки на него в документ Поступления
- warehouse_external_id - код Магазина во внешней системе. Необязательный параметр; если указан, то будет осуществлен поиск Магазина по указанному коду и добавление ссылки на него в документ Поступления.
- Также в качестве параметров могут быть переданы все поля для поступления
Ответ сервера
В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info.
Также возвращается id записи, которая была обновлена или добавлена.
- Флаг isnew равен «1», если запись была создана, и «0» если обновлена.
Пример ответа сервера
<?xml version="1.0" encoding="UTF-8"?> <root> <success>1</success> <id>1</id> <isnew>0</isnew> </root>
Массовое обновление поступления
Возможно через http://virtualpos.ru/api/inflow/batchUpdate/?apikey=MySecret&format=xml&id=1&batch=batch
Пример batch:
<?xml version="1.0" encoding="UTF-8"?> <root> <inflows> <inlow> <id>12</id> <warehouse_id>1</warehouse_id> <docdate>2016-10-25 00:00:00</docdate> <waybill>118</waybill> <supplier_id>1</supplier_id> <supplier_external_id>212</supplier_external_id> <supplier_name>Мой поставщик</supplier_name> <supplier_inn>1234567890123</supplier_inn> <supplier_kpp>111</supplier_kpp> <supplier_type>1</supplier_type> <warehouse_external_id>111</warehouse_external_id> <amount>4545.00</amount> <status>accept</status> <comment/> <created_date>2016-11-18 15:37:55</created_date> <created_by>4</created_by> <last_update_date>2016-11-18 15:39:16</last_update_date> <last_update_by>4</last_update_by> <external_id>321</external_id> <accept_date/> <factura_invoice_num/> <factura_invoice_date/> <UPD_num/> <UPD_date/> <correction_num/> <items> <item> <line_id>100</line_id> <item_id>431</item_id> <item_ext_id/> <item_name>Открытка с шоколадом</item_name> <quantity>68.000</quantity> <quantity_expected>68.000</quantity_expected> <barcode/> <price>65.0000</price> <amount>4420.00</amount> <manuf_date/> <lot_number/> </item> <item> <line_id>101</line_id> <item_id>668</item_id> <item_ext_id/> <item_name>Шоколад "Большой набор"</item_name> <quantity>1.000</quantity> <quantity_expected>1.000</quantity_expected> <barcode/> <price>125.0000</price> <amount>125.00</amount> <manuf_date/> <lot_number/> </item> </items> </inlow> </inflows> </root>
Пример запроса на удаление данных Поступления
Пример запроса на удаление поступления:
http://mycompany.virtpos.ru/api/inflow/delete/?apikey=MySecret&format=xml&id=1
Параметры запроса
параметры, которые не отмечены как get only, могут быть переданы как get- или как post-параметры.
- apikey - Секретный ключ для доступа к данным. Обязательный параметр.
- format (get only) - формат, в котором сервер отдаст данные. Может принимать значения «xml» или «json». Необязательный параметр.
- id (get only) - идентификатор поступления, которое будет удалено
- external_id (get only) - код поступления во внешней системе учета (например, в 1С)
Ответ сервера
В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info.
Также возвращается id записи, которая была удалена.
Пример ответа сервера
<?xml version="1.0" encoding="UTF-8"?> <root> <success>1</success> <id>1</id> </root>
Пример запроса на принятие накладной по Поступлению
Пример запроса на принятие накладной на поступление:
http://mycompany.virtpos.ru/api/inflow/accepting/?apikey=MySecret&format=xml&id=1
Параметры запроса
параметры, которые не отмечены как get only, могут быть переданы как get- или как post-параметры.
- apikey - Секретный ключ для доступа к данным. Обязательный параметр.
- format (get only) - формат, в котором сервер отдаст данные. Может принимать значения «xml» или «json». Необязательный параметр.
- id (get only) - идентификатор поступления
- external_id (get only) - код поступления во внешней системе учета (например, в 1С)
Ответ сервера
В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info.
Также возвращается id записи.
Пример ответа сервера
<?xml version="1.0" encoding="UTF-8"?> <root> <success>1</success> <id>1</id> </root>
Пример запроса на откат принятия накладной по Поступлению
Пример запроса на откат принятия накладной на поступление (накладная откатывается в состояние «Черновик»):
http://mycompany.virtpos.ru/api/inflow/rollback/?apikey=MySecret&format=xml&id=1
Параметры запроса
параметры, которые не отмечены как get only, могут быть переданы как get- или как post-параметры.
- apikey - Секретный ключ для доступа к данным. Обязательный параметр.
- format (get only) - формат, в котором сервер отдаст данные. Может принимать значения «xml» или «json». Необязательный параметр.
- id (get only) - идентификатор поступления
- external_id (get only) - код поступления во внешней системе учета (например, в 1С)
Ответ сервера
В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info.
Также возвращается id записи.
Пример ответа сервера
<?xml version="1.0" encoding="UTF-8"?> <root> <success>1</success> <id>1</id> </root>
Пример запроса на добавление/изменение данных строки товарной позиции Поступления
Пример запроса на обновление данных о товарной позиции в поступлении:
http://mycompany.virtpos.ru/api/inflow/updateItems/?apikey=MySecret&format=xml&id=1&quantity=2
Параметры запроса
параметры, которые не отмечены как get only, могут быть переданы как get- или как post-параметры.
- apikey - Секретный ключ для доступа к данным. Обязательный параметр.
- format (get only) - формат, в котором сервер отдаст данные. Может принимать значения «xml» или «json». Необязательный параметр.
- id (get only) - идентификатор товарной строки в поступлении, данные которой нужно обновить
- external_id (get only) - код товарной строки в поступлении во внешней системе учета (например, в 1С)
- create_if_not_exist (get only) - Если истина, то при неудачном поиске товарная строка будет добавлена в систему.
- Также в качестве параметров могут быть переданы все поля для строки товарной позиции в поступлении
Ответ сервера
В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info.
Также возвращается id записи, которая была обновлена или добавлена.
- Флаг isnew равен «1», если запись была создана, и «0» если обновлена.
Пример ответа сервера
<?xml version="1.0" encoding="UTF-8"?> <root> <success>1</success> <id>1</id> <isnew>0</isnew> </root>
Пример запроса на удаление данных строки товарной позиции в Поступлении
Пример запроса на удаление товарной строки из документа поступления:
http://mycompany.virtpos.ru/api/inflow/deleteItems/?apikey=MySecret&format=xml&id=1
Параметры запроса
параметры, которые не отмечены как get only, могут быть переданы как get- или как post-параметры.
- apikey - Секретный ключ для доступа к данным. Обязательный параметр.
- format (get only) - формат, в котором сервер отдаст данные. Может принимать значения «xml» или «json». Необязательный параметр.
- id (get only) - идентификатор строки товарной позиции Поступления, которая будет удалена
- external_id (get only) - код строки товарной позиции Поступления во внешней системе учета (например, в 1С)
Ответ сервера
В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info.
Также возвращается id записи, которая была удалена.
Пример ответа сервера
<?xml version="1.0" encoding="UTF-8"?> <root> <success>1</success> <id>1</id> </root>
Пример запроса для загрузки файла Поступления
Пример запроса для загрузки поступления:
Параметры запроса
Если параметр не помечен как get only, то он может быть передан как get- или как post-параметр.
- apikey - Секретный ключ для доступа к данным. Обязательный параметр.
- format (get only) - формат, в котором сервер отдаст данные. Может принимать значения «xml» или «json». Необязательный параметр.
- waybill - товарная накладная. Обязательный параметр.
- docdate - дата документа в формате YYYYMMDD. Необязательный параметр. По умолчанию используется текущая дата.
- encoding - кодировка файла. Необязательный параметр. Может принимать значения «cp1251» и «utf8». По умолчанию «cp1251».
- supplier_id - ID Поставщика. Обязательный параметр.
- supplier_external_id - ID Поставщика во внешней системе. Может быть использован вместо supplier_id.
- warehouse_id - ID Магазина. Обязательный параметр.
- warehouse_external_id - ID Магазина во внешней системе. Может быть использован вместо warehouse_id.
- phone - телефон клиента. Необязательный параметр. Необходим, если из Поступления планируется создать заказ.
- order - номер заказа. Необязательный параметр. Необходим, если из Поступления планируется создать заказ.
- unique - Если равен true, то будет проверено, что такое Поступление еще не загружалось в систему. Если false - проверки не будет. Необязательный параметр. По умолчанию равен true.
Ответ сервера
В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info.
Также возвращается имя временного файла, в который было сохранено загруженное поступление. В дальнейшем из него будет создано поступление в системе.
Пример ответа сервера
<?xml version="1.0" encoding="UTF-8"?> <root> <success>1</success> <files> <0>74e474f98c55579e5f0bc72123da2b68.csv</0> </files> </root>