# Общие сведения > Источник: https://wiki.virtualpos.ru/hc/api/overview > Обновлено: 2026-10-11 > Где в программе: Администрирование → Настройки → API и обмен с 1С Программный интерфейс (API) VirtualPos позволяет внешним системам — 1С, интернет-магазинам, учётным программам — получать и изменять данные: товары, остатки, продажи, документы. Здесь описаны общие правила: как получить ключ, как вызывать методы и какие бывают ответы. Подробности по каждому методу — в статьях раздела. ## Общее описание Работа с API устроена одинаково для всех методов: 1. **Получите ключ** — Ключ доступа виден в панели управления, на вкладке «API и обмен с 1С». 1. **Отправьте запрос** — Адрес вида `/api/метод`, ключ и параметры метода. Ключ можно передать в адресной строке (GET) или в теле запроса (POST). 1. **Проверьте результат** — В каждом ответе есть поле `success`: 1 — операция выполнена, 0 — произошла ошибка. 1. **Обработайте данные** — Ответ приходит в формате JSON или XML — на ваш выбор. > **Примечание:** > API работает по протоколу HTTPS. Передавайте запросы на адрес вашей компании, например `https://mycompany.myvirtualpos.ru`. Ограничений по IP-адресам и частоте запросов API не накладывает, но большие выборки лучше запрашивать порциями — как это сделать, описано ниже. ## Получение ключа Ключ доступа отображается в панели управления: **Администрирование → Настройки → вкладка «API и обмен с 1С»**. В блоке «API. Универсальный обмен данными» показаны: - **Адрес сайта для обмена** — Адрес, на который нужно отправлять запросы - **API Key** — Основной ключ для всех методов API - **API Key для загрузки документов** — Отдельный ключ, который подходит только для загрузки файлов поступлений (метод `inflow/upload`) - **Документация** — Ссылка на эту документацию ![Вкладка «API и обмен с 1С»](https://wiki.virtualpos.ru/_media/hc/api/overview/settings-api.png) Значения только отображаются — создать или перевыпустить ключ из интерфейса нельзя. Если ключ нужно заменить, например из-за утечки, обратитесь в поддержку. > **Внимание:** > **Основной ключ даёт полный доступ ко всем данным и всем методам API.** Он один на всю компанию: разделить права между интеграциями или пользователями нельзя. Не публикуйте ключ, не храните его в открытом виде в коде сайта и в системе контроля версий. Если ключ мог попасть к посторонним, сразу свяжитесь с поддержкой. > **Права доступа:** > Вкладка «API и обмен с 1С» доступна пользователям с правом `console.config.api`. На этой же вкладке — файлы обработок для обмена с [1С](https://wiki.virtualpos.ru/hc/integration/1c) и кнопка **«Настроить webhook»** для отправки уведомлений во внешние системы при событиях в VirtualPos. ## Адрес запросов Адрес метода состоит из адреса компании, слова `api`, имени раздела и, при необходимости, действия: ``` https://[компания].myvirtualpos.ru/api/[раздел]/[действие] ``` Например: - `/api/item` — Получить данные о товарах - `/api/item/update` — Создать или изменить товар - `/api/writeoff/deleteItems` — Удалить строки из документа списания Действие по умолчанию — получение данных: если действие не указано, вызывается запрос на чтение. Создание, изменение, удаление и другие операции — отдельные действия: `update`, `delete`, `updateItems`, `accepting` и так далее. Они указаны в статьях по методам. Версии в адресе нет: он не меняется от релиза к релизу. ## Авторизация Ключ передаётся в параметре **apikey** в каждом запросе. В заголовках ключ не принимается. Запрос списка товаров методом GET: ```bash curl "https://mycompany.myvirtualpos.ru/api/item?apikey=MySecret&format=json" ``` Тот же запрос методом POST — параметры в теле, тип содержимого `application/x-www-form-urlencoded`: ```bash curl -X POST "https://mycompany.myvirtualpos.ru/api/item" \ -d "apikey=MySecret" \ -d "format=json" ``` > **Важно:** > Ключ в адресной строке остаётся в журналах веб-серверов и прокси. Поэтому ключ удобнее передавать в теле POST-запроса, а параметры метода — в адресной строке, как указано в статье метода. ## Вызов методов API использует только два метода HTTP: **GET** и **POST**. Ключ `apikey` и формат `format` принимаются и в адресной строке, и в теле POST-запроса. Остальные параметры метода читаются по-разному: одни только из адресной строки (в статьях они помечены «get only» или описаны как передаваемые в адресной строке), другие — из обоих мест. Если параметр не подействовал, передайте его в адресной строке. Методов PUT и DELETE нет: удаление — отдельное действие (`/api/inflow/delete`), а не тип запроса. Типичные операции одинаковы для большинства разделов: | Что нужно сделать | Как вызвать | Пример | | --- | --- | --- | | Получить список записей | `GET /api/[раздел]` | `/api/item?apikey=MySecret` | | Получить одну запись | тот же запрос с параметром `id` или `external_id` | `/api/item?apikey=MySecret&id=1` | | Создать или изменить запись | действие `update` | `/api/item/update?apikey=MySecret&id=1&name=Новое+название` | | Удалить запись | действие `delete` | `/api/writeoff/delete?apikey=MySecret&id=1` | Для «создать или изменить» запись ищется по `id` (ид в VirtualPos) или `external_id` (код во внешней системе, например в 1С). Если записи нет, она создаётся только при параметре `create_if_not_exist=1`. В ответе приходит `id` записи и признак `isnew`, создана ли она. Сложные данные передаются строкой внутри параметра: например, для массового обновления товаров список записей в формате JSON указывается в параметре `data`. Формат каждого такого параметра описан в статье метода. ### Общие параметры - **apikey** — Ключ доступа. Обязателен во всех методах, кроме отдельных служебных - **format** — Формат ответа: `json` (по умолчанию) или `xml` - **id** — Ид записи в VirtualPos - **external_id** — Код записи во внешней системе (1С, сайт). Для склада, товара и поставщика в разных методах есть свои варианты: `ext_warehouseid`, `supplier_external_id` и другие - **create_if_not_exist** — `1` — создать запись, если она не найдена. Используется в действиях `update` - **fields** — Список дополнительных полей в ответе, через двоеточие: `fields=itemname:article`. Допустимые значения указаны в методе ### Постраничная выдача Единого способа порционной выдачи нет — он зависит от метода. Чаще всего встречаются такие: - **from_id** и **limit** — Выдать записи, начиная с указанного ид, не более `limit` штук. В методе `item` максимум 10 000 за запрос. В ответе возвращается `last_id` — с него начинается следующая порция - **page** и **page_size** — Номер страницы (с 1) и размер страницы. В методе `customer` размер — от 10 до 10 000 - **marker** — Метка последней полученной записи вида `время:ид`: в метод `receipt` передайте значение из прошлого ответа, чтобы получить только новые чеки ## Формат ответа Формат выбирается параметром **format**: `json` (по умолчанию) или `xml`. Заголовок `Accept` и расширение в адресе не учитываются. Ответ всегда в кодировке UTF-8, кириллица в JSON не экранируется. В заголовке ответа указан тип содержимого — `application/json` или `application/xml`. В любом ответе есть поле **success**: - **success** — `1` — операция выполнена успешно, `0` — ошибка - **info** — При ошибке — текст с описанием причины - **code** — В некоторых ошибках — служебный код, например `AUTH_ERROR_LOGIN_PWD_INCORRECT` - **type** — Тип данных в ответе, например `item` - **count** — Сколько записей вернулось - **total**, **last_id** — В методах с порционной выдачей — общее число записей и ид последней записи в ответе ### Ответ в формате JSON ```json { "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 ```xml 1 item 52 28541 1 52 abc123 Шампунь с маслами авокадо и оливы 1000 мл 1 4627087168773 -1 2017-09-15 11:58:12 ``` ### Даты и числа - **Даты в запросах** — Формат `ГГГГММДД`, например `20261025`. В некоторых методах допускается `ГГГГММДДЧЧММСС` - **Даты в ответах** — Как правило `2015-07-11 17:16:49`. В чеках — `дд.мм.гггг чч:мм:сс` - **Числа** — Десятичный разделитель — точка, разделителей тысяч нет. Часть чисел приходит строками - **Логические параметры** — Значения `1`, `true`, `on`, `yes` означают «да», остальные — «нет» - **Кодировка** — UTF-8 ## Ошибки > **Важно:** > Ошибки почти всегда приходят с HTTP-кодом **200**. Чтобы понять, выполнена ли операция, проверяйте поле `success` в ответе, а не код ответа HTTP. Пример ответа с ошибкой: ```json {"success": 0, "info": "Access denied. Wrong APIKEY provided ."} ``` | Сообщение | Причина | Что делать | | --- | --- | --- | | Неверные данные для авторизации | В запросе нет параметра `apikey` | Добавьте ключ. В ответе также приходит `code`: `AUTH_ERROR_LOGIN_PWD_INCORRECT` | | Access denied. Wrong APIKEY provided | Ключ не подходит | Проверьте ключ на вкладке «API и обмен с 1С» | | Доступ к системе заблокирован (HTTP 402) | Доступ к компании приостановлен, либо API выключен | Обратитесь в поддержку | | Incorrect date format … | Дата передана в другом формате | Передайте дату как `ГГГГММДД`, например `20261025` | | You have to specify [id] or [external_id] to update record | Для изменения не указан ни `id`, ни `external_id` | Укажите идентификатор или `create_if_not_exist=1` | | Record not found | Запись не найдена | Проверьте `id` или `external_id` | | Field '…' not found | В `fields` указано недопустимое поле | Выберите поле из списка, который показан в сообщении | | Data validation failed | Данные не прошли проверку | Прочитайте подробности в тексте сообщения и исправьте параметры | Если указанного метода не существует, сервер вернёт HTTP-код **404** и страницу с описанием ошибки в формате HTML, а не JSON или XML. Проверьте адрес запроса. Если ошибка произошла уже внутри метода, ответ содержит поле `http_status` с кодом и `message` с описанием: ```json {"success": 0, "http_status": 500, "message": "…"} ``` ## Связанные разделы - [Item. Номенклатура](https://wiki.virtualpos.ru/hc/api/item) — Пример полного описания метода: параметры, ответы, примеры запросов - [Receipt. Продажи](https://wiki.virtualpos.ru/hc/api/receipt) — Получение чеков с разбивкой по позициям - [Store. Остатки товара](https://wiki.virtualpos.ru/hc/api/store) — Получение и обновление остатков на складах - [Интеграция с 1С](https://wiki.virtualpos.ru/hc/integration/1c) — Готовая обработка для обмена с 1С