Marketing crm pro

REST API

документация для интеграции сайтов и приложений
Введение

Выполнение запросов к API осуществляется по следующим принципам:

  1. Запрос делается на адрес BaseUrl + название метода

  2. BaseUrl будет https://***.marketingcrm.online/userapi/ где вместо ***, адрес вашего сервера (уточнить у сотрудника MCRM)

  3. Во всех методах будет передаваться приватный ключ заведения. Имя параметра resto_key.

  4. Во всех методах для конкретного пользователя требуется указать в URL параметр access_token, который получается в результате вызова метода userauth

  5. Время жизни сессии – 2 недели бездействия. При любом действии с использованием access_token ее время жизни продлевается на следующие 2 недели.

  6. Параметры запросов передаются через GET, а данные через POST
То есть для получения списка транзакций у текущего пользователя нужно вызвать:

https://***.marketingcrm.online/userapi/gettransactionlist?resto_key=........&access_token=.......&page_number=1&page_count=50


Идентификатор сессии
Чтобы использовать аналитику посещения сайта нужно установить счетчик.
Код для установки счетчика
Значение server_url и js_key нужно получить у администратора MCRM

<script src="https://***.marketingcrm.online/frame/metric" type="text/javascript"></script>
<script type="text/javascript">
getregKey('js_key');
</script>


Также после установки счетчика становится доступной переменная идентификатор сессии.
Для доступа нужно взять из coockie значение переменной mcrm_sid. Везде, где требуется переменная sid - требуется это значение из coockie

Пример запроса на авторизацию на PHP
//Готовим данные POST для авторизации
$request = array(
    'login' => 'test',
    'password' => '123',
	'sid' => $_COOKIE["mcrm_sid"]
);
        
//Готовим CURL для запроса авторизации
$curlHandle = curl_init('https://***.marketingcrm.online/userapi/userauth?resto_key=333');

curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, $request);

$execResult = curl_exec($curlHandle);

$resultOrder = json_decode($execResult, true);            
print_r($resultOrder);

Результат выполнения будет следующим (для неверных логина и пароля):
Array
(
    [error] => ERROR
    [system_message] => 
    [user_message] => Пользователь не существует
    [access_token] => 
)

Результат успешной авторизации:
Array
(
    [error] => OK
    [system_message] => 
    [user_message] => 
    [access_token] => a51df5f3a17d1ac45220d8b45fbd8a8d
)

register
регистрация пользователя

Переменные ожидаются в POST (см.таблицу ниже)

Важно: в процессе заполнения анкеты нужно вызвать метод API verify, чтобы на указанный телефон была отправлена СМС с кодом, который он добавит в code

Выход:

  • register_status – OK или ERROR
  • access_token – токен после успешной регистрации. Пользователь сразу становится авторизованным. Только при регистрации карт с номером.
    Если номер карты назначается в MCRM, то access_token'а не будет.
  • field_status – статус для каждого поля OK или ERROR, чтобы визуально пометить ошибочные поля.
  • error_list – список ошибок для вывода пользователю.

Успешный запрос
{
	"register_status" : "OK",
	"access_token" : "123",
	"field_status" : {
		"session_id" : "OK",
		"card" : "OK",
		"firstname" : "OK",
		"lastname" : "OK",
		"phone" : "OK",
		"email" : "OK",
		"district_home" : "OK",
		"district_work" : "OK",
		"gender" : "OK",
		"birthdate" : "OK",
		"code" : "OK",
	},
	"error_list" : {}	
}

Ошибочный запрос
{
	"register_status" : "ERROR",
	"access_token" : "",
	"field_status" : {
		"session_id" : "OK",
		"card" : "OK",
		"firstname" : "OK",
		"lastname" : "OK",
		"phone" : "ERROR",
		"email" : "OK",
		"district_home" : "OK",
		"district_work" : "ERROR",
		"gender" : "OK",
		"birthdate" : "ERROR",
		"code" : "OK",
	},
	"error_list" : {
		"email" : "E-mail обязателен для заполнения",
		"phone" : "Введите мобильный телефон в любом формате",
		"district_work" : "Район работы обязателен для заполнения",
		"birthdate" : "Поле день рождение обязательно для заполнения",
	}
}

userauth
авторизация зарегистрированного пользователя

Вход:

  • login (POST) – номер телефона в любом формате
  • password (POST) – пароль
  • sid (POST) – идентификатор сессии
