Руководство по API

Формат взаимодействия

LOCUST CARDS — универсальное решение для работы с картами лояльности. С помощью этого API вы можете отправлять запросы на регистрацию карт, накопление и списание бонусов, изменять данные о владельце карты и многое другое.

API в качестве основного протокола использует HTTP, а значит, подходит для разработки на любом языке программирования, который умеет работать с HTTP-библиотеками (cURL и другими).

API endpoint: https://locustcards.ru/api/

API поддерживает POST и GET-запросы. API всегда возвращает ответ в формате JSON, независимо от типа запроса.

PHP-класс для работы с API: MAXiDROME / LocustCards

Аутентификация

Для аутентификации запросов необходимо использовать ваш секретный ключ (его можно сгенерировать в личном кабинете), который нужно передавать при каждом запросе к API.

Секретный ключ отвечает за безопасность ваших данных. Храните его в защищенном месте и не публикуйте на сторонних ресурсах (например, вместе с примерами кода).

Справочник API LOCUST CARDS

В справочнике API вы найдете описание всех методов API LOCUST CARDS. С помощью этого API вы можете отправлять запросы на регистрацию карт, накопление и списание бонусов, изменять данные о владельце карты и многое другое.

register_customer

Регистрация нового покупателя и бонусной карты.

В ответ на запрос придет номер карты и ключ, который нужно будет передать в request_key.

Параметры запроса Описание
phone
string, required 		Номер телефона покупателя.
card
string, optional 		Номер карты покупателя. Если не указан - будет сгенерирован автоматически.
percent
integer, optional 		Процент бонусов по карте. Если не передается, то будет установлен в 0.
email
string, optional 		Адрес электронной почты покупателя.
lastname
string, optional 		Фамилия покупателя.
firstname
string, optional 		Имя покупателя.
patronymic
string, optional 		Отчество покупателя.
sex
string, optional 		Пол покупателя (1 - мужчина, 0 - женщина).
birthday
integer, optional 		Дата рождения покупателя в формате YYYY-MM-DD.
comment
string, optional 		Комментарий.
Пример запроса
<?php
$api=new LocustCard("e7422563640e72d3af753fef783e9e55");
$cards=$api->register_customer("+79126438021","",5,"john.dow@example.com","Иванов","Петр","Сергеевич",1,"Тестовый пользователь");
?>
Пример тела ответа

edit_customer

Изменение информации о покупателе.

В ответ на запрос придет TRUE в случае успеха.

Параметры запроса Описание
customer_id
string, required 		id покупателя.
email
string, optional 		Адрес электронной почты покупателя. Если отличается от сохраненного значения, то значение email_activated устанавливается в 0.
lastname
string, optional 		Фамилия покупателя.
firstname
string, optional 		Имя покупателя.
patronymic
string, optional 		Отчество покупателя.
sex
string, optional 		Пол покупателя (1 - мужчина, 0 - женщина).
comment
string, optional 		Комментарий.
Пример запроса
<?php
$api=new LocustCard("e7422563640e72d3af753fef783e9e55");
$cards=$api->edit_customer("e7422563640e72d3af753fef783e9e55","john.dow@example.com","Иванов","Петр","Сергеевич",1,"Тестовый пользователь");
?>
Пример тела ответа
true

get_customer_by_phone

Запрос информации о покупателе по номеру телефона.

В ответ на запрос придет информация о пользователе.

Параметры запроса Описание
phone
string, required 		Номер телефона покупателя.
Пример запроса
<?php
$api=new LocustCard("e7422563640e72d3af753fef783e9e55");
$customer=$api->get_customer_by_phone("+79126438021");
?>
Пример тела ответа
{
    "id": "e7422563640e72d3af753fef783e9e55",
    "regdate": 1573116633,
    "lastname": "Иванов",
    "firstname": "Петр",
    "patronymic": "Сергеевич",
    "birthday": "0000-00-00",
    "sex": 1,
    "comment": "Тестовый покупатель",
    "email": "john.dow@example.com",
    "email_activated": true
}

get_customer_by_email

Запрос информации о покупателе по адресу электронной почты.

В ответ на запрос придет информация о пользователе.

Параметры запроса Описание
email
string, required 		Адрес электронной почты покупателя.
Пример запроса
<?php
$api=new LocustCard("e7422563640e72d3af753fef783e9e55");
$customer=$api->get_customer_by_email("john.dow@example.com");
?>
Пример тела ответа
{
  "id": "e7422563640e72d3af753fef783e9e55",
  "regdate": 1573116633,
  "lastname": "Иванов",
  "firstname": "Петр",
  "patronymic": "Сергеевич",
  "birthday": "0000-00-00",
  "sex": 1,
  "comment": "Тестовый покупатель",
  "email": "john.dow@example.com",
  "email_activated": true
}

