База знаний
API {Cash}
описание методов для интеграции кассовых систем
БАЗОВЫЕ ПРИНЦИПЫ

Все запросы отправляются в GET формате на адрес: https://host.marketingcrm.online/cashapi/method_name/?key=***

Где:
  • host - название клиентского сервера
  • method_name - имя метода
  • key=*** - ключ, получаемый от администратора MCRM
Параметры добавляются в GET после key. Ответы от сервера отправляются в формате JSON.

В каждом ответе есть параметр status, который принимает значение либо "ok", если запрос успешен, либо "error", если произошла ошибка. В случае с error добавляется параметр "message", где идет описание ошибки.
Состав чека
Эта структуры есть в нескольких запросах. Представляет строку в формате JSON с массивом структур:

  • cat_name - название категории товара.
  • cat_code - идентификатор категории. Если идентификатора нет.
  • name - название товара.
  • price - цена товара за единицу в копейках.
  • count - количество товаров.
  • article - артикул товара. Используется при частичной отмене товаров из чека.
  • coefficient - внешний коэффициент. Если указан, то сумма бонусов будет умножена на этот коэффициент.

Параметр struct (структура чека) может быть передан:

  • Как строка JSON в GET, параметр struct
  • Как параметр struct в POST
  • Как JSON запрос


ТИПЫ ТРАНЗАКЦИЙ

1 - Транзакция.Место (покупка в ресторане или магазине)
2 - Бонус.Акция (Начисление / списание бонусов автоматической механикой)
3 - Бонус.Админ (Начисление / списание бонусов админом MCRM)
4 - Транзакция.Доставка (покупка на сайте)
7 - Транзакция.Online (Покупка для касс неинтегрированных с MCRM)
8 - Покупка авто
9 - Запчасти для авто
10 - Покупка б/у авто
11 - Автосервис


ПРИМЕР:

[{
"cat_name": "Безалкогольные напитки",
"cat_code": "Безалкогольные напитки",
"name": "Молочный коктейль Ванильный",
"price": "15000",
"article": "123",
"count": "2"
}, {
"cat_name": "Суп",
"cat_code": "111-222-333",
"name": "Том-ям с рисом",
"code": "04697",
"price": "60000",
"article": "321",
"count": "1"
}]

getcard
Запрос информации по карте.
Получает анкету карты для вывода кассиру.

Входные параметры:

  • number - номер карты или номер телефона клиенты
Выходные параметры:

  • first_name - имя клиента
  • last_name - фамилия
  • phone - номер телефона
  • card_number - номер карты
  • balance - баланс карты в копейках
  • check_summ - сумма чеков по всем визитам
  • check_count - количнество визитов
  • average_check - средний чек по всем позициям
  • last_date - дата последнего визита в формате "дд.мм.гггг чч:ммм"
  • message - сообщение для кассира
  • dateEndOfSubscription - дата окончания действия премиум подписки. Если подписки нет, то параметр отсутствует. Если подписка есть (даже просроченная), то значение это дата и время окончания действия подписки в формате yyyy-mm-dd hh:mm:ss




calculatebonus
Узнать максимальную сумму для списания, а так же сумму, которая будет начислена после на карту после списания, и баланс карты после транзакции. Вызов функции не приводит к изменению баланса карты.(calculatebonus - это унифицированный запрос. Можно передать, что оплата бонусами 0, чтобы узнать максимальную сумму к списанию. Либо же передать сколько хотим списать, и он выдаст сумму бонусов, которые будут начислены.)

Входные параметры:

  • number - номер карты или номер телефона клиенты
  • order_summ - общая сумма заказа
  • order_pay_bonus - сумма, оплаченная бонусами
  • order_pay_money - сумма, оплаченная деньгами
  • account - идентификатор счета, с которого планируется списание бонусов. По умолчанию:  -1 - основной счет.
  • struct - структура чека (не обязательно)


Выходные параметры:

  • max_spend - максимальная сумма, которую можно будет списать при такой структуре чека
  • bonus_summ - сумма бонуса в копейках, которая будет начислена
  • card_summ - будущий баланс карты




payorder
Оплата чека и начисление бонусов.

Входные параметры:

  • number - номер карты или номер телефона клиенты
  • order_summ - общая сумма заказа
  • order_pay_bonus - сумма, оплаченная бонусами
  • order_pay_money - сумма, оплаченная деньгами
  • account - идентификатор счета, с которого производится списание бонусов. По умолчанию: -1 - основной счет.
  • request - идентификатор запроса. Для контроля дублей. Повторный запрос приведет к ошибке (не обязательно)
  • code - идентификатор чека для отмены (не обязательно). Из R-keeper используется параметр checkguid http://joxi.ru/E2p09nS7og3v2Y
  • officiant - официант, обслуживающий столик (не обязательно)
  • struct - структура чека (не обязательно)
  • promo - промокод (не обязательно)
Структура чека struct может быть передана тремя способами:
1. Через параметр struct в URL 
2. Через тело запроса POST 
3. Через POST параметр struct, если стиль вызова form-data.  

Предпочтителен способ №2.

Выходные параметры

  • bonus_summ - сумма бонуса в копейках
  • card_summ - новый баланс карты




checkpromocode
Работа с промокодом в методе payorder

Принимает параметры:
- promo = строка промокода
- order_summ - сумма заказа
- struct - состав чека

Выдает либо status=ok, либо текст ошибки. Если добавление успешно, и к промокоду есть подарочное блюдо, то к ответу добавляется параметр food, где содержится идентификатор блюда.


rollback
Полная отмена транзакции.

При частичной оплате деньгами и бонусом будут отменены обе транзакции.

Входные параметры:
code - Код для отмены.

Выходные параметры
card_summ - сумма бонусов на карте после отката


articlerollback
Отмена одного товара в чеке.

Входные параметры:

  • code - Код для отмены.
  • article - артикул товара, который нужно отменить
  • count - количество позиций для отмены. Обязательное поле!
Выходные параметры

  • new_bonus_summ - новая сумма бонуса
  • new_check_summ - новая сумма чека
  • card_summ - сумма бонусов на карте после частичного отката




addbonus
Начисление бонусов на счет. 
Начисление административного (ручного) бонуса на карту. 

Входные параметры: 

number - номер карты или номер телефона клиенты 
add_summ - сумма к начислению. Положительное число. 
comment - комментарий к начислению (не обязательно) 
request - уникальный идентификатор запроса (не обязательно) 


Выходные параметры: 

code - код для отмены транзакции, для метода rollback 
card_summ - сумма бонусов на карте после списания




spendbonus
Списание суммы со счета.

Списание денег с карты.

Входные параметры:

  • number - номер карты или номер телефона клиенты
  • spend_summ - сумма к списанию. Положительное число.
  • type - тип транзакции для списания.
  • comment - комментарий к списанию (не обязательно)
  • request - уникальный идентификатор запроса (не обязательно)


Выходные параметры

  • code - код для отмены тразнакции, для метода rollback
  • card_summ - сумма бонусов на карте после списания


getsegmentlist
Получить список сегментов пользователей, доступных для предприятия.

Входные параметры:
Отсутствуют

Выходные параметры:
segments - массив сегментов, с идентификаторами и названиями.



getuserlist
Получить список пользователей в сегменте. .

Входные параметры:

  • segment_id - идентификатор сегмента. Может быть получен из getsegmentlist

Выходные параметры:

users - массив пользователей сегмента, содержащий следующие данные:

  • number - номер карты
  • user_id - идентификатор пользователя
  • phone - телефон пользователя (не является идентификатор, может быть изменен со временем)
  • external_id - идентификатор пользователя во внешней системе