API УКМ 5 доступно на кассовом сервере. Порт: 29017.
Актуальное описание swagger-схем с возможностью выполнения запросов доступно по адресу: http://ukm5-server:29017/api/v1/import/docs/swagger-ui/index.html?url=/api/v1/import/assets/swagger.json#/.
Описание API актуально для версии API 1.0, кассового сервера версии 1.25.
Совместимость версий API гарантируется в пределах мажорной версии. Т.е. версии 1.0, 1.1, 1.2 и т.д. совместимы, но версии 1.1 и 2.3, например, нет.
Импорт торговых данных
Особенности
- Сервер УКМ 5 всегда выступает в роли сервера. Клиентом является товаро-учетная система.
- Авторизация не требуется. IT-службы клиента должны обеспечивать безопасность.
- Загрузка данных всегда производится партиями. Размер партии ограничен выделенным ресурсами. Рекомендуемый размер партии – 1000 записей.
- Рекомендуется загружать данные в один поток. Следующий запрос можно посылать только после получения ответа на предыдущий.
- При импорте проверяется соответствие данных схеме, а также наличие дубликатов.
- Загрузка данных всегда происходит в инкрементальном режиме. Т.е. новые данные дополняют уже имеющиеся.
- Для удаления данных используется поле deleted, которое присутствует во всех сущностях.
- Успешный импорт означает, что запрос сконвертирован во внутренний формат УКМ 5 и передан на дальнейшую обработку. Однако, из этого не следует, что он загружен в базу данных и передан на кассы.
- Ручные скидки УКМ 5 могут изменять стоимость продажи товара ниже минимальной стоимости товара, в том числе до 0.
Правила заполнения справочника налогов
В УКМ 5 поставщик может иметь признак, что он не является плательщиком НДС. В этом случае, касса использует специальную налоговую ставку. В противном случае, ставка НДС берется из товарного справочника. Такое упрощение было сделано сознательно, т.к. проблема может возникнуть только, если один и тот же поставщик реализует товары как по льготной ставке, так и по полной, что является редким случаем.
На текущий момент, в России существует только один налог, учитываемый в розничной торговле. Это НДС, имеющий 2 ставки: 10% и 20%.
Пример заполнения справочника групп налогов (таблица tax_group в базе данных):
Id (код группы) | Tax_id | Percent | Fp_code | Advanced_tax_id | Is_preferential | Примечание |
1 | 1 | 10 | 5 | false | НДС=10% | |
2 | 1 | 20 | 6 | false | НДС=20% | |
3 | 1 | 0 | false | НДС=0% | ||
4 | 1 | 0 | true | НДС не облагается | ||
5 | 1 | 10 | false | 10/110 | ||
6 | 1 | 20 | false | 20/120 |
Товары со ставкой НДС в 10% в торговой системе привязаны к группе с id=1.
Товары со ставкой НДС в 20% в торговой системе привязаны к группе с id=2.
Если в товарном справочнике в торговой системе есть товары, облагаемые по ставке НДС=0 (не путать с «НДС не облагается»!), то:
- в справочнике должна быть группа со ставкой НДС=0% и значением Is_preferential=false (в данном примере – id=3).
Если предполагается продажа товара без расчета НДС (например, продажа на кассах юр. лица, освобожденного от уплаты НДС), то:
- в справочнике должна быть группа, «отвечающая» за ставку «НДС не облагается» (в данном примере – id=4) с установленным признаком Is_preferential=true;
- независимо от того, какая группа указана у товара, в чеке он будет зарегистрирован с группой id=4.
Если предполагается получение на кассе предоплаты за товары, то:
- в справочнике должны быть группы, «отвечающие» за расчетные ставки (в данном примере – id=5 и 6, соответственно);
- для групп с «обычными» ставками должны быть указаны соответствующие им расчетные группы (в параметре Advanced_tax_id);
- при получении предоплаты за товар с группой id=2, товар будет зарегистрирован в чеке с группой 6 (для группы id=2 указано значение Advanced_tax_id=6);
- при получении предоплаты за товар с группой id=1, товар будет зарегистрирован в чеке с группой 5 (для группы id=1 указано значение Advanced_tax_id=5).
Если предполагается получение на кассе авансовых платежей (например, продажа подарочного сертификата), то:
- в справочнике должна быть группа, «отвечающая» за расчетную ставку (в данном примере – id=6);
- товар, который регистрируется в чеке для получения аванса, должен иметь атрибут Аванс;
- если для SKU указана налоговая ставка с признаком Is_preferential=true, то с этой ставкой он и будет регистрироваться в чеке;
- если SKU продается в магазине, для которого задано, что он не является плательщиком НДС, то SKU регистрируется в чеке с налоговой группой, для которой установлено значение Is_preferential=true;
- если для SKU указана налоговая ставка с заполненным значением Advanced_tax_id (в справочнике налоговых групп), то SKU регистрируется с налоговой группой, указанной в Advanced_tax_id;
- если для SKU указана налоговая ставка с незаполненным Advanced_tax_id, то SKU регистрируется с указанной для него налоговой группой.
Следует помнить о том, что для правильной регистрации товаров в ККТ необходимо устанавливать соответствие между налоговыми группами в кассовой программе и в конкретных моделях ККТ. Установка соответствия происходит в разделе fiscalprinter настроек оборудования.
Например, для ККТ СП-801 и справочника налогов, приведенного выше, соответствие должно быть установлено следующим образом:
# Соответствие налога в ККТ СП и налоговой группы в УКМ 5
# Налоги в ККТ СП-801
# tax0 – НДС 20;
# tax1 – НДС 10;
# tax2 – НДС 0;
# tax3 – без НДС;
# tax4 – 20/120;
# tax5 – 10/110.
taxes: { tax0 = 2 tax1 = 1 tax2 = 3 tax3 = 4 tax4 = 6 tax5 = 5 }
Реализация в недалеком будущем
По мере развития продукта СуперМаг УКМ5, планируется реализация следующих параметров, формальное наличие которых в API-документации на текущий момент не означает, что они функционально реализованы:
/api/v1/import/store/{id}/barcodePrices
isPromoPrice – признак того, что торговая система проводит акцию на данный товар в данном магазине
dateTo – дата и время начала действия цены
dateFrom – дата и время окончания действия цены
/api/v1/import/store/{id}/itemPrices
isPromoPrice – признак того, что торговая система проводит акцию на данный товар в данном магазине
dateTo – дата и время начала действия цены
dateFrom – дата и время окончания действия цены
/api/v1/import/items
descr – подробное описание товара
/api/v1/import/itemProperties
showToCashier – показывать свойство на экране кассира
printOnReceipt – печатать значение свойства в чеке
/api/v1/import/taxGroups
fpCode – код налоговой группы в фискальном устройстве.
Экспорт продаж
Особенности
Экспорт продаж может происходить двумя способами:
1. Сервер УКМ 5 работает как клиент для сервера товаро-учетной системы. Т.е. в товаро-учетной системе должен быть REST API-сервис, который реализует следующую схему запросов:
/api/v1/export/receipt – Экспорт чеков. Этот метод должен быть реализован на внешнем сервере.
/api/v1/export/shift – Экспорт смены с чеками. Этот метод должен быть реализован на внешнем сервере.
/api/v1/export/moneyOperation – Экспорт операций с денежным ящиком. Этот метод должен быть реализован на внешнем сервере.
- Данные выгружаются из kafka. Для работы требуется, чтобы была включена передача данных с касс через kafka.
- Смены выгружаются по факту закрытия вместе со всеми чеками, которые были в каждой смене. При этом, чеки запрашиваются из базы данных. Если в базе данных не хватает чеков, смена не будет выгружаться.
- Данные выгружаются последовательно, в порядке прихода с касс. Если при выгрузке данных возникает внутренняя ошибка (например, не все чеки по смене пришли на сервер), данные перекладываются в отдельный топик, чтобы не блокировать выгрузку остальных данных. Фоновый процесс пытается выгрузить данные из топика с ошибками.
- Данные хранятся в kafka 7 дней. Если за это время они не будут выгружены, то будут потеряны.
- Т.к. данные выгружаются по мере их прихода с касс, то информация выгружается только единожды. Если внешней системе нужна информация повторно, то необходимо воспользоваться запросами, приведенными ниже.
2. Сервер УКМ 5 работает как сервер для товаро-учетной системы, т.е. товаро-учетная система обращается к серверу УКМ 5 и получает нужную информацию:
/api/v1/export/receipt/{storeId}/{date} – Экспорт чеков по запросу за дату (по всем кассам магазина).
/api/v1/export/shiftWOReceipts/{storeId}/{date} – Экспорт смен без чеков по запросу за дату (по всем кассам магазина).
/api/v1/export/shift/{storeId}/{posId}/{date} – Экспорт конкретной смены (вместе с чеками) по запросу.
- Данные выгружаются из базы данных.
- Период времени, за который могут быть получены данные, ограничивается периодом хранения их в базе данных сервера.
- Повторный запрос с одинаковыми параметрами приведет к повторному получению той же самой информации – вдобавок к информации, которая появилась на сервере за время, прошедшее с момента первого запроса.
В обоих вариантах взаимодействия авторизация не требуется. Безопасность обеспечивается IT-службами клиента.