CARDPR

Интеграция по API

Версия 2.5.4 от 26.10.2020

Интеграция по API

Версия 2.5.4 от 26.10.2020
При работе по API обязательно хранить базу клиентов в вашей системе.
При получении клиентом электронной карты система CARDPR отправит хук в вашу систему, вам необходимо обработать данный хук и сохранить данные клиента в вашей базе.
Если данные обновятся в вашей системе (например, процент скидки или бонус), вам необходимо отправить хук в CARDPR, система CARDPR обновит карту клиента и отправит на нее push.

Передача данных из CARDPR в вашу CRM

Робот CARDPR вызывает заданный URL CRM.
Ваш адрес должен быть обязательно с HTTPS и по адресу должен быть уже рабочий скрипт. Для установки хука сообщите ваш URL в техподдержку.
Метод 1.1. createCustomer — при регистрации клиентом карты.
https://yourdomain.com/hook_url
Данные:
{
name — имя
surname — фамилия (необязательно)
middlename — отчество (необязательно)
email — электронная почта
phone — мобильный телефон клиента
birthday — дата рождения dd.mm.yyyy (необязательно)
cardNumbers — массив c номерами карт
cardTracks — ассоциативный массив с номерами и треками карт
extra — пользовательские переменные (массив, дополнительно)
promo* — промокод клиента для реферальной программы (дополнительно)
referCustomerPhone* — телефон клиента-реферала (дополнительно)
}
*доступны при подключенных промокодах
Пример:
https://yourdomain.com/hook_url
{
"method": "createCustomer",
"customer": {
"name": "Иван",
"surname": "Петров",
"middlename": "Иванович",
"email": "ivan@ivan.ru",
"phone": "+79111111111",
"birthday": "25.01.1990",
"cardNumbers": ["120"],
"cardTracks": { "120": "876234876234" },
"extra": {
"sex": "male",
"promo": "BBBBB" //промокод, который ввел клиент при регистрации
},
"promo": "AAAAA", //промокод клиента для приглашений
"referCustomerPhone": "+79000000000"
}
}
Обработчик получает данные, проверяет наличие клиента в CRM системе по номеру телефона. Если клиента с таким номером телефона нет, его нужно создать, создать ему карту и вернуть customerId. Если клиент с таким номером телефона есть, нужно обновить данные этого клиента и добавить ему новую карту (заменить, если CRM система не поддерживает несколько карт) и вернуть customerId. Номера карт назначаются на стороне CARDPR и при интеграции необходимо прописать в настройках стартовый номер свободного диапазона карт.
Необходимый ответ от CRM:
customerId — уникальный идентификатор пользователя в вашей CRM.
Пример успешного вызова (HTTP 200):
{ "customerId": "6d2845ff-0a07-11e7-25df-d8d18565926f" }
Пример вызова с ошибкой (HTTP 400):
{ "error": "Bad Request" }
Метод 1.2. readBalance — запрос баланса, необходим для ручного запроса на обновление процентов и баланса на карте клиента.
Пример запроса:
https://yourdomain.com/hook_url
{
"crm_key": "",
"method": "readBalance",
"customer": {
"phone": "+79111111111",
"cardNumbers": ["120"]
}
}
Обработчик должен вернуть баланс/бонус/скидку по указанному клиенту (идентификация по номеру телефона и номеру карты).
Пример ответа:
{
"success": true,
"bonus" : "12.5",
"balance": "5",
"discount": "17.88"
}
Метод 1.3. addBalance — хук на добавление бонусов, необходим для начисления приветственных и реферальных бонусов.
Пример запроса:
https://yourdomain.com/hook_url
{
"crm_key": "",
"method": "addBalance",
"customer": {
"phone": "+79111111111",
"cardNumbers": ["120"],
"sum": 50,
"transactionId": id/guid
}
}
Обработчик должен добавить баланс указанному клиенту (идентификация по номеру телефона и номеру карты).
Пример ответа:
{
"success": true
}

Запросы из вашей CRM в CARDPR

