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

> Источник: https://wiki.virtualpos.ru/hc/api/receiptexternal  
> Обновлено: 2026-09-26

Метод принимает чек продажи, возврата или покупки в формате JSON и сохраняет его в системе. Он предназначен для загрузки чеков из внешних фискальных систем, например с регистраторов Multisoft. Загруженные чеки появляются в отчётах и в выгрузке [Receipt. Продажи](https://wiki.virtualpos.ru/hc/api/receipt).

> **Примечание:**
> Как получить ключ, как формируются запросы и какие бывают ответы и ошибки — в статье [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview). Здесь описаны только особенности метода `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`.
> - Товары: остатки на складе не списываются и не приходуются, себестоимость строк равна нулю. Автоматически созданные товары не имеют цены в прайс-листах и штрихкодов.
> - Повторы: метод не проверяет, загружался ли такой чек раньше. Повторная отправка создаст дубль, поэтому отправляйте каждый чек один раз и при ошибке сети сверяйтесь с выгрузкой чеков.
> - Организация и касса, созданные автоматически, остаются в системе, даже если сам чек не сохранился из-за ошибки.

## Ответ

```json
{"success":1,"id":"386290"}
```

- **success** — `1` — чек сохранён
- **id** — Ид созданного чека. Приходит строкой

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

```json
{"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",…}` |

## Ошибки

Ошибка авторизации и общие ошибки описаны в статье [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview). Ошибки методов приходят с кодом 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 … | Не удалось создать кассу | Создайте кассу в панели управления |

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

- [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview) — Ключ доступа, вызов методов, форматы ответов и ошибки
- [Receipt. Продажи](https://wiki.virtualpos.ru/hc/api/receipt) — Выгрузка чеков, в том числе загруженных этим методом
- [ZReport. Z-отчёты](https://wiki.virtualpos.ru/hc/api/zreport) — Итоги смен