POS API: интеграция кассы

POS API МойСклад — это набор розничных сущностей JSON API 1.2 для построения собственной кассы: точка продаж, кассовая смена, чеки продаж и возвратов, движения наличных. Разберём модель данных розницы, жизненный цикл смены и главную боль касс — работу офлайн с последующей синхронизацией.

Модель розницы в МойСклад

Розничный контур строится вокруг точки продаж и кассовой смены, внутри которой оформляются чеки. Основные сущности JSON API 1.2:

Точка продаж связывает организацию (от чьего лица продажа), склад (откуда списывается товар) и кассу. Все чеки и движения денег привязываются к открытой смене этой точки.

Кассовая смена: открытие и закрытие

Продавать можно только в рамках открытой смены. Жизненный цикл прост, но требует строгого порядка:

1. открываем смену — POST /api/remap/1.2/entity/retailshift с указанием точки продаж;
2. оформляем чеки и движения наличных внутри смены;
3. закрываем смену — фиксируем итоги (выручка, количество чеков).

Открытая смена — это ещё и связка с ККТ: реальная касса открывает фискальную смену, а МойСклад ведёт учётную. Их состояния должны совпадать.

Оформление продажи и возврата

Чек — это retaildemand с позициями (positions), привязкой к смене и способом оплаты. В позициях указываются товар/модификация, количество, цена и скидки.

• оплата бывает наличными, картой, предоплатой и смешанной;
• списание товара со склада происходит по проведённому чеку;
• возврат оформляется retailsalesreturn со ссылкой на исходную продажу.

Пример минимального тела продажи:

{"retailShift":{"meta":{...}},"positions":[{"assortment":{"meta":{...}},"quantity":1,"price":150000}]}

Цена в JSON API 1.2 указывается в копейках (price: 150000 = 1500 руб). Это частый источник ошибок — не забывайте про множитель 100.

Движения наличных: внесение и выплата

Касса — это ещё и денежный ящик. Помимо чеков, в смене учитываются движения наличных, не связанные с продажей:

• cashin — внесение (размен в начале смены, инкассация наоборот);
• cashout — выплата (выемка наличных, расходы).

Эти операции влияют на остаток в кассе и попадают в итоги смены. При закрытии смены сумма наличных должна сходиться: начальный остаток + продажи за наличные + внесения − выплаты − возвраты.

Офлайн-режим и синхронизация

Главная инженерная задача кассы — работа без интернета. Магазин не может останавливать продажи из-за сети, поэтому POS должен продавать офлайн и синхронизироваться при появлении связи.

• каждому офлайн-чеку присваивайте локальный уникальный идентификатор для дедупликации;
• отправку делайте идемпотентной — повтор не должен создавать дубль продажи;
• обновление справочников — по изменённым записям (filter=updated>...), а не полной выгрузкой.

Загрузка ассортимента и остатков

Кассе нужны товары с ценами, штрихкодами и остатками — и лучше одним запросом, а не по одной позиции. Для этого в JSON API 1.2 есть объединённая выборка entity/assortment, которая отдаёт товары, модификации, комплекты и услуги вместе.

GET /api/remap/1.2/entity/assortment?filter=stockStore=<склад точки>&limit=1000

• Штрихкоды — поле barcodes, по нему касса ищет товар при сканировании;
• Цены — salePrices с типами цен, выбирайте нужный тип для розницы;
• Остатки — параметр stockStore привязывает остаток к складу точки продаж;
• Пагинация — по 1000 записей через limit/offset.

Полную выгрузку делайте редко (первичная загрузка на устройство), а инкрементальную — по фильтру измерённых записей. Так вы не упираетесь в лимиты частоты запросов и держите локальный кэш свежим.

Связь с фискализацией

Розничная продажа в России сопровождается фискальным чеком по 54-ФЗ. POS API отвечает за учётную часть, а пробитие чека — за ККТ и Фискальный API.

1. оформляем retaildemand в МойСклад;
2. отправляем данные чека на ККТ для фискализации;
3. сохраняем фискальные реквизиты (ФН, ФД, ФП) рядом с продажей.

Важно не «пробить» чек дважды при повторной синхронизации — фискализация должна происходить один раз на продажу, с защитой от дублей на уровне локального идентификатора чека.

Итог

POS API — это розничная часть JSON API 1.2: точка продаж, смена, чеки продаж и возвратов, движения наличных. Ключевые сложности — строгий жизненный цикл смены, цены в копейках, устойчивая офлайн-работа с дедупликацией чеков и корректная связка с фискализацией по 54-ФЗ.

Мы разрабатываем кассовые и розничные интеграции: офлайн-режим с очередью синхронизации, обмен остатками и ценами, связку с ККТ и учётом в МойСклад. Спроектируем архитектуру, которая продаёт даже без сети и не создаёт дублей при восстановлении связи.