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-службы клиента должны обеспечивать безопасность.
Загрузка данных всегда производится партиями. Размер партии ограничен выделенным ресурсами. Рекомендуемый размер партии – 10 000 записей.
Рекомендуется загружать данные в один поток. Следующий запрос можно посылать только после получения ответа на предыдущий.
При импорте проверяется соответствие данных схеме, а также наличие дубликатов.
Загрузка объектов (товары, цены, пик-листы и т.д.) всегда происходит в инкрементальном режиме. Т.е. данные о новых объектах прибавляются к уже имеющимся. При этом, признаки тех объектов, которые уже присутствуют в базе сервера, полностью перезаписываются на новые (за исключением атрибутов). Под признаками объекта понимаются как его атрибуты, так и прочие сущности, такие как штрих-коды, принадлежность к товарной группе, описание, налоговая группа и др.
Для удаления данных используется поле 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, заполнив поле payVat (запрос /api/v1/import/legalEntities) одним из следующих значений: usn_no_nds (УСН не плательщик НДС), osn (ОСН), usn5 (УСН 5%), usn7 (УСН 7%).

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

По мере развития продукта СуперМаг УКМ5, планируется реализация следующих параметров, формальное наличие которых в API-документации на текущий момент не означает, что они функционально реализованы:

/api/v1/import/store/{id}/barcodePrices

isPromoPrice – признак того, что торговая система проводит акцию на данный товар в данном магазине

dateTo – дата и время начала действия цены

dateFrom – дата и время окончания действия цены

/api/v1/import/store/{id}/itemPrices

isPromoPrice – признак того, что торговая система проводит акцию на данный товар в данном магазине

/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 выгружается без изменения.

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

Расчет налогов

Расчет налогов кассой носит справочный характер и может не совпадать с расчетом налогов, выполненным ККТ (и переданным в ОФД), а также не совпадать с расчетом, сделанным в соответствии с правилами бухгалтерского учета.

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