apiОбщие сведения

Программный интерфейс (API) VirtualPos позволяет внешним системам — 1С, интернет-магазинам, учётным программам — получать и изменять данные: товары, остатки, продажи, документы. Здесь описаны общие правила: как получить ключ, как вызывать методы и какие бывают ответы. Подробности по каждому методу — в статьях раздела.

Работа с API устроена одинаково для всех методов:

Ключ доступа отображается в панели управления: Администрирование → Настройки → вкладка «API и обмен с 1С». В блоке «API. Универсальный обмен данными» показаны:

Значения только отображаются — создать или перевыпустить ключ из интерфейса нельзя. Если ключ нужно заменить, например из-за утечки, обратитесь в поддержку.

На этой же вкладке — файлы обработок для обмена с 1С и кнопка «Настроить webhook» для отправки уведомлений во внешние системы при событиях в VirtualPos.

Адрес метода состоит из адреса компании, слова api, имени раздела и, при необходимости, действия:

https://[компания].myvirtualpos.ru/api/[раздел]/[действие]

Например:

Действие по умолчанию — получение данных: если действие не указано, вызывается запрос на чтение. Создание, изменение, удаление и другие операции — отдельные действия: update, delete, updateItems, accepting и так далее. Они указаны в статьях по методам. Версии в адресе нет: он не меняется от релиза к релизу.

Ключ передаётся в параметре apikey в каждом запросе. В заголовках ключ не принимается.

Запрос списка товаров методом GET:

curl "https://mycompany.myvirtualpos.ru/api/item?apikey=MySecret&format=json"

Тот же запрос методом POST — параметры в теле, тип содержимого application/x-www-form-urlencoded:

curl -X POST "https://mycompany.myvirtualpos.ru/api/item" \
  -d "apikey=MySecret" \
  -d "format=json"

API использует только два метода HTTP: GET и POST. Ключ apikey и формат format принимаются и в адресной строке, и в теле POST-запроса. Остальные параметры метода читаются по-разному: одни только из адресной строки (в статьях они помечены «get only» или описаны как передаваемые в адресной строке), другие — из обоих мест. Если параметр не подействовал, передайте его в адресной строке. Методов PUT и DELETE нет: удаление — отдельное действие (/api/inflow/delete), а не тип запроса.

Типичные операции одинаковы для большинства разделов:

Для «создать или изменить» запись ищется по id (ид в VirtualPos) или external_id (код во внешней системе, например в 1С). Если записи нет, она создаётся только при параметре create_if_not_exist=1. В ответе приходит id записи и признак isnew, создана ли она.

Сложные данные передаются строкой внутри параметра: например, для массового обновления товаров список записей в формате JSON указывается в параметре data. Формат каждого такого параметра описан в статье метода.

Единого способа порционной выдачи нет — он зависит от метода. Чаще всего встречаются такие:

Формат выбирается параметром format: json (по умолчанию) или xml. Заголовок Accept и расширение в адресе не учитываются. Ответ всегда в кодировке UTF-8, кириллица в JSON не экранируется. В заголовке ответа указан тип содержимого — application/json или application/xml.

В любом ответе есть поле success:

{
  "success": 1,
  "type": "item",
  "last_id": 52,
  "total": 28541,
  "count": 1,
  "items": [
    {
      "item": {
        "id": 52,
        "external_id": "abc123",
        "name": "Шампунь с маслами авокадо и оливы 1000 мл",
        "enabled": 1,
        "barcodes": "4627087168773",
        "vat_percent": -1,
        "created_date": "2017-09-15 11:58:12"
      }
    }
  ]
}

В JSON-ответах каждая запись списка вложена в объект с именем сущности (item) — так JSON соответствует структуре XML.

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <success>1</success>
  <type>item</type>
  <last_id>52</last_id>
  <total>28541</total>
  <count>1</count>
  <items>
    <item>
      <id>52</id>
      <external_id>abc123</external_id>
      <name>Шампунь с маслами авокадо и оливы 1000 мл</name>
      <enabled>1</enabled>
      <barcodes>4627087168773</barcodes>
      <vat_percent>-1</vat_percent>
      <created_date>2017-09-15 11:58:12</created_date>
    </item>
  </items>
</root>

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

{"success": 0, "info": "Access denied. Wrong APIKEY provided ."}

Если указанного метода не существует, сервер вернёт HTTP-код 404 и страницу с описанием ошибки в формате HTML, а не JSON или XML. Проверьте адрес запроса.

Если ошибка произошла уже внутри метода, ответ содержит поле http_status с кодом и message с описанием:

{"success": 0, "http_status": 500, "message": "…"}