Перейти к содержаниюСправка

ReceiptExternal. Загрузка чеков из внешней системы

Метод принимает чек продажи, возврата или покупки в формате JSON и сохраняет его в системе. Он предназначен для загрузки чеков из внешних фискальных систем, например с регистраторов Multisoft. Загруженные чеки появляются в отчётах и в выгрузке Receipt. Продажи.

Как получить ключ, как формируются запросы и какие бывают ответы и ошибки — в статье Общие сведения. Здесь описаны только особенности метода receiptExternal.

Запрос

Один вызов создаёт один чек. Ключ apikey передаётся в адресной строке, а сам чек — в теле POST-запроса в формате JSON (весь запрос целиком, а не параметр формы). Формат ответа выбирается параметром format в адресной строке. 

POST https://[компания].myvirtualpos.ru/api/receiptExternal/addJson?apikey=MySecret
Content-Type: application/json

{
  "type": "SELL",
  "time": "2026-09-26T10:00:00.000Z",
  "inn": "7700000001",
  "serial": "9000001",
  "doc_num": 1,
  "check_num": 1,
  "day_num": 1,
  "user": "Иван",
  "total": "300.00",
  "payment": ["200.00", "100.00"],
  "items": [
    { "name": "Товар 1", "quantity": 2, "price": 100 },
    { "name": "Товар 2", "quantity": 1, "price": 100 }
  ]
}

Поля чека

type Строка. Тип чека. Обязательно: SELL — продажа, SELL_REFUND — возврат продажи, BUY — покупка у клиента, BUY_REFUND — возврат покупки
time Строка. Дата и время чека, например 2026-09-26T10:00:00.000Z (ISO 8601). Обязательно. Время сохраняется по часовому поясу сервера
inn Число. ИНН организации. Обязательно. Если организации с таким ИНН нет, она создаётся автоматически с названием «Неизвестная компания (ИНН …)»
serial Число. Серийный номер фискального регистратора. Обязательно. Если кассы с таким номером нет, она создаётся автоматически как внешняя касса на первой в списке точке продаж с описанием «autocreated from API»
doc_num Целое число. Номер документа по данным регистратора. Обязательно
check_num Целое число. Номер чека в смене. Обязательно
day_num Целое число. Номер смены. Необязателен
user Строка. Кассир. Значение не используется: чек записывается на первого пользователя системы
total Число. Сумма чека. Обязательно
payment Массив чисел. Оплата: первый элемент — наличными, второй (необязателен) — картой. Не должен быть пустым
adj Число. Корректировка чека: положительное значение — наценка, отрицательное — скидка. По умолчанию 0
change Число. Сдача. Необязательно
items Массив строк чека. Обязателен, не должен быть пустым

Строка чека (items)

name Строка. Название товара. Обязательно. Товар ищется по точному названию; если такого товара нет, он создаётся автоматически как обычный товар
price Число. Цена за единицу до корректировки. Обязательно
quantity Число. Количество. По умолчанию 1
adj Число. Корректировка строки: положительное значение — наценка, отрицательное — скидка на всю строку. По умолчанию 0

Сумма строки рассчитывается как price × quantity с учётом корректировки: скидка adj=-10 уменьшает сумму строки на 10.

Что происходит при сохранении.

  • Оплата: если сумма payment отличается от total больше чем на 1 копейку, вся сумма чека записывается как оплата наличными.
  • Кассир: чек записывается на первого пользователя системы, а не на того, кто указан в user.
  • Товары: остатки на складе не списываются и не приходуются, себестоимость строк равна нулю. Автоматически созданные товары не имеют цены в прайс-листах и штрихкодов.
  • Повторы: метод не проверяет, загружался ли такой чек раньше. Повторная отправка создаст дубль, поэтому отправляйте каждый чек один раз и при ошибке сети сверяйтесь с выгрузкой чеков.
  • Организация и касса, созданные автоматически, остаются в системе, даже если сам чек не сохранился из-за ошибки.

Ответ

{"success":1,"id":"386290"}
success 1 — чек сохранён
id Ид созданного чека. Приходит строкой

При ошибке приходит success равный 0 и текст в поле info: 

{"success":0,"info":"Cannot save data. [time]: Incorrect datetime format: not a time"}

Примеры запросов

Задача Тело запроса
Продажа за наличные {«type»:«SELL»,«time»:«2026-09-26T10:00:00Z»,«inn»:«7700000001»,«serial»:«9000001»,«doc_num»:1,«check_num»:1,«user»:«a»,«total»:«100»,«payment»:[«100»],«items»:[{«name»:«Товар»,«price»:100}]}
Продажа со скидкой на строку {…,«total»:«90»,«payment»:[«90»],«items»:[{«name»:«Товар»,«price»:100,«adj»:-10}]}
Смешанная оплата (наличные и карта) {…,«total»:«300»,«payment»:[«200»,«100»],«items»:[…]}
Возврат {«type»:«SELL_REFUND»,…}

Ошибки

Ошибка авторизации и общие ошибки описаны в статье Общие сведения. Ошибки методов приходят с кодом HTTP 200 и success равным 0.

Сообщение Причина Что делать
JSON validation error Тело запроса пусто, не является JSON или содержит пустой объект Передайте корректный JSON в теле запроса
Cannot save data. [поле]: … Поле не прошло проверку: например inn или serial не число, неверные type или time, пустые payment или items, строка без name Исправьте указанное поле. В сообщении указывается первая найденная ошибка
Cannot save data. [inn]: Cannot create new organization … Не удалось создать организацию Создайте организацию в панели управления
Cannot save data. [serial]: Cannot create new terminal … Не удалось создать кассу Создайте кассу в панели управления

Связанные разделы