Выход:

  • error – OK, если все хорошо, либо ERROR в случае ошибки.
  • system_message – системное описание ошибки, для логирования на стороне клиента
  • user_message – сообщение об ошибке для отображения пользователю.
  • access_token – токен доступа для всех пользовательских данных.
Важно: после получения access_token он должен быть записан в coockies под именем mcrm_access_token.

Успешный запрос
{
	"error" : "OK",
	"system_message" : "",
	"user_message" : "",
	"access_token" : "123"
}

Ошибочный запрос
{
	"error" : "ERROR",
	"system_message" : "",
	"user_message" : "Ваш номер телефона не зарегистрирован",
	"access_token" : ""
}
openauth
авторизация пользователя без пароля


Вход:
  • login (POST) – номер телефона в любом формате
  • sid (POST) – идентификатор сессии

Выход:
  • error – OK, если все хорошо, либо ERROR в случае ошибки.
  • system_message – системное описание ошибки, для логирования на стороне клиента
  • user_message – сообщение об ошибке для отображения пользователю.

Получение токена:
Токен доступа для пользователя будет отправлен на URL вашего сайта, указанный администратору MCRM. В момент, когда получен ответ на этот запрос, токен уже был отправлен. Вам нужно сохранить его у себя в БД, и использовать в методах, где он требуется.

Данные для коллбэк передаются в теле запроса POST в формате JSON со следующими данными:
  • login - номер телефона 10 цифр, который был в запросе
  • token - токен доступа
  • sign - подтверждение подлинности запроса

Поле sign вычисляется как hash_hmac('sha256', 'token', 'key') где:
  • token - полученный в запроса токен доступа
  • key - выдается администратором MCRM

Пример обработки полученного токена: 
 
function saveToken() { 
 $request = json_decode(file_get_contents('php://input')); 
 $userToken = $request->token; 
 $userLogin = $request->login; 
 $sign = $request->sign; 
 $signKey = 'sign_key';//Получается в MCRM 
 if($sign == hash_hmac('sha256', $userToken, $signKey)) { 
  //Сохраняем себе $userToken для $userLogin и используем в дальнейших запросах 
 } 
}
recover
восстановление пароля

После вызова пользователю будет отправлена СМС с паролем для входа.

Вход:

  • login (POST) – номер телефона или номер карты.
Выход:

  • error – OK, если все хорошо, либо ERROR в случае ошибки.
  • system_message – системное описание ошибки, для логирования на стороне клиента
  • user_message – сообщение об ошибке для отображения пользователю.

Пример ответа
{
	"error" : "OK",
	"system_message" : "",
	"user_message" : "Ваш пароль отправлен по СМС"
}
chpass
изменение пароля

После вызова пользователю будет изменен пароль.

Вход:
password (POST) – Новый пароль
Требуется access_token в GET;

Выход:
error – OK, если все хорошо, либо ERROR в случае ошибки.
system_message – системное описание ошибки, для логирования на стороне клиента
user_message – сообщение об ошибке для отображения пользователю.

Пример ответа
{
	"error" : "OK",
	"system_message" : "",
}
verify
запрос СМС с кодом проверки

Вход:

  • phone (POST) – номер телефона
Выход:

  • error – OK, если все хорошо, либо ERROR в случае ошибки.
  • system_message – системное описание ошибки, для логирования на стороне клиента.
  • user_message – сообщение об ошибке для отображения пользователю.

Пример ответа
{
	"error" : "OK",
	"system_message" : "",
	"user_message" : "На Ваш номер отправлен код"
}

getbalance
получить баланс карты

Вход:

  • sid (POST) – идентификатор сессии (не обязательно)
  • Требуется access_token в GET;


Выход:

  • error – OK, если все хорошо, либо ERROR в случае ошибки.
  • summ – сумма на карте в рублях
  • system_message – системное описание ошибки.

Пример ответа
Ошибка
{
	"error" : "ERROR",
	"summ" : -1,
	"system_message" : "Не найдет пользователь по access_token"
}

Успех
{
	"error" : "OK",
	"summ" : 156,
	"system_message" : ""
}
payorder
оплата бонусами

Вызывается, когда пользователь делает оплату бонусами на сайте.

Вход:

  • sale_number (POST) – номер заказа на сайте
  • summ (POST) – сумма списания
  • promo (POST) – промокод (не обязательно)
  • sid (POST) – идентификатор сессии (не обязательно)
  • Требуется access_token в GET;

Выход:

  • error – OK, если все хорошо, либо ERROR в случае ошибки.
  • system_message – системное описание ошибк
  • user_message – описание ошибки для вывода пользователю

