Продажи
Дата написания: 24.06.2020
Методы работы с операциями продажи и возврата товара.
Методы вызываются при продаже и возврате в порядке их описания в документе.
На сервисе возможна настройка различных уровней карт, методы вызываемые при продаже могут учитывать этот механизм. Настройка уровней карт выполняется в личном кабинете организации.
Получение баланса карты
Перед расчетом скидок и начислением бонусов по настроенным на сервисе правилам возможно принять от клиента оплату бонусами в счет покупки. Метод получения баланса принимает на вход позиции чека, идентификатор магазина, зарегистрированного в сервисе. На основании этих данных сервис рассчитывает максимально допустимую сумму оплаты чека бонусами. В расчете участвует:
- Сегмент товаров исключенных из оплаты(настраивается для каждого магазина)
- Максимально допустимый % оплаты
- Сумма скидок применяемых к чеку.
|
POST |
/organization/card/{id}/balance |
|
Параметры |
id //Идентификатор существующей карты |
|
Заголовки |
token // Токен доступа выданный при авторизации |
|
Входной JSON |
{ "shop_id": uuid, //Идентификатор магазина, в котором осуществляется продажа.
"date_calculate_local":1500659675601, // [Необязательный] Дата в UNIX-Time на которую необходимо произвести расчет баланса в местном формате. Необходима для одного из условий разрешений на оплату баллами
"coupon":"coupon_1" // [Необязательный] Номер промокода. Актуален если баланс рассчитывается по правилам списания баллов.
"cheque_items": // Массив строк чека [ { "article" : "2d39df54-3428-4638-82e4-2509309462ac", // Идентификатор товара "summ" : 100.00, // Полная сумма по строке товара, без учета скидок "discount_summ" : 10.99 // Сумма скидок на строку
// Свойства товара, необязательный "property_values": [ { "property_id":"color_id", "value":"Красный" } ... ] }, ... ]
// Способы оплаты, прописанные в условиях срабатывания "payment_types": [ "cash", "card", "certificate" ],
// Сертификаты для оплаты чека "cert_payments": [ { "line_number": 1, "certificate_id":"c2", "sum": 100 }, { "line_number": 2, "certificate_id":"c3", "sum": 10 } ] } |
|
Выходной JSON |
{ "code": 0, "message": "Операция выполнена", "status": "inactive"/"active"/"tempblocked"/"blocked", // Статус карты. Неактивна, Активна, Временная блокировка, Блокировка, соответственно. "block_message": "По заявлению ...", // Комментарий к блокировке. "unblock_date": 12345678097, // Дата автоматического снятия блокировки при состоянии tempblocked "balance": 100500.00, // Полный баланс карты. Информативное поле. Для индикации рекомендуется использовать доступный баланс "balance_available": 500.00, // Доступный баланс. Баллы активированные и не сгоревшие на дату запроса "max_payment": 450.00, // Максимально допустимая сумма оплаты бонусами по переданному документу. Параметр = 0 при неактивной, заблокировнанной и частично заблокированной карте. Метод process_bonus(см. ниже) повторно проконтролирует непревышение допустимой суммы. "card_level_id" : "922eb276-ea39-46f0-8390-67d2c0190c16", // Идентификатор уровня карты "master_card_id": "1b9a31f3-0854-4c99-8bc5-39a327969aa9", // Идентификатор мастер-карты "excluded_articles": [ "dff8f7cb-3b86-421f-a647-dbe1ab137bb3", "48ec83e8-9061-4e9f-86be-9463f66c962b" ] // Массив идентификаторов товаров в чеке, которые нельзя оплачивать бонусами. Клиентское приложение должно учесть эти товары при распределении оплаты по строкам чека. } |
Расчет скидок по документу
Метод вызывается перед внесением оплаты наличными и/или безналичными, после оплаты бонусами.
При вызове выполняется расчет суммовых и подарочных скидок. Метод возвращает список примененных к строкам чека скидок и рассчитанный документ.
|
POST |
/organization/calculate_document |
|
Заголовки |
token // Токен доступа выданный при авторизации |
|
Входной JSON |
{ "card_id":"cda1c1f4-e8d8-4ae0-ad4e-df47c46682ee", //[Необязательный]. Идентификатор существующей карты. "card_code":"112", //[Необязательный]. Магнитный код карты. Используется для расчета скидок по картам сторонних программ лояльности. "card_barcode":"112", //[Необязательный]. Штриховой код карты. Используется для расчета скидок по картам сторонних программ лояльности. "shop_id":"", //Идентификатор магазина, в котором осуществляется продажа. "date_calculate_local":1500659675601, // [Необязательный] Дата в UNIX-Time на которую необходимо произвести расчет скидок в местном формате. Необходима для одного из условий скидки
"bonus_payment":12, // Сколько бонусов было потрачено при оплате. Учитывается, если включена настройка “Вычитать сумму оплаты баллами при расчете скидок”
"coupon":"coupon_1" // [Необязательный] Номер промокода.
"cheque_items": // Список товаров в документе [ { "line_number" :1, // Номер строки документа. "article" :"Art_1", // Идентификатор номенклатуры "name" :"Art_1", // [Необязательный]. Наименование номенклатуры "quantity" :2, // Количество "price" :100, // Цена "discount_summ": 0, // Скидка на позицию номенклатуры "summ" :200, // Сумма без учета скидки(Количество * Цена)
// Свойства товара, необязательный "property_values": [ { "property_id":"color_id", "value":"Красный" } ... ] }, { "line_number" :2, "article" :"Art_2", "name" :"Art_2", "quantity" :1, "price" :150, "discount_summ":0, "summ" :150 } ],
// Способы оплаты, прописанные в условиях срабатывания "payment_types": [ { "type":"cash", "sum":100.5 }, { "type":"card", "sum": 25 }, { "type":"certificate", "sum": 1 } ], // Сертификаты для оплаты чека "cert_payments": [ { "line_number": 1, "certificate_id":"c2", "sum": 100 }, { "line_number": 2, "certificate_id":"c3", "sum": 10 } ]
}
|
|
Выходной JSON |
{ "code": 0, "message": "Операция выполнена", "cheque_items": [ { "line_number" : 1, "article" :"Art_1", "quantity" :2, "price" :100, "summ" :200, // Сумма = сумма без скидки - сумма скидки - сумма оплаты баллами, применившаяся к этой строке "bonus_percet" :6.665, // Рассчитанный сервисом процент скидки "bonus_summ" :13.33 // Рассчитанная сервисом сумма скидки }, { "line_number" :2, "article" :"Art_2", "quantity" :1, "price" :150, "summ" :150, "bonus_percet" :6.667, "bonus_summ" :10 } ], "cheque_discounts": // Таблица примененных скидок. [ { "line_number" :1, // Номер строки на которую была применена скидка "discount_id" :"497323b7-02ff-4b2c-9320-4928e1467104", // Идентификатор скидки "discount_type" :3, // Тип скидки "discount_summ" :13.33, // Сумма скидки "gift_list_id" :"", // Идентификатор сегмента подарков, для скидок с видом подарок. Подарки выдаются и обрабатываются со стороны клиента. "discount_name" :"Сумма 50р без условий", // Наименование скидки "discount_value":50 // Значение указанное при настройке скидки. Зависит от вида скидки. Информативное поле. }, { "line_number" : 2, "discount_id" :"497323b7-02ff-4b2c-9320-4928e1467104", "discount_type" : 3, "discount_summ" :10, "gift_list_id" :"", "discount_name" :"Сумма 50р без условий", "discount_value":50 } ], "cheque_bonus": [ { "line_number": 1, "discount_id":"7bdedbdb-3eb5-4090-853a-61e43cfd08f6", "discount_type": 2, "discount_summ":150, "gift_list_id":"", "discount_name":"rassh", "discount_value":10 } ] } |
Расчет всех скидок по документу [Устаревший]
|
POST |
/organization/calculate |
|
Заголовки |
token // Токен доступа выданный при авторизации |
|
Входной JSON |
{ "card_id":"cda1c1f4-e8d8-4ae0-ad4e-df47c46682ee", //[Необязательный]. Идентификатор существующей карты. "card_code":"112", //[Необязательный]. Магнитный код карты. Используется для расчета скидок по картам сторонних программ лояльности. "card_barcode":"112", //[Необязательный]. Штриховой код карты. Используется для расчета скидок по картам сторонних программ лояльности. "shop_id":"", //Идентификатор магазина, в котором осуществляется продажа. "cheque_items": // Список товаров в документе [ { "line_number" :1, // Номер строки документа. "article" :"Art_1", // Идентификатор номенклатуры "name" :"Art_1", // [Необязательный]. Наименование номенклатуры "quantity" :2, // Количество "price" :100, // Цена "discount_summ": 0, // Скидка на позицию номенклатуры "summ" :200 г // Сумма без учета скидки(Количество * Цена) }, { "line_number" :2, "article" :"Art_2", "name" :"Art_2", "quantity" :1, "price" :150, "discount_summ":0, "summ" :150 } ] }
|
|
Выходной JSON |
{ "code": 0, "message": "Операция выполнена", "cheque_items": [ { "line_number" : 1, "article" :"Art_1", "quantity" :2, "price" :100, "summ" :200, "bonus_percet" :6.665, // Рассчитанный сервисом процент скидки "bonus_summ" :13.33 // Рассчитанная сервисом сумма скидки }, { "line_number" :2, "article" :"Art_2", "quantity" :1, "price" :150, "summ" :150, "bonus_percet" :6.667, "bonus_summ" :10 } ], "cheque_discounts": // Таблица примененных скидок. [ { "line_number" :1, // Номер строки на которую была применена скидка "discount_id" :"497323b7-02ff-4b2c-9320-4928e1467104", // Идентификатор скидки "discount_type" :3, // Тип скидки "discount_summ" :13.33, // Сумма скидки "gift_list_id" :"", // Идентификатор сегмента подарков, для скидок с видом подарок. Подарки выдаются и обрабатываются со стороны клиента. "discount_name" :"Сумма 50р без условий", // Наименование скидки "discount_value":50 // Значение указанное при настройке скидки. Зависит от вида скидки. Информативное поле. }, { "line_number" : 2, "discount_id" :"497323b7-02ff-4b2c-9320-4928e1467104", "discount_type" : 3, "discount_summ" :10, "gift_list_id" :"", "discount_name" :"Сумма 50р без условий", "discount_value":50 } ] } |
Отражение операции
Метод вызывается после расчета документа.
Метод выполняет:
- проверку временной или полной блокировки карты, активности карты(запрещается оплата, возможно только начисление скидок)
- проверку непревышения максимальной суммы оплаты по чеку;
- начисление бонусов по скидкам;
- списание бонусов учтенных в счет оплаты;
- увеличивает сумму накоплений на карте;
- запись в историю продаж.
|
POST |
/organization/process_bonus |
|
Заголовки |
token // Токен доступа выданный при авторизации |
|
Входной JS ON |
{ "operation_type": "sale"/"refund" // Тип операции продажа/возврат соответственно. При возврате начисленные бонусы будут возвращены пропорционально возвращаемым товарам. "card_id": uuid, // Идентификатор существующей карты "shop_id": uuid, // Идентификатор магазина в сервисе. "doc_id" : uuid, // Идентификатор документа во внешней системе. Уникальный идентификатор операции в рамках ВСЕХ систем взаимодействующих с сервисом. "doc_type": 0, // Числовое представление документа во внешней системе. Не обрабатывается сервисом. // Идентификатор кассы во внешней системе. Не обрабатывается сервером. "kkm_name" : "Касса на входе", // Наименование кассы "cheque_number": "1", // Номер документа "author": "Иванов Иван", // Автор документа // Дополнительное описание операции "bonus_payment": 20, // Количество бонусов списываемое в счет оплаты чека. Если карта частично заблокирована, заблокирована или неактивна - значение не должно передаваться или должно быть = 0, в противном случае сервис возвращает ошибку. "doc_id_refund" : uuid, // Идентификатор документа основания. Используется при виде операции "refund" "bonus_refund" : 1.90, // [Необязательный] Количество бонусов, к возврату. Используется при type="refund". Количество возвращаемых бонусов не должно превышать количество начисленных бонусов, иначе счет карты может стать отрицательным. "date_calculate" : 1500659675601, // [Необязательный] Дата в UNIX-Time на которую необходимо произвести расчет скидок "date_calculate_local" : 1500659675601, // [Необязательный] Дата в UNIX-Time на которую необходимо произвести расчет скидок в местном формате. Необходима для одного из условий скидки
"coupon":"coupon_1" // [Необязательный] Номер промокода.
"auto_bonus_refund":true, // [Необязательный] По умолчанию false. При возврате, если взведен, указывает на то, что сервис сам должен списать баллы, начисленные по скидке, на основании документа продажи. Работает по скидкам на строки.
"auto_bonus_payment":true, // [Необязательный] По умолчанию false. При возврате, если взведен, указывает на то, что сервис сам должен начислить баллы, списанные при оплате документа продажи. Работает пропорционально суммам.
// Структура чека, используется сервером для контроля ограничения оплаты. Структура чека должна содержать скидки примененные к документу. [ { "line_number" : 1, "article" : "12456", "name" : "Товар 1", "quantity" : 1.000, "price" : 1.99, "summ" : 200, "discount_summ": 1.90, "property_values": [ { "property_id":"color_id", "value":"Красный" } ... ] }, ... ], "calculate_history": // [Необязательный]. При выполнении сервер дополняет таблицу начисленными бонусами. Передается в том виде, в котором её вернул метод /calculate_document в свойстве cheque_discounts [ { "line_number" : 1, "discount_id" : "guid", "discount_value" : 100.00, } ], "cheque_bonus": [ { "line_number": 1, "discount_id":"7bdedbdb-3eb5-4090-853a-61e43cfd08f6", "discount_type": 2, "discount_summ":150, "gift_list_id":"", "discount_name":"rassh", "discount_value":10 } ], "level_up":true, // [Необязательный]. Булево. true false, Если true тогда повысит уровень на новый. Если false тогда оповестит о наличии уровня, на который можно перейти. Работает аналогично функции level_up.
"level_down":true // [Необязательный]. Булево. true false, Если true тогда понизит уровень. Если false тогда оповестит о наличии уровня, на который можно перейти. Работает аналогично функции level_up. Используется при возврате, после вычитаний накоплений по карте. Понижает строго на 1 порядок. Не понижает уровнеь если: - накоплений хватает для текущего уровня - на текущем уровне стоит обнуление накоплений - нет уровня с более низким приоритетом
"cert_sales": [ { "line_number": 1, // номер строки
"certificate_id":"certificate_1", // номер сертификата
"sum": 1000 // Сумма, которая будет начислена на сертификат, если группа сертификатов предполагает произвольную сумму сертификата. Если сумма фиксированная - эта сумма игнорируется } ], // [Необязательный]. Массив сертификатов для продажи этого документа. При продаже сертификат активируется автоматически.
"cert_payments": [ { "line_number": 1, // номер строки
"certificate_id":"certificate_1", // номер сертификата
"sum": 1000 // Сумма, которая будет списана с сертификата. Оставшаяся часть может сгореть, если группа сертификатов предполагает полное погашение сертификата. Если нет, то остаток останется } ] // [Необязательный]. Массив сертификатов для оплаты этого документа
// Способы оплаты, прописанные в условиях срабатывания "payment_types": [ { "type":"cash", "sum":100.5 }, { "type":"card", "sum": 25 }, { "type":"certificate", "sum": 1 }
] } |
|
Выходной JSON |
{ "code": 0, "message": "Операция выполнена", "bonus_earned": 1000, // Общее количество начисленных бонусов. "bonus_spent" : 500, // Общее количество списанных бонусов. "card_accum" : 500, // Сумма накопления на карте. "actual_balance": 100 // Актуальный баланс на карте "transactions_process_bonus": // Транзакции начисления/списания [ { "id": uuid, "time": unixtime, "type": 0,// 0 - начисление, 1 - списание "sum": 100500.99, // Сумма транзакции },... ] "level_up": { "level_id":"61fc02f3-cef3-49d1-9150-4369b2a5f6a6", "level_name":"1s100k", "accum_amount":295466.27, "accum_level":100 }, "next_level_up": { "level_id":"level_id_1", "level_name":"Уровень 1", "accum_amount":295466.27, "accum_level":150000 }, "level_down": { "level_id":"61fc02f3-cef3-49d1-9150-4369b2a5f6a6", "level_name":"1s100k", "accum_amount":0, "accum_level":100 }, "next_level_down": { "level_id":"61fc02f3-cef3-49d1-9150-4369b2a5f6a6", "level_name":"1s100k", "accum_amount":0, "accum_level":100 } } |
Изменение суммы накоплений по продажам на карте
Накопления на карте определяют условия срабатывания различных видов скидок. Предполагается, что накопления меняются клиентом в момент продажи или возврата в рублях. Однако, в частных случаях можно интерпретировать значение счетчика накопления в других единицах.
ВНИМАНИЕ! Метод process_bonus автоматически увеличивает сумму накоплений на карте. Повторное накопление не требуется.
|
POST |
/organization/card/{id}/accumulate |
|
Параметры |
id //Идентификатор существующей карты |
|
Заголовки |
token // Токен доступа выданный при авторизации |
|
Входной JSON |
{ "reset":false, // Установить или добавить к сумме накоплений на карте. Если значение reset = false, сумма прибавляется к текущему значению. В противном случае устанавливается в качестве нового значения. "sum":100500.99 } |
|
Выходной JSON |
{ "code": 0, "message":"Операция выполнена", "level_up": // [Необязательный] Возвращается, если начисления по карте достигли порога следующего уровня карты. Если механизм уровней карт не используется(пороги не настроены) - параметр не возвращается. { "level_id": “ae4ca021-ad18-49e0-ae16-a390f7ba676b”, // Идентификатор уровня карты "level_name": "Особая карта", // Наименование уровня карты "accum_amount": 100.99, // Сумма накоплений на карте "accum_level": 99.99 // Сумма порога для перехода на следующий уровень } } |
Проверка и перевод карты на новый уровень
Если настроен механизм уровней карт, клиентское приложение может проверить возможность перевода карты на новый уровень и/или перевести карту автоматически.
“Перепрыгнуть” через уровень невозможно, для реализации такой схемы, клиентское приложение должно вызывать метод циклически.
|
POST |
/organization/card/{id}/levelup |
|
Параметры |
id //Идентификатор существующей карты |
|
Заголовки |
token // Токен доступа выданный при авторизации |
|
Входной JSON |
{ "check": true // Если передан или == true, метод не выполняет автоматический переход, вместо этого возвращает секции с описанием возможности перехода(next_level_up). В противном случае - сервис автоматически переводит карту на следующий уровень, возвращая секцию level_up. Секция next_level_up при этом указывает на условия следуюего уровня. } |
|
Выходной JSON |
{ "code": 0, "message":"Операция выполнена", "level_up": // [Необязательный] Возвращается, если начисления по карте достигли порога следующего уровня карты. Если механизм уровней карт не используется(пороги не настроены) - параметр не возвращается. { "level_id": "ae4ca021-ad18-49e0-ae16-a390f7ba676b", // Идентификатор уровня карты "level_name": "Особая карта", // Наименование уровня карты "accum_amount": 100.99, // Сумма накоплений на карте "accum_level": 99.99 // Сумма порога для перехода на следующий уровень }
"next_level_up": // [Необязательный]. Если отсутствует - дальнейшее повышение уровня невозможно. { "level_id": "06fbb3c2-6447-4f4f-a045-a3357d9eee21", // Идентификатор уровня карты, на который был выполнен перевод или следующий уровень. "level_name": "VIP-карта", // Наименование уровня карты "accum_amount": 200.99, // Сумма накоплений на карте "accum_level": 199.99 // Сумма порога для перехода на следующий уровень }
} |
Получить историю продаж
|
GET |
/organization/sale_info |
|
Параметры в запросе |
//[Необязательный]. Идентификатор документа doc_id // Строка
//[Необязательный]. Идентификатор карты card_id // Строка
//[Необязательный]. Идентификатор магазина shop_id // Строка
//[Необязательный]. Дата от которой вести выборку date_from // Число, unixtime в миллисекундах 1538057266000
//[Необязательный]. Дата до которой получить выборку date_to // Число, unixtime в миллисекундах 1538057266000
//[Необязательный]. Дополнительная информация о карте card_info // Булево true / false
//[Необязательный]. Дополнительная информация о клиенте user_info // Булево true / false
//[Необязательный]. Дополнительная информация о транзакциях по документу transaction_info // Булево true / false
//[Необязательный]. Дополнительная информация о транзакциях по документу operation // Строка “sale”, “refund”
//[Необязательный]. Номер страницы которую нужно получить page
//[Необязательный]. Количество строк на страницу, максимум 25 per_page
//[Необязательный]. Булево, возвращать расчет пагинации или нет calculate_count |
|
Заголовки |
token // Токен доступа выданный при авторизации |
|
Выходной JSON |
{ "code": 0, "message":"Операция выполнена", "sales": [ { // Номер строки "row_number": 1,
// Дата продажи "date": 1518618728150,
// Идентификатор документа продажи "doc_id":"fb29e2bb-1193-11e8-a06d-54a05079c2b5",
// Идентификатор документа возврата "doc_id_refund":"", // Идентификатор карты "card_id":"",
// Идентификатор магазина "shop_id":"397180fd-e273-4274-9a50-495e6fa1da0f",
// Идентификатор кассы "cashbox_id":"",
// Наименование кассы "cashbox_name":"1(2)",
// Номер документа продажи "check_number":"00ав-000006",
// Сумма документа продажи "summ":4,
// Сумма документа продажи со скидкой "summ_with_discount":4,
// Операция “sale” || “refund” "operation":"sale",
// Дата продажи (местная) "date_calculate_local": 0,
// Краткая информация о карте "card": { "id":"", "code":"", "barcode":"", "name":"", "active":false, "blocked":false, "card_level_id":"2cc58163-2434-4f39-8c5b-e6704ca18eee" },
// Краткая информация о пользователе "user": { "id":"", "name":"", "login":"", "is_locked": 0, "phone":"", "email":"", "confirmed": 0, "recieve_notifications": 0, "birthdate": 669081600000 },
// Краткая информация о транзакциях по документу "transactions": [ { "id":"8345CC3D-97D4-4BDF-B4BB-BFFC2E13F7F8", "time": 1518618731030, "sum":4, "type": 0 } ],
// Товары по чеку "cheque_items_for_sales": [ { "article_id":"", "item_name":"Пополнение карты БС", "quantity":1, "price":4, "discount":0, "item_info":"" } ] }, … ],
// Пагинация "pagination": { "per_page": 10, // Количество строк на страницу "page" : 1, // Номер текущей страницы "items" : 15275, // Всего записей "pages" : 1528 // Всего страниц } } |