CARDPR
Зарегистрироваться
Войти
‹ Документация

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

Версия 2.7.6
‹ Документация

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

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

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

Сервис CARDPR вызывает заданный вами URL в настройках интеграции (тип интеграции URL).
Ваш адрес должен быть с HTTPS и по адресу должен быть рабочий скрипт.
Для контроля доступа вы можете использовать "http basic authentication" или "crm_key".
При выборе "http basic authentication" в настройках интеграции укажите ваш логин и пароль.
При выборе "crm_key" в настройках интеграции укажите ваш "crm_key" в поле пароль, при этом поле логин оставьте пустым.
Параметры "ID организации", "ID программы", "ID кошелька" из настроек интеграции передаются
в заголовках запросов "X-organization-id", "X-program-id", "X-wallet-id".
Для контроля доступа также вы можете использовать фильтрацию по IP (194.67.109.166).
На этапе тестирования вы можете использовать сервис https://webhook.site.
Во всех методах номер телефона должен быть в международном формате (E.164 format).
Метод 1.1. createCustomer [POST]
Регистрация клиентом карты.
https://webhook.site
{
  "crm_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "method": "createCustomer",
  "customer": {
    "name": "Илья",
    "surname": "Орлов",
    "middlename": "Андреевич",
    "email": "ilia@cardpr.com",
    "phone": "+79111111111",
    "birthday": "1980-01-25",
    "cardNumbers": ["120"],
    "cardTracks": [{"card": "120", "track": "876234876234"}],
    "extra": {
      "sex": "male", //необязательный параметр
      "promo": "BBBBB" //промокод, который ввел клиент при регистрации
    },
    "balance": 300.00,
    "bonus": 10.00,
    "discount": 25.00,
    "promo": "AAAAA", //промокод клиента для приглашений
    "referCustomerPhone": "+79000000000"
  }
}
Обработчик получает данные, проверяет наличие клиента в CRM системе по номеру телефона. Если клиента с таким номером телефона нет, его нужно создать, создать ему карту и вернуть "customerId". Если клиент с таким номером телефона есть, нужно обновить данные этого клиента и добавить ему новую карту (заменить, если CRM система не поддерживает несколько карт) и вернуть "customerId". Номера карт назначаются на стороне CARDPR и при интеграции необходимо прописать в настройках стартовый номер свободного диапазона карт.
Необходимый ответ от CRM:
"customerId" — уникальный идентификатор пользователя в вашей CRM.
Пример успешного вызова (HTTP 200):
{"customerId": "6d2845ff-0a07-11e7-25df-d8d18565926f"}
Пример вызова с ошибкой (HTTP 400):
{"error": "Detailed error description..."}
Метод 1.2. readBalance [POST]
Запрос баланса, необходим для ручного запроса на обновление процентов и баланса на карте клиента.
Пример запроса:
https://webhook.site
{
  "crm_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "method": "readBalance",
  "customer": {
    "phone": "+79111111111",
    "cardNumbers": ["120"]
  }
}
Обработчику следует вернуть баланс/бонус/скидку по указанному клиенту (идентификация по номеру телефона и номеру карты).
Пример ответа:
{
  "success": true,
  "bonus" : 12.5,
  "balance": 5,
  "discount": 17.88
}
Метод 1.3. addBalance [POST]
Хук на добавление бонусов, необходим для начисления бонусов.
Пример запроса:
https://webhook.site
{
  "crm_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "method": "addBalance",
  "customer": {
    "phone": "+79111111111",
    "cardNumbers": ["120"],
    "sum": 50.00,
    "transactionId": "id/guid",
    "lifetime": 14 //необязательно, время жизни бонусов в сутках
  }
}
Обработчик должен добавить баланс указанному клиенту (идентификация по номеру телефона и номеру карты). Если передан параметр "lifetime", у данного начисления необходимо задать сгорание через заданное количество суток.
Пример ответа:
{
  "success": true
}

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