Используется для создания/обновления электронных карт при изменении информации в вашей CRM и для чтения информации из CARDPR.
Метод 2.1. user_create_or_update
Обновление или создание клиента в CARDPR.
URL: https://core.codepr.ru/api/v2/crm/user_create_or_update
Данные (в блоке также можно передавать пользовательские переменные):
{
app_key — ключ приложения
phone — мобильный телефон клиента
email — электронная почта
name — имя
surname — фамилия (необязательно)
middlename — отчество (необязательно)
birthday — дата рождения dd.mm.yyyy (необязательно)
discount — размер скидки в % (по умолчанию 0)
bonus — размер бонуса в % (по умолчанию 0)
balance — количество бонусов (по умолчанию 0)
customerId — идентификатор клиента в вашей CRM (по умолчанию "")
link — ссылка на страницу с формой выдачи карты со "/"
sms — текст SMS-сообщения ("Предлагаем установить карту: %link%")
}
Для генерации уникальной ссылки на именную карту (form_url) необходимо передавать ссылку на страницу с формой в поле link.
В тексте SMS-сообщения %link% будет заменено на уникальную ссылку для получения карты.
Ответ:
{
success — сообщение о создании клиента (bool)
card — сообщение о создании карты (bool)
card_number — номер созданной карты (строка)
card_track — трек созданной карты (строка)
card_url — персональная ссылка на карту (url)
form_url — персональная ссылка на форму (url)
user_hash — hash для персонализации формы выдачи (hash)
}
Пример создания клиента:
https://core.codepr.ru/api/v2/crm/user_create_or_update
{
"app_key" : "76GUHT6HTU7TJ7UT67",
"phone" : "+79111111111",
"email" : "ivan@ivan.ru",
"name" : "Иван",
"surname" : "Петров",
"middlename" : "Иванович",
"birthday" : "11.12.1990",
"discount" : "5",
"bonus" : "0",
"balance" : "0",
"link" : "https://form.cardpr.com/00000000-0000-0000-0000-000000000000/",
"sms" : "Предлагаем установить карту: %link%"
}
Пример текста SMS-сообщения (по ссылке выдается карта без ввода персональных данных):
Предлагаем установить карту: https://form.cardpr.com/00000000-0000-0000-0000-000000000000/?hash=2f10171a33f66f3bc425335690ec880c
Пример отправки push:
https://core.codepr.ru/api/v2/crm/user_create_or_update
{
"app_key" : "76GUHT6HTU7TJ7UT67",
"phone" : "+79111111111",
"push" : "Спецпредложение! Два товара по цене одного."
}
Метод 2.2. read_customer
Получение данных клиента по номеру телефона.
URL: https://core.codepr.ru/api/v2/crm/read_customer
Входные параметры:
{
"app_key": "",
"phone": "",
"invites": bool, //нужна ли реферальная информация
"installs": bool //нужна ли информация об установках карт
}
Формат ответа:
{
"customer": {
"phone": "+79111111111",
"email": "ivan@ivan.ru",
"name": "Иван",
"surname": "Петров",
"middlename": "Иванович",
"birthday": "11.12.1990",
"cardNumbers": [
"120"
],
"cardTracks": {
"120": "876234876234"
},
"cardInstalls": { //информация об установках карт
"120": 1
},
"discount": "5",
"bonus": "0",
"balance": "0",
"invitedBy": "+79111111111",
"invites": [ //реферальная информация
"+79111111112",
"+79111111113"
]
}
}
Метод 2.3. read_customers
Получить список клиентов по дате регистрации.
Параметр "installed":
если параметр не указан – метод вернет всех клиентов;
если параметр равен true – метод вернет клиентов с установленными картами;
если параметр равен false – метод вернет клиентов с неустановленными картами.
Метод возвращает первых 100 клиентов, для получения следующих клиентов необходимо использовать аргумент offset.
URL: https://core.codepr.ru/api/v2/crm/read_customers
Входные параметры:
{
"app_key": "",
"start_date": "datetime", //01.01.2020
"end_date": "datetime", //31.12.2020 23:59:59
"installed": true,
"offset": 0
}
Формат ответа:
{
"customers":
[
"+79111111111",
"+79111111112"
]
}
Метод 2.4. push/create
Создать push-рассылку по всей клиентской базе или по сегменту.
URL: https://core.codepr.ru/api/v2/crm/push/create
{
"app_key": "",
"message": "", //текст push-сообщения
"name": "", //название, отображается в кабинете, необязательный параметр
"segment_uuid": "" //идентификатор сегмента, необязательный параметр
}
Пример ответа:
{
"result": {
"name": "Push#0000",
"uuid": "00000000-0000-0000-0000-000000000000",
"message": "Тестовый пуш!"
}
}
Метод 2.5. push/send
Выполнить push-рассылку.
URL: https://core.codepr.ru/api/v2/crm/push/send
{
"app_key": "",
"push_uuid": "" //идентификатор пуш-рассылки
}
Приложение A. Пример CURL из Linux-консоли (Cygwin для Windows).
curl -d '{"app_key":"", "phone":"", "email":"", "name":"", "surname":"", "middlename":"", "birthday":"", "discount":"", "bonus":"", "balance":""}' -H "Content-Type: application/json" -X POST https://core.codepr.ru/api/v2/crm/user_create_or_update
Приложение B. Пример реализации на PHP.
$url = 'https://core.codepr.ru/api/v2/crm/user_create_or_update';
$post = [
'app_key' => '',
'phone' => '',
'email' => '',
'name' => '',
'surname' => '',
'middlename' => '',
'birthday' => '',
'discount' => '',
'bonus' => '',
'balance' => ''
];

$data_string = json_encode($post);

$options = [
CURLOPT_TIMEOUT => 30,
CURLOPT_POST => 1,
CURLOPT_HEADER => 0,
CURLOPT_URL => $url,
CURLOPT_FRESH_CONNECT => 1,
CURLOPT_RETURNTRANSFER => 1,
CURLOPT_FORBID_REUSE => 1,
CURLOPT_SSL_VERIFYHOST => 0,
CURLOPT_SSL_VERIFYPEER => 0,
CURLOPT_POSTFIELDS => $data_string,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Content-Length: '.strlen($data_string)
]
];

$ch = curl_init();
curl_setopt_array($ch, $options);
$result = curl_exec($ch);

Примечания

1. При работе с API есть лимиты на количество запросов:
Тариф Startup — 1 / сек, 60 / час;
Тариф Base — 1 / сек, 60 / час;
Тариф Advanced — 1 / сек, 600 / час;
Тариф Expert — 1 / сек, 3 600 / час.
Увеличение лимитов по запросу в техподдержку.
2. При получении ошибки сформируйте запрос в техподдержку с предоставлением логов (запрос + ответ).
3. Для передачи данных по клиентам в вашу CRM реализуйте интеграцию согласно группе методов — Передача данных из CARDPR в вашу CRM.