register_card

Регистрация новой карты.

В ответ на запрос придет номер карты и ключ, который нужно будет передать в request_key.

Параметры запроса Описание
customer_id
string, required 		id покупателя.
phone
string, required 		Номер телефона покупателя.
card
string, optional 		Номер карты покупателя. Если не указан - будет сгенерирован автоматически.
percent
integer, optional 		Процент бонусов по карте. Если не передается, то будет установлен в 0.
Пример запроса
<?php
$api=new LocustCard("e7422563640e72d3af753fef783e9e55");
$cards=$api->register_card("e7422563640e72d3af753fef783e9e55","+79126438021","1122334455","10");
?>
Пример тела ответа

edit_card

Изменение данных карты (телефона, процента бонусов и покупателя).

В ответ на запрос придет TRUE в случае успеха.

Параметры запроса Описание
card
string, required 		Номер карты покупателя.
phone
string, required 		Номер телефона покупателя.
percent
integer, optional 		Процент бонусов по карте. Если не передается, то будет установлен в 0.
customer_id
string, optional 		id нового покупателя, если необходимо привязать карту к другому пользователю. История операций по карте перенесется к новому покупателю.
Пример запроса
<?php
$api=new LocustCard("e7422563640e72d3af753fef783e9e55");
$cards=$api->edit_card("1234567890","89126438021","3","");
?>
Пример тела ответа
true

delete_card

Удаление карты и истории операций. Так же удаляет покупателя, если у него не заполнен адрес электронной почты и нет ни одной карты.

В ответ на запрос придет TRUE в случае успеха.

Параметры запроса Описание
card
string, required 		Номер карты покупателя.
Пример запроса
<?php
$api=new LocustCard("e7422563640e72d3af753fef783e9e55");
$cards=$api->delete_card("1234567890");
?>
Пример тела ответа
true

is_card_active

Возвращает признак активации карты. Карта считается активированной, если request_code и request_key для этой карты были выполнены успешно.

В ответ на запрос придет TRUE, если карта активна.

Параметры запроса Описание
card
string, required 		Номер карты покупателя.
Пример запроса
<?php
$api=new LocustCard("e7422563640e72d3af753fef783e9e55");
$cards=$api->is_card_active("1234567890");
?>
Пример тела ответа
true

get_cards_by_phone

Получение списка карт, привязанных к номеру телефона.

В ответ на запрос придет массив карт и инофрмация о покупателе.

Параметры запроса Описание
phone
string, required 		Номер телефона покупателя. Будет автоматически очищен от всех символов, кроме цифр. Если номер телефона начинается с 8, то она будет заменена на код страны из профиля компании.
Пример запроса
<?php
$api=new LocustCard("e7422563640e72d3af753fef783e9e55");
$cards=$api->get_cards_by_phone("+79126438021");
?>
Пример тела ответа

    {
        "cards":[
            {
                "id":"e7422563640e72d3af753fef783e9e55",
                "card_number":"0000000001",
                "percent":10,
                "phone":"79126438021",
                "balance":1100,
                "active":true,
                "regdate":"1572588885"
            },
            {
                "id":"ceeeb7d6945bca1c0976eb2e1d6d2a10",
                "card_number":"0000000002",
                "percent":3,
                "phone":"79126438021",
                "balance":0,
                "active":true,
                "regdate":"1573539285"
            }
        ],
        "customer":{
            "id":"e7422563640e72d3af753fef783e9e55",
            "regdate":1573116633,
            "lastname":"Иванов",
            "firstname":"Петр",
            "patronymic":"Сергеевич",
            "birthday":"0000-00-00",
            "sex":1,
            "comment":"Тестовый покупатель",
            "email":"john.dow@example.com",
            "email_activated":true
        }
    }

get_card_by_number

Получение информации о карте по ее номеру.

В ответ на запрос придут данные карты и информация о покупателе.

Параметры запроса Описание
card
string, required 		Номер карты покупателя.
Пример запроса
<?php
$api=new LocustCard("e7422563640e72d3af753fef783e9e55");
$cards=$api->get_card_by_number("1234567890");
?>
Пример тела ответа

{
    "card":{
        "id":"e7422563640e72d3af753fef783e9e55",
        "card_number":"0000000001",
        "percent":10,
        "phone":"79126438021",
        "balance":1100,
        "active":true,
        "regdate":1572588885
},
    "customer":{
        "id":"e7422563640e72d3af753fef783e9e55",
        "regdate":1573116633,
        "lastname":"Иванов",
        "firstname":"Петр",
        "patronymic":"Сергеевич",
        "birthday":"0000-00-00",
        "sex":1,
        "comment":"Тестовый покупатель",
        "email":"john.dow@example.com",
        "email_activated":true
    }
}

