Import/export API

API УКМ 5 доступно на кассовом сервере. Порт: 29017.

Описание API актуально для версии API 1.0, кассового сервера версии 1.25.

Совместимость версий API гарантируется в пределах мажорной версии. Т.е. версии 1.0, 1.1, 1.2 и т.д. совместимы, но версии 1.1 и 2.3, например, нет.

Импорт торговых данных

Архитектурные требования

Серверная архитектура кассовой системы диктует определенные требования к правилам загрузки информации из товаро-учетной системы: если во внешней товаро-учетной системе изменяется объект (или создается новый / удаляется ранее существовавший), то информация об этом должна быть передана кассовому серверу (API) только один раз. Далее кассовой сервер организует доставку этой информации до касс, к которым относится объект.

Объекты, которые выгружает торгово-учетная система, могут быть двух типов:

объекты, общие для всех касс торговой сети;
объекты, предназначенные для касс конкретного магазина.

Объекты, общие для всех касс:

- справочник налогов;
- группы товаров (товарная иерархия);
- товары (включая шрихкоды);
- дополнительные параметры товаров;
- пик-листы;
- поставщики/продавцы;
- товары поставщиков/продавцов.

Объекты, общие для касс магазина:

- цены на товары;
- дополнительные цены на товары;
- цены на штрихкоды;
- кассиры;
- продавцы-консультанты).

Кассовая система не осуществляет анализ выгруженной из торговой системы информации на предмет ее отличия от той, которая уже есть в кассовой системе. Соответственно, объем передаваемой информации на кассы определяется объемом информации, выгруженной из торговой системы. Поэтому торговая система должна быть ориентирована на выгрузку только изменившейся в ней информации.

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

Полная выгрузка приводит к абсолютно неоправданной нагрузке на кассовый сервер и сетевую инфраструктуру – в результате, весь пакет будет передан на все кассы торговой сети.

Полная выгрузка допустима для объектов, общих для касс одного магазина (например, цены, кассиры, продавцы).

Оптимальная схема выгрузки – накопление в торговой системе изменений за несколько часов и их выгрузка в кассовую систему.

Надо иметь в виду, что загружаемый объект всегда должен содержать все его признаки (исключение составляют только атрибуты, их наличие необязательно). Под признаками объекта понимаются как его атрибуты, так и прочие сущности, такие как штрих-коды, принадлежность к товарной группе, описание, налоговая группа и др. Имеющаяся запись о каждом признаке будет полностью заменена на новое значение. Если какой-то признак отсутствует в запросе, то, если он обязателен в соответствии со схемой (помечен значком *), то запрос не будет принят системой (возникнет сообщение об ошибке); если признак не обязателен, то его значение будет установлено в значение null. В том числе, это относится к признакам, содержащим множество значений. Например, в информации о товаре есть признак barcodes (штрих-коды). При каждой выгрузке товара в признаке barcodes должны быть перечислены все штрихкоды для данного товара, и прежний перечень будет полностью заменен на новый, в том числе и на пустой.

Массив атрибутов является необязательным. Помимо загрузки, атрибуты также можно присваивать объектам вручную, в веб-интерфейсе кассового сервера УКМ 5. Если загрузить заполненный массив, то атрибуты выставятся на группы. Если загрузить пустой массив, то все атрибуты с группы уберутся. Если выполнить загрузку без массива атрибутов, то изменения атрибутов групп не произойдет (атрибуты останутся такими, как их загрузили ранее или настроили на в веб-интерфейсе сервера УКМ 5 ранее). В свою очередь, при выгрузке с кассового сервера, на кассу выгружаются объекты с полным объемом признаков – с атрибутами или без. Если при загрузке объекта возникает ошибка, то не принимается весь пакет, а не только ошибочный объект.

Технические особенности

Сервер УКМ 5 всегда выступает в роли сервера. Клиентом является товаро-учетная система.
Авторизация не требуется. IT-службы клиента должны обеспечивать безопасность.
Загрузка данных всегда производится партиями. Размер партии ограничен выделенным ресурсами. Рекомендуемый размер партии – 1000 записей.
Рекомендуется загружать данные в один поток. Следующий запрос можно посылать только после получения ответа на предыдущий.
При импорте проверяется соответствие данных схеме, а также наличие дубликатов.
Загрузка объектов (товары, цены, пик-листы и т.д.) всегда происходит в инкрементальном режиме. Т.е. данные о новых объектах прибавляются к уже имеющимся. При этом, признаки тех объектов, которые уже присутствуют в базе сервера, полностью перезаписываются на новые (за исключением атрибутов). Под признаками объекта понимаются как его атрибуты, так и прочие сущности, такие как штрих-коды, принадлежность к товарной группе, описание, налоговая группа и др.
Для удаления данных используется поле deleted, которое присутствует во всех сущностях.
Успешный импорт означает, что запрос сконвертирован во внутренний формат УКМ 5 и передан на дальнейшую обработку. Однако, из этого не следует, что он загружен в базу данных и передан на кассы.

Правила заполнения справочника налогов

На текущий момент, в России существует только один налог, учитываемый в розничной торговле. Это НДС, имеющий 3 ставки: 0%, 10% и 20%.