Используется для создания/обновления электронных карт при изменении информации в вашей CRM и для чтения информации из CARDPR.
На этапе тестирования вы можете использовать приложение https://postman.com.
Метод 2.1. status [POST]
Проверка приватного ключа и статуса вашего аккаунта.
URL
https://core.codepr.ru/api/v2/status
Данные:
{
  "app_key": "приватный ключ"
}
Ответ:
{
  "app": "account_name",
  "balance": 15000.00
}
Метод 2.2. user_create_or_update [POST]
Обновление или создание клиента в CARDPR, ключом является номер телефона.
URL
https://core.codepr.ru/api/v2/crm/user_create_or_update
Данные (в блоке также можно передавать пользовательские переменные):
{
  "app_key": "приватный ключ",
  "name": "имя",
  "phone": "мобильный телефон клиента",
  "email": "электронная почта", //необязательно
  "surname": "фамилия", //необязательно
  "middlename": "отчество", //необязательно
  "birthday": "дата рождения dd.mm.yyyy", //необязательно
  "discount": "размер скидки в %", //float, по умолчанию 0
  "bonus": "размер бонуса в %", //float, по умолчанию 0
  "balance": "количество бонусов", //float, по умолчанию 0
  "card_track": "...", //новый трек карты, при смене трека карта перезаписана в CRM
  "template_uuid": "...", //uuid дизайн-шаблона карты
  "customerId": "идентификатор клиента в вашей CRM",
  "link": "ссылка на форму выдачи карт",
  "sms": "Предлагаем установить карту: %link%" //sms для отправки клиенту
}
Для создания персональной ссылки на форму для установки карты "form_url" необходимо передавать ссылку на форму в поле "link". В тексте SMS-сообщения %link% будет заменено на персональную ссылку для получения карты.
Ответ:
{
  "success": "сообщение о создании клиента", //bool
  "sms_send": "сообщение об отправке смс", //bool
  "card": "сообщение о создании карты", //bool
  "card_number": "номер созданной карты", //string
  "card_track": "трек созданной карты", //string
  "card_url": "персональная ссылка на карту Apple Wallet", //url
  "card_gpay_url": "персональная ссылка на карту Google Pay", //url
  "form_url": "персональная ссылка на форму", //url
  "user_hash": "hash для персонализации формы выдачи" //hash
}
Пример создания клиента:
При создании клиента, если вы хотите ему отправить SMS, необходимо указать ссылку на вашу форму в поле "link" и текст самого сообщения в поле "sms", как показано в примере.
https://core.codepr.ru/api/v2/crm/user_create_or_update
{
  "app_key" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "phone" : "+79111111111",
  "email" : "ilia@cardpr.com",
  "name" : "Илья",
  "surname" : "Орлов",
  "middlename" : "Андреевич",
  "birthday" : "11.11.1980",
  "discount" : 0,
  "bonus" : 3.50,
  "balance" : 100,
  "link" : "https://form.cardpr.com/00000000-0000-0000-0000-000000000000",
  "sms" : "Ваша карта доступна по ссылке: %link%"
}
Пример текста SMS-сообщения (по ссылке выдается карта без ввода персональных данных):
"Ваша карта доступна по ссылке: https://form.cardpr.com/00000000-0000-0000-0000/?hash=2f10171a33f66f3bc425335690ec880c"
Изменение баланса карты. Дополнительно, если в шаблоне карты настроен push на изменение баланса — у клиента на телефона отобразится сообщение об изменении баланса.
https://core.codepr.ru/api/v2/crm/user_create_or_update
{
  "app_key" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "phone" : "+79111111111",
  "balance" : 120
}
Отправка персонального push-сообщения на электронную карту:
При отправке пуша не меняйте переменные, к которым привязаны уведомления в дизайн-шаблоне карты. Если отправить пуш и одновременно изменить такую переменную, то будет отправлен пуш с системным уведомлением, что карта изменилась.
https://core.codepr.ru/api/v2/crm/user_create_or_update
{
  "app_key" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "phone" : "+79111111111",
  "push" : "Ваш заказ готов к получению!"
}
Отправка персонального webpush (требуются подключенные webpush из Маркетплейса):
https://core.codepr.ru/api/v2/crm/user_create_or_update
{
  "app_key" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "phone" : "+79111111111",
  "send_webpush" : "Ваш заказ готов к получению!"
}
Отправка персонального Telegram-сообщения (требуются подключенный Telegram из Маркетплейса):
https://core.codepr.ru/api/v2/crm/user_create_or_update
{
  "app_key" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "phone" : "+79111111111",
  "send_telegram" : "Ваш заказ готов к получению!"
}
Метод 2.3. read_customer [POST]
Получение данных клиента по номеру телефона или по номеру карты.
URL
https://core.codepr.ru/api/v2/crm/read_customer
Входные параметры (указывайте "phone" или "card"):
{
  "app_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "phone": "", //номер телефона
  "card": "", //номер карты
  "invites": bool, //нужна ли реферальная информация
  "installs": bool //нужна ли информация об установках карт
}
Формат ответа:
{
  "customer": {
    "phone": "+79111111111",
    "email": "ilia@cardpr.com",
    "name": "Илья",
    "surname": "Орлов",
    "middlename": "Андреевич",
    "birthday": "11.11.1980",
    "cardNumbers": ["120"],
    "cardTracks": [{"card": "120", "track": "876234876234"}],
    "cardInstalls": [{"card": "120", "install": true}], //флаг установки карт
    "discount": 4.5,
    "bonus": 0,
    "balance": 0,
    "template_uuid": "...", //uuid дизайн-шаблона карты
    "remoteId": "6326", //ID во внешней CRM-системе
    "invitedBy": "+79111111111",
    "invites": [ //реферальная информация
      "+79111111112",
      "+79111111113"
    ]
  }
}
Метод 2.4. read_customers [POST]
Получить список клиентов по дате регистрации.
URL
https://core.codepr.ru/api/v2/crm/read_customers
Входные параметры:
{
  "app_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "start_date": "datetime", //01.01.2020
  "end_date": "datetime", //31.12.2020 23:59:59
  "installed": true,
  "offset": 0
}
Параметр "installed":
если параметр не указан – метод вернет всех клиентов;
если параметр равен true – метод вернет клиентов с установленными картами;
если параметр равен false – метод вернет клиентов с неустановленными картами.
Метод возвращает первых 100 клиентов,
для получения следующих клиентов необходимо использовать аргумент offset.
Формат ответа:
{
  "customers":
  [
    "+79111111111",
    "+79111111112"
  ]
}
Метод 2.5. push/create [POST]
Создать push-рассылку по всей клиентской базе или по сегменту.
Тип рассылки может быть push на карты, webpush или Telegram.
Для webpush и Telegram требуется подключенное приложение из Маркетплейса.
После создания push-рассылки её необходимо отправить методом 2.5.
URL
https://core.codepr.ru/api/v2/crm/push/create
Входные параметры:
{
  "app_key": "", //приватный ключ
  "message": "", //текст сообщения
  "type": "", //тип сообщения – text, webpush, telegram
  "name": "", //название, отображается в кабинете, необязательный параметр
  "segment_uuid": "" //идентификатор сегмента, необязательный параметр
}
Пример ответа:
{
  "result": {
    "name": "Push#0000",
    "uuid": "00000000-0000-0000-0000-000000000000",
    "message": "Тестовый пуш!"
  }
}
Метод 2.6. push/send [POST]
Выполнить push-рассылку.
URL
https://core.codepr.ru/api/v2/crm/push/send
Входные параметры:
{
  "app_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "push_uuid": "00000000-0000-0000-0000-000000000000" //идентификатор пуш-рассылки
}
Приложение A. Пример CURL из Linux-консоли (Cygwin для Windows).
curl -d '{"app_key":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "phone":"+79000000000", "email":"ilia@cardpr.com", "name":"Илья", "surname":"Орлов", "middlename":"Андреевич", "birthday":"03.05.1980", "discount":0, "bonus":5, "balance":200}' -H "Content-Type: application/json" -X POST https://core.codepr.ru/api/v2/crm/user_create_or_update
Приложение B. Пример реализации на PHP.
<?php

