API УКМ 5 доступно на кассовом сервере. Порт: 29017.
Описание API актуально для версии API 1.0, кассового сервера версии 1.25.
Совместимость версий API гарантируется в пределах мажорной версии. Т.е. версии 1.0, 1.1, 1.2 и т.д. совместимы, но версии 1.1 и 2.3, например, нет.
Импорт торговых данных
Архитектурные требования
Серверная архитектура кассовой системы диктует определенные требования к правилам загрузки информации из товаро-учетной системы: если во внешней товаро-учетной сстеме изменяется объект (или создается новый / удаляется ранее существовавший), то информация об этом должна быть передана кассовому серверу (API) только один раз. Далее кассовой сервер организует доставку этой информации до касс, к которым относится объект.
Объекты, которые выгружает торгово-учетная система, могут быть двух типов:
- объекты, общие для всех касс торговой сети;
- объекты, предназначенные для касс конкретного магазина.
Объекты, общие для всех касс:
- справочник налогов (/api/v1/import/taxes и /api/v1/import/taxGroups);
- группы товаров (товарная иерархия) (/api/v1/import/groupItems);
- товары (включая шрихкоды) (/api/v1/import/items);
- дополнительные параметры товаров (/api/v1/import/itemProperties);
- пик-листы (/api/v1/import/picklists);
- поставщики/продавцы (/api/v1/import/legalEntities);
- товары поставщиков/продавцов (/api/v1/import/legalEntityItemContractors и /api/v1/import/legalEntityItemVendors, соответственно).
Объекты, общие для касс магазина:
- цены на товары (/api/v1/import/store/{id}/itemPrices);
- дополнительные цены на товары (/api/v1/import/store/{id}/AlternativeItemPrices);
- цены на штрихкоды (/api/v1/import/store/{id}/barcodePrices);
- кассиры (/api/v1/import/store/{id}/AlternativeItemPrices);
- продавцы-консультанты (/api/v1/import/store/{id}/sellers).
Надо иметь в виду, что загружаемый объект всегда должен содержать все его атрибуты: имеющаяся запись будет полностью заменена на новое значение. Если какой-то атрибут отсутствует в запросе, то, если он обязателен в соответствии со схемой (помечен значком *), то запрос не будет принят системой (возникнет сообщение об ошибке); если атрибут не обязателен, то его значение будет установлено в значение null. В том числе, это относится к атрибутам, содержащим множество значений. Например, в информации о товаре есть атрибут barcodes. При каждой выгрузке товара в атрибуте barcodes должны быть перечислены все штрихкоды для данного товара и прежний перечень будет полностью заменен на новый, в том числе и на пустой.
Если при загрузке объекта возникает ошибка, то не принимается весь пакет, а не только ошибочный объект.
Технические особенности
- Сервер УКМ 5 всегда выступает в роли сервера. Клиентом является товаро-учетная система.
- Авторизация не требуется. IT-службы клиента должны обеспечивать безопасность.
- Загрузка данных всегда производится партиями. Размер партии ограничен выделенным ресурсами. Рекомендуемый размер партии – 1000 записей.
- Рекомендуется загружать данные в один поток. Следующий запрос можно посылать только после получения ответа на предыдущий.
- При импорте проверяется соответствие данных схеме, а также наличие дубликатов.
- Загрузка данных всегда происходит в инкрементальном режиме. Т.е. новые данные дополняют уже имеющиеся.
- Для удаления данных используется поле deleted, которое присутствует во всех сущностях.
- Успешный импорт означает, что запрос сконвертирован во внутренний формат УКМ 5 и передан на дальнейшую обработку. Однако, из этого не следует, что он загружен в базу данных и передан на кассы.
Правила заполнения справочника налогов
В УКМ 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-службами клиента.
Выгрузка оперативных продаж
Для метода /api/v1/export/receiptPackage существует ряд запросов:
| № | Название запроса | Тип запроса | Параметры запроса | Код ответа | Тело ответа |
|---|---|---|---|---|---|
| 1 | Выгрузка чеков с подтверждением | GET | 200 | Чеки со статусом выгрузки Невыгруженные чеки. Количество чеков в пачке ограничено параметром Размер пачки. | |
| 700 | Имеется блокировка на выгрузку. | ||||
| 500 | Ошибка, описание ошибки. | ||||
| 2 | Подтверждение получения и обработки пачки чеков | PUT | 200 | Ok. | |
| 500 | Ошибка, описание ошибки. | ||||
| 3 | Удаление блокировки | DELETE | 200 | Ok. | |
| 500 | Ошибка, описание ошибки. |
Мапирование кодов средств оплаты
API УКМ 5 допускает использование кастомных кодов для обозначения различных средств оплаты. Для активации механизма мапирования кодов средств оплаты, необходимо обратиться к команде техподдержки УКМ 5.
Механизм мапирования фигурирует в выгружаемой информации по чеку (например, /api/v1/export/receiptPackage) и реализован через переменную pType:
paymentTypeMap: [
{externalId = 1, pType = "cash"},
{externalId = 2, pType = "card"},
{externalId = 3, pType = "certificate"}]
Здесь pType может принимать следующие значения:
- cash – наличные;
- card – банковская карта;
- certificate – подарочный сертификат/подарочная карта;
- PayCard – платежная карта (не банковская);
- other – другие средства оплаты.
Если для pType задано значение, то для всех средств оплаты с данным pType значение Receipt.payments.paymentId заменяется на значение, указанное в параметре externalId.
Если мапирование не задано, то Receipt.payments.paymentId выгружается без изменения.
Внимание! Мапирование кодов средств оплаты не реализовано для запросов по выгрузке смен.