Ошибка
{
	"error" : "ERROR",
	"system_message" : "",
	"user_message" : "Сумма не может быть больше баланса"
}

Успех
{
	"error" : "OK",
	"system_message" : "",
	"user_message" : ""
}
getuserdata
получить пользовательскую анкету

Возвращает пользовательскую анкету в формате JSON

Вход: sid (POST) – идентификатор сессии (не обязательно)
Требуется access_token в GET;

Параметры в JSON:
session_id - не используется
card - номер карты
firstname - фамилия
lastname - имя
phone - номер телефона
email - электронный адрес
city - город
district_home - идентификатор района проживания
district_work - идентификатор района работы
gender - пол
birthdate - день рождения в формате гггг-мм-дд
user_id - уникальный не меняющийся идентификатор пользователя
code - не используется
change - не используется
vipCoefficient - ВИП коэффициент карты в предприятии
osmi_link - ссылка на скачивание персональной wallet-карты
params - массив доп параметров анкеты название-значение.
segments - массив с сегментами пользователя
dateEndOfSubscription - дата окончания действия премиум подписки. Если подписки нет, то параметр отсутствует. Если подписка есть (даже просроченная), то значение это дата и время окончания действия подписки в формате yyyy-mm-dd hh:mm:ss

Пример ответа:
{
  "session_id": null,
  "card": "1240240",
  "firstname": "Иванов",
  "lastname": "Иван",
  "phone": "9029901813",
  "email": "zhnik@akrk.info",
        "city": "Москва",
  "district_home": "20",
  "district_work": "21",
  "gender": "male",
  "birthdate": "1983-08-27",
  "user_id": "666",
  "code": null,
  "change": null,
  "vipCoefficient": "1.5",
  "params": [{
      "parameter": "Name 1",
      "value": "Value 1"
    }, {
      "parameter": "Name 2",
      "value": null
    }
  ],
  "segments": [
        "Виртуальный служебный сегмент",
        "Карты 10%"
    ]
}
userupdate
обновление анкеты пользователя

Функция аналогична register, кроме следующих различий:

Требуется access_token в GET;
Не требуется code;
Не требуется change;
sid (POST) – идентификатор сессии (не обязательно)


savecardparam
Добавить пользователю параметр название-значение.

Вход:
parameter (POST) – имя параметра (обязательно)
value (POST) – значение параметра (не обязательно)
Требуется access_token в GET;



gettransactioncount
Узнать количество транзакций для постраничного вывода

Вход:
Требуется access_token в GET;

Выход:
count – количество транзакций, на основе которого будет сделана пагинация.

Пример ответа:
{
"count" : 122
}

gettransactionlist
получить список транзакций пользователя

Вход:
page_number (GET) – номер страницы с транзакциями. Если не указано, то 1.
page_count (GET) – количество транзакций на страницу. Если не указано, то 50.
Требуется access_token в GET;

Выход:
JSON массив транзакций

Пример ответа: 
[
	{
		"id": 123,
		"request": "",
		"trans_type": 1,
		"resto_id": 1,
		"date": "2018-04-05 14:53",
		"order_summ": 1056,
		"bonus_summ": 10.56,
		"text_comment": "Комментарий к транзакции",
		"account": -1,
		"account_name": "Основной счёт"
	},
	{
		"request": "",
		"id": 124,
		"request": 32167,
		"trans_type": 2,
		"resto_id": 2,
		"date": "2018-04-05 14:53",
		"order_summ": 0,
		"bonus_summ": -67,
		"text_comment": "Комментарий к транзакции",
		"account": 1,
		"account_name": "Акционный счёт"
	}
]
gettransactiondetail
Возвращает детали по конкретной транзакции

Вход:
transaction_id - идентификатор транзакции, полученный в gettransactionlist.
Требуется access_token в GET;

Выход:
Массив строк в чеке.

Структура строки позиции:
category - категория позиции
position_name - название позиции
position_article - артикул (если есть)
price - цена за единицу
sum - сумма за позицию
quantity - количество позиций
coefficient - бонусный коэффициент

Пример ответа:
[
	{
		"category" : "Роллы", 
		"position_name" : "Ролл Дракон",
		"position_article" : "757800", 
		"price" : 250,
		"sum" : 500, 
		"quantity" : 2,
		"coefficient" : 1
	}
]
gettranstypelist
получить список типов транзакций, доступных для текущего предприятия

Пример ответа:
{
	1: "Транзакция.Место", 
	2: "Бонус.Акция", 
	3: "Бонус.Админ"
}
getrestolist
Возвращает список предприятий в сети. Если сети нет, то возвращает массив с одной строкой - по текущему предприятию

