COM API

COM-Интерфейс

Интеграция возможна на платформах MS Windows (Начиная с XP и выше)

Для начала интеграции достаточно скачать дистрибутив и установить его на кассу или станцию разработки

Данный дистрибутив работает в режимах:
— Передача данных в облако гифтоман (api.giftoman.ru) и отображение результатов после обработки;
— Получение данных из облака и визуализация результатов.

Поддержка интеграции для POS-систем

POS-система Ссылки на файлы/документацию
IIKO Инструкция по установке ПО Гифтоман и плагинов IIKO
Архив с доступными плагинами
Frontol Инструкция по установке ПО Гифтоман и добавления сценария обработки интеграции
Готовый сценарий обработки для Frontol v4
Готовый сценарий обработки для Frontol v5
1C Интеграция
Другие Индивидуальная интеграция
Примеры кода для POS-систем

1C 7.7

ГМ = CreateObject(“Giftoman.ChequeApi”);
ГМ.<Название метода>( Параметры );

1C 8+

ГМ = Новый COMОбъект(“Giftoman.ChequeApi”);
ГМ.<Название метода>( Параметры );

Frontol 4+

var gmObject = new ActiveXObject(“Giftoman.ChequeApi”);
gmObject.<Название метода>( Параметры );
Начало покупки

Метод предназначен для начала оформления покупки по новому чеку.

PurchaseOpen ( [ total, cashier ]);

NAME TYPE DESCRIPTION
total decimal(10,4) (Опционально) Итоговая сумма чека (за вычетом скидки)
(Опционально, если нужен расчёт суммы по PurchaseAddItem())
cashier(60) BSTR (Опционально) ФИО или другое текстовое обозначение продавца

Exceptions

Значение Описание
COMException Не обнаружена директория обмена

Пример

Открытие чека с итоговой суммой 300 рублей .Кассир «Иванова И.И.»

 GM.PurchaseOpen( 300.00, "Иванова И.И." );
Добавление позиции в покупку

Добавление позиции в чек должно вызываться между открытием и закрытием чека. Каждый вызов добавляет отдельную позицию.

PurchaseAddItem( name, count, total, [, category, seller, extId] );

Параметры.

NAME TYPE DESCRIPTION
name BSTR(200) Название товарной позиции
count decimal(10,4) Количество
total decimal(10,4) Итоговая сумма (за вычетом скидки) по товарной позиции (priceDiscounted * count)
category BSTR(200) (Опционально) Строка категории (группы) товара
Можно передавать несколько категорий, разделяя их ‘&&’
seller BSTR(64) (Опционально) Строка имени продавца по позиции (по умолчанию продавец берётся из PurchaseOpen())
extId BSTR(48) (Опционально) Внешний идентификатор товара (из номенклатуры ТС)

Пример

Добавление товарных позиций

GM.PurchaseOpen( 300.00,"Иванова И.И." ); // Открываем покупку
GM.PurchaseAddItem('Пакет-майка',1,5.0); // Регистрируем позицию "Пакет-майка", количество 1, общая стоимость 5.0
GM.PurchaseAddItem('Огурцы зелёные',3,295,'Овощи'); // Регистрируем позицию "Огурцы зелёные", количество 3, общая стоимость 295 в категории "Овощи"
GM.PurchaseClose();  // Закрываем покупку
Добавление атрибута к покупке

Добавление атрибута в покупку должно вызываться между открытием и закрытием чека. Каждый вызов добавляет отдельный атрибут.

PurchaseAddAttr(name, value);

Параметры

NAME TYPE DESCRIPTION
name BSTR (20) Название атрибута
withcard (value: 0,1) — использование карты лояльности
discount (value: decimal(10,4)) — скидка на покупку
bonus_sp (value: decimal(10,4)) — использование бонусных баллов
procspd (value: int) — время обработки чека, сек.
paytype/[cash,card,visa,master, e.t.c.] (value: decimal(10,4)) — разбиение суммы по платежам или указание типа платежа.
возможно использовать свои названия под разработку доп. KPI.
value BSTR (10) значение атрибута (Все значения передаются в виде строки, в том числе и числовые типа скидок и флагов)