$url = 'https://core.codepr.ru/api/v2/crm/user_create_or_update';
$post = [
  'app_key' => 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  'phone' => '+79000000000',
  'email' => 'ilia@cardpr.com',
  'name' => 'Илья',
  'surname' => 'Орлов',
  'middlename' => 'Андреевич',
  'birthday' => '03.05.1980',
  'discount' => 0,
  'bonus' => 4.5,
  'balance' => 100
];

$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 => 2,
  CURLOPT_SSL_VERIFYPEER => true,
  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);

print_r($result);

?>

Примечания

1. При работе с API есть лимиты на количество запросов:
Тариф Base — 1/сек, 60/час;
Тариф Advanced — 1/сек, 600/час;
Тариф Expert — 1/сек, 3600/час.
Тариф Exclusive — 1/сек, 3600/час.
В лимитах учитываются все запросы от вашей системы к CARDPR.
Увеличение лимитов по запросу в техподдержку.
2. В примерах для наглядности в JSON-коде используются комментарии согласно спецификации JSON5, однако, при работе по API в JSON-коде комментарии использовать нельзя.
3. При получении ошибки сформируйте запрос в техподдержку с предоставлением логов (запрос + ответ).
4. Для передачи данных по клиентам в вашу CRM реализуйте интеграцию согласно группе методов — Передача данных из CARDPR в вашу CRM.
5. Для отладки хуков на этапе тестирования вы можете использовать сервис https://webhook.site.
6. Для отладки исходящих запросов на этапе тестирования вы можете использовать приложение https://postman.com.