Пример ответа:
[
	{"id" : 1, "name" : "Ресторан"},
	{"id" : 2, "name" : "Ресторан 2"},
]
getdistrict
получить список районов

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

Вход: Ничего

Выход:

  • error – OK, если все хорошо, либо ERROR в случае ошибки.
  • system_message – системное описание ошибки, для логирования на стороне клиента.
  • user_message – сообщение об ошибке для отображения пользователю.
  • data – массив районов.

error – OK, если все хорошо, либо ERROR в случае ошибки.

system_message – системное описание ошибки, для логирования на стороне клиента.

user_message – сообщение об ошибке для отображения пользователю.

data – массив районов.

Пример ответа:
{
"error": "OK",
"system_message" : "",
	"user_message" : "",
data: [
{
"id" : "1",
	"name": "Район 1"
},{
	"id" : "2",
"name": "Район 2"
}]
}
getpopup
получить всплывающее окно (pop-up)

Получает сообщение для отображения во всплывающем окне.

Вход:

  • Пусто

Выход:

Либо пустой массив (если окон на отображение нету), либо текст окна в формате JSON:

  • id - идентификатор popup сообщения
  • subject - заголовок popup сообщения
  • message - текст popup сообщения
Сообщение будет выдаваться каждый раз, пока не будет помечено как прочитанное, или не истечет срок показа popup сообщения.




setpopupread
отметить pop-up как прочитанный

Вход:

  • popupid (POST) - идентификатор popup сообщения, полученный при getpopup

Выход:

  • error – OK, если все хорошо, либо ERROR в случае ошибки.
  • system_message – системное описание ошибки.
  • user_message – описание ошибки для вывода пользователю



getspecial
получить сообщения "Специально для Вас"

Вход:

  • Пусто


Выход:

Либо пустой массив (если окон на отображение нету), либо текст окна в формате JSON:

  • subject - заголовок сообщения
  • short_text - краткий текст сообщения
  • full_text - полный текст сообщения
  • image - изображени


ПРОМОКОДЫ
1. BaseURL запроса: https://***.marketingcrm.online/userapi/addpromocode, где *** - адрес сервера MCRM

2. Метод: GET

3. Параметры на входе :

- resto_key – API ключ предприятия
- promocode - промокод
- saleSumm – сумма заказа (нужна для того, чтобы проверить удовлетворяет ли промокод ограничениям по сумме заказа)

4. На выходе выдает json объект при успешной операции:

{"foodID": ExternalID, "sumStart": SumStart, "sumEnd": SumEnd}

Примечание:

ExternalID берется извтаблицыfood_catalog;

foodID – идентификатор блюда на сайте с которого делается запрос к API. Если равен -1, то промокод верный, он принят, но добавление подарочного блюда не предусматривает;

либо при ошибке:
{"error": "описание ошибки"}

5.Описания ошибок:

- "restoID is not set!" если в GET параметрах отсутствует restoID
- "promocode is not set!" если в GET параметрах отсутствует promocode
- "saleSumm is not set!" если в GET параметрах отсутствует saleSumm
- "Блюдо в таблице food_catalog не найдено!"
- "Блюдо в таблице promo_list не найдено!"
- "Промокод не найден"
- "Промолист не найден!"
- Либо текст подсказки из таблицы promo_list либо "Промокод не удовлетворяет условиям!"
    
            $curl_opts = array(
                CURLOPT_FOLLOWLOCATION => true,
                CURLOPT_CONNECTTIMEOUT => 2,
                CURLOPT_TIMEOUT => 60,
                CURLOPT_HEADER => 0,
                CURLOPT_VERBOSE => 0,
                CURLOPT_RETURNTRANSFER => true,  // return result instead of echoing
                CURLOPT_CUSTOMREQUEST => 'GET'
            );
            $curl = curl_init($url);
            $headers[] = 'Accept: */*';
            $headers[] = 'Content-Type: application/json; charset=utf-8';
            $curl_opts[CURLOPT_HTTPHEADER] = $headers;
            foreach ($curl_opts as $curl_opt => $val)
                curl_setopt($curl, $curl_opt, $val);
    
            $response = curl_exec($curl);
            $meta = curl_getinfo($curl);
            $err = curl_error($curl);
            curl_close($curl);
    
            if ($meta['http_code'] >= 400)
                throw new Exception($response);
            if ($err) {
                throw new Exception($err);
            }
            return $response;