Пример

Добавление товарных позиций

GM.PurchaseOpen( 300.00,"Иванова И.И.");
GM.PurchaseAddItem('Пакет-майка',1,5.0);
GM.PurchaseAddAttr('withcard','1'); // Обозначаем, что покупка проходит с картой лояльности Клиента
GM.PurchaseAddAttr('paytype/cash','200'); // Была проведена покупка за 200р наличными
GM.PurchaseAddAttr('discount','100'); // Определяем скидку на данную покупку
GM.PurchaseClose();
Завершение покупки

Только при закрытии покупки система ставит её в очередь отправки в облако.

PurchaseClose([extId])

Параметры

NAME TYPE DESCRIPTION
extId BSTR (40) (Опциональный) Идентификатор чека внутри торговой системы для возможности сквозной идентификации на стороне облака.
Начало возврата

Метод предназначен для начала процедуры возврата.

RefundOpen ([total, extId ]);

name type description
total decimal(10,4) (Опционально) Сумма возврата
(Опционально, если будут указаны возвращаемые позиции)
extId BSTR(40) (Опционально) Идентификатор чека в торговой системе
(При обработке чека в облаке будет связано с начальной покупкой)

Exceptions

Значение Описание
COMException Не обнаружена директория обмена

Пример

Возврат чека с итоговой суммой 300 рублей.

 GM.RefundOpen( 300 ); //Возврат суммы чека в 300 рублей
 GM.RefundClose(); // отправка данных
Добавление позиции в возврат

В случае, если проводится неполный возврат чека (выделенные позиции).

RefundAddItem( name, count, total [, category, seller] );

Параметры.

NAME TYPE DESCRIPTION
name BSTR(200) Название товарной позиции
count decimal(10,4) Количество возвращаемых позиций
total decimal(10,4) Итоговая сумма возврата
category BSTR(200) Категория возвращаемого товара (Опциональный параметр)
Можно передавать несколько категорий, разделяя их ‘&&’
seller BSTR(64) Продавец возвращаемого товара (Опциональный параметр)

Пример

Возврат товарных позиций

GM.RefundOpen( 300.00,"12309283445" ); // Начинаем возврат
GM.RefundAddItem('Огурцы зелёные',3,295, "Овощи СТМ", "Иванов Иван Иванович"); // Регистрируем позицию возврата "Огурцы зелёные", количество 3, общая стоимость 295
GM.RefundClose();  // Закрываем возврат
Закрытие возврата

Отправка данных в облако.

RefundClose()

Параметры отсутствуют

Установка даты-времени покупки/возврата

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

Установка даты-времени должна производиться между открытием и закрытием покупки или открытием и закрытием возврата.

Время должно быть преобразовано к UTC-0

SetDateTime(BSTR datetime);

Параметры

NAME TYPE DESCRIPTION
datetime BSTR (14) Строковый формат даты-времени (yyyyMMddHHmmss) (20160515120159) — UTC-0 время на машине момента регистрации события

Пример

Установка даты-времени покупки

GM.PurchaseOpen( 300.00,"Иванова И.И.");
GM.SetDateTime('20160515120159'); // Устанавливаем время 12:01:59 от 15-го мая 2016-го года
GM.PurchaseClose();
Установка продавца

Данный метод используется для отдельной установки ФИО продавца (как для продажи, так и возврата)

SetCashier(BSTR cashier);

Параметры

NAME TYPE DESCRIPTION
cashier BSTR (64) ФИО продавца

Пример

Установка продавца в чек

GM.PurchaseOpen( 300.00 );
GM.SetCashier('Грозный Иван Васильевич'); 
GM.PurchaseClose();