В некоторых случаях, или владелец ККТ или поставщик товара (в случае реализации по договорам комиссии или агентским договорам) могут быть освобождены от учета НДС, в этом случае товар регистрируется в ККТ по особой ставке «НДС не облагается». Также, для ряда операций товары регистрируются в ККТ по особым «расчетным» ставкам.

Пример заполнения справочника групп налогов (таблица tax_group в базе данных):

Id (код группы)	Tax_id	Percent	Fp_code	Advanced_tax_id	Is_preferential	Примечание
1	1	20			false	НДС=20%
2	1	10			false	НДС=10%
3	1	20		1	false	20/120 (расчетная)
4	1	10		2	false	10/110 (расчетная)
5	1	0			false	НДС=0%
6	1	0			true	НДС не облагается
7	1	5			false	НДС=5%
8	1	7			false	НДС=7%
9	1	5		7	false	5/105 (расчетная)
10	1	7		8	false	7/107 (расчетная)

Значения Percent должны быть целыми числами.

Товары со ставкой НДС в 10% в торговой системе привязаны к группе с id=2.

Товары со ставкой НДС в 20% в торговой системе привязаны к группе с id=1.

Если в товарном справочнике в торговой системе есть товары, облагаемые по ставке НДС=0 (не путать с «НДС не облагается»!), то:

- в справочнике должна быть группа со ставкой НДС=0% и значением Is_preferential=false (в данном примере – id=5).

Если предполагается продажа товара без расчета НДС (например, продажа на кассах юр. лица, освобожденного от уплаты НДС), то:

- в справочнике должна быть группа, «отвечающая» за ставку «НДС не облагается» (в данном примере – id=6) с установленным признаком Is_preferential=true;

- независимо от того, какая группа указана у товара, в чеке он будет зарегистрирован с группой id=6.

Если предполагается получение на кассе предоплаты за товары, то:

- в справочнике должны быть группы, «отвечающие» за расчетные ставки (в данном примере – id=3 и 4, соответственно);

- для групп с «обычными» ставками должны быть указаны соответствующие им расчетные группы (в параметре Advanced_tax_id);

- при получении предоплаты за товар с группой id=2, товар будет зарегистрирован в чеке с группой 4 (для группы id=2 указано значение Advanced_tax_id=4);

- при получении предоплаты за товар с группой id=1, товар будет зарегистрирован в чеке с группой 3 (для группы id=1 указано значение Advanced_tax_id=3).

Если предполагается получение на кассе авансовых платежей (например, продажа подарочного сертификата), то:

- в справочнике должна быть группа, «отвечающая» за расчетную ставку (в данном примере – id=3);

- товар, который регистрируется в чеке для получения аванса, должен иметь признак Аванс;

- если для SKU указана налоговая ставка с признаком Is_preferential=true, то с этой ставкой он и будет регистрироваться в чеке;

- если SKU продается в магазине, для которого задано, что он не является плательщиком НДС, то SKU регистрируется в чеке с налоговой группой, для которой установлено значение Is_preferential=true;

- если для SKU указана налоговая ставка с заполненным значением Advanced_tax_id (в справочнике налоговых групп), то SKU регистрируется с указанной для него налоговой группой;

- если для SKU указана налоговая ставка с незаполненным Advanced_tax_id, то SKU регистрируется налоговой группой, у которой параметр Advanced_tax_id равен группе, указанной у товара.

Следует помнить о том, что для правильной регистрации товаров в ККТ необходимо устанавливать соответствие между налоговыми группами в кассовой программе и в конкретных моделях ККТ. Установка соответствия происходит в разделе fiscalprinter настроек оборудования.

Для справочника налогов, приведенного выше, и разных типов ККТ соответствие должно быть установлено следующим образом:

СП 801-Ф

СП 101-Ф, СП 402-Ф, СП 802-Ф

# соответствие налога в СП ККТ (слева) и налоговой группы в УКМ 5 (справа).

# tax0 – НДС 20;

# tax1 – НДС 10;

# tax2 – НДС 20/120;

# tax3 – НДС 10/110;

# tax4 – НДС 0;

# tax5 – без НДС

taxes: {

tax0 = 1

tax1 = 2

tax2 = 3

tax3 = 4

tax4 = 5

tax5 = 6

defaultTax = 1 # Если у товара не указана налоговая группа берётся максимальный налог (это номер налога в ККТ!)

}

# соответствие налога в СП ККТ (слева) и налоговой группы в УКМ 5 (справа).

# tax1 – НДС 20;

# tax2 – НДС 10;

# tax3 – НДС 20/120;

# tax4 – НДС 10/110;

# tax5 – НДС 0;

# tax6 – без НДС

taxes: {

tax1 = 1

tax2 = 2

tax3 = 3

tax4 = 4

tax5 = 5

tax6 = 6

defaultTax = 1 # Если у товара не указана налоговая группа берётся максимальный налог (это номер налога в ККТ!)

}

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

Реализация в недалеком будущем

По мере развития продукта СуперМаг УКМ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.
2	Подтверждение получения и обработки пачки чеков	PUT	500	Ошибка, описание ошибки.
3	Удаление блокировки	DELETE	200	Ok.
3	Удаление блокировки	DELETE	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 выгружается без изменения.

Внимание! Мапирование кодов средств оплаты не реализовано для запросов по выгрузке смен.

Дерево страниц