get_operations_by_card

Возвращает список операций по карте.

В ответ на запрос придет список операций по карте в заданном интервале дат или за текущий месяц, если даты не указаны.

Параметры запроса Описание
card
string, required 		Номер карты покупателя.
date_start
integer, optional 		Дата и время начала периода в формате UNIX (количество секунд, прошедших с начала эпохи Unix (1 января 1970 00:00:00 GMT)). Если не указана, то используется первое число текущего месяца.
date_end
integer, optional 		Дата и время конца периода в формате UNIX (количество секунд, прошедших с начала эпохи Unix (1 января 1970 00:00:00 GMT)). Если не указана, то используется последнее число текущего месяца.
Пример запроса
<?php
$api=new LocustCard("e7422563640e72d3af753fef783e9e55");
$cards=$api->get_operations_by_card("1234567890","","");
?>
Пример тела ответа

[
    {
        "adddate":1573017120,
        "operation_date":1573017021,
        "value_add":1000,
        "value_sub":0,
        "comment":"начисление за заказ 101",
        "uid":"12ef878787f098098c098b09809800",
        "status":"1"
    },
    {
        "adddate":1573116696,
        "operation_date":1573116696,
        "value_add":0,
        "value_sub":500,
        "comment":"списание за заказ 123",
        "uid":"12ef878787aaa8098c098b09809800",
        "status":"1"
    },
    {
        "adddate":1573313550,
        "operation_date":1573313550,
        "value_add":300,
        "value_sub":0,
        "comment":"заказ 123",
        "uid":"12ef8787bcde8098c098b09809800",
        "status":"0"
    }
]

add_operation

Добавление операции по карте.

В ответ на запрос придет UID операции. При недостаточном балансе при попытке списания выдаст ошибку.

Параметры запроса Описание
card
string, required 		Номер карты покупателя.
value_add
float, required 		Сумма операции начисления, дробная часть отделяется точкой и имеет два разряда.
value_sub
float, required 		Сумма операции списания, дробная часть отделяется точкой и имеет два разряда.
uid
string, optional 		Уникальный идентификатор операции. Если не задан, будет сгенерирован автоматически.
date
integer, optional 		Дата и время совершения операции в формате UNIX (количество секунд, прошедших с начала эпохи Unix (1 января 1970 00:00:00 GMT)). Если не указана, то записывается текущая дата и время.
comment
string, optional 		Текстовый комментарий к операции.
Пример запроса
<?php
$api=new LocustCard("e7422563640e72d3af753fef783e9e55");
$cards=$api->add_operation("1234567890",100.20,0,"","Заказ №123");
?>
Пример тела ответа
{
  "uid": "12ef878787f098098c098b09809800"
}

confirm_operation

Подтверждение операции по карте.

В ответ на запрос придет TRUE в случае успешного подтверждения операции.

Параметры запроса Описание
uid
string, required 		Идентификатор операции.
Пример запроса
<?php
$api=new LocustCard("e7422563640e72d3af753fef783e9e55");
$cards=$api->confirm_operation("12ef878787f098098c098b09809800");
?>
Пример тела ответа
true

delete_operation

Удаляет операцию по карте.

В ответ на запрос придет TRUE в случае успеха.

Параметры запроса Описание
uid
string, required 		Уникальный идентификатор операции.
Пример запроса
<?php
$api=new LocustCard("e7422563640e72d3af753fef783e9e55");
$cards=$api->delete_operation("e7422563640e72d3af753fef783e9e55");
?>
Пример тела ответа
true

request_code

Запрос смс-кода для подтверждения номера телефона, привязанного к карте.

В ответ на запрос придет ключ, который нужно будет передать в request_key.

Параметры запроса Описание
card
string, required 		Номер карты покупателя.
Пример запроса
<?php
$api=new LocustCard("e7422563640e72d3af753fef783e9e55");
$cards=$api->request_code("1234567890");
?>
Пример тела ответа
{
  "key": "d293e58f23094586c34af85623094de6"
}

request_key

Проверка смс-кода для подтверждения номера телефона, привязанного к карте.

В ответ на запрос придет TRUE, если код верный.

Параметры запроса Описание
code
string, required 		Проверочный код из смс.
key
string, required 		Ключ, полученный после вызова request_code.
Пример запроса
<?php
$api=new LocustCard("e7422563640e72d3af753fef783e9e55");
$cards=$api->request_key("1234","1234567890987654321234567890");
?>
Пример тела ответа
true