Documentation Powered by ReDoc

Спецификация публичного API maceloyalty.ru (1.0.0)

Download OpenAPI specification:Download

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

MaceLoyalty — универсальное решение для работы с картами Apple Wallet и Google Pay. API MaceLoyalty построено на REST-принципах, работает с реальными объектами и обладает предсказуемым поведением. С помощью этого API вы можете отправлять запросы на выпуска карт, создавать пользователей, совершать операции по картам и многое другое. API в качестве основного протокола использует HTTP, а значит, подходит для разработки на любом языке программирования, который умеет работать с HTTP-библиотеками (cURL и другими).

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

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

Для аутентификации запросов необходимо использовать HTTP Basic Auth. В заголовках запросов в качестве имени пользователя необходимо передать идентификатор вашей компании в MaceLoyalty, в качестве пароля — ваш секретный ключ (его нужно сгенерировать через менеджера). Секретный ключ отвечает за безопасность ваших данных. Храните его в защищенном месте и не публикуйте на сторонних ресурсах (например, вместе с примерами кода).

Идемпотентность

В контексте API идемпотентность означает, что многократные запросы обрабатываются так же, как однократные. Это значит, что получив повторный запрос с теми же параметрами, MaceLoyalty выдаст в ответе результат исходного запроса. Такое поведение помогает избежать нежелательного повторения операций. Например, если при проведении начисления возникли проблемы с сетью, и соединение прервалось, вы сможете безопасно повторить нужный запрос неограниченное количество раз. GET-запросы являются по умолчанию идемпотентными, так как не имеют нежелательных последствий. Для обеспечения идемпотентности POST-запросов используется заголовок Idempotence-Key (или ключ идемпотентности).

Если вы повторяете запрос с теми же данными и тем же ключом, API обрабатывает его как повторный. Если данные в запросе те же, а ключ идемпотентности отличается, запрос выполняется как новый. В заголовке Idempotence-Key можно передавать любое значение, уникальное для этой операции на вашей стороне. Мы рекомендуем использовать V4 UUID. MaceLoyalty обеспечивает идемпотентность в течение 24 часов после первого запроса, потом повторный запрос будет обработан как новый.

Работа со списками объектов в ответах (пагинация)

Некоторые запросы могут возвращать структуру, содержащую коллекцию объектов, а также nextCursor. С помощь него можно получить ссылку на следующую порцию данных, передав его в GET параметрах запроса. Также, можно передавать параметр limit для управления количеством объектов в ответе.

Получить список шаблонов карт

query Parameters
nextCursor
string

Метка на следующую выборку

limit
integer

Количество объектов в выборке

Responses

Response samples

Content type
application/json
{
  • "nextCursor": "string",
  • "items": [
    ]
}

Получить шаблон карты по идентификатору

path Parameters
id
required
string

Уникальный идентификатор шаблона карты

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "type": "discount",
  • "status": "active",
  • "levels": [
    ]
}

Получить список карт

query Parameters
nextCursor
string

Метка на следующую выборку

limit
integer

Количество объектов в выборке

Responses

Response samples

Content type
application/json
{
  • "nextCursor": "string",
  • "items": [
    ]
}

Создание карты

Request Body schema: application/json

Детальная информация по выпускаемой карте

cardTemplateId
required
string

Идентификатор шаблона карты

object

Данные держателя карты

object

Уровень карты

object

Информация о балансе карты

Responses

Request samples

Content type
application/json
{
  • "cardTemplateId": "string",
  • "customer": {
    },
  • "level": {
    },
  • "balance": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "os": "ios",
  • "cardTemplateId": "string",
  • "status": "created",
  • "packageUri": "string",
  • "customer": {
    },
  • "level": {
    },
  • "balance": {
    }
}

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

path Parameters
id
required
string

Уникальный идентификатор карты

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "os": "ios",
  • "cardTemplateId": "string",
  • "status": "created",
  • "packageUri": "string",
  • "customer": {
    },
  • "level": {
    },
  • "balance": {
    }
}

Получить список операций

query Parameters
nextCursor
string

Метка на следующую выборку

limit
integer

Количество объектов в выборке

Responses

Response samples

Content type
application/json
{
  • "nextCursor": "string",
  • "items": [
    ]
}

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

Request Body schema: application/json

Детальная информация по операции

cardInstanceId
required
string
required
OperationType (string)
required
object

Детали операции

Responses

Request samples

Content type
application/json
{
  • "cardInstanceId": "string",
  • "type": "purchase",
  • "details": {
    }
}

Response samples

Content type
application/json
{
  • "id": "6d92480a-fb06-43ba-8765-6e4ed00ed349",
  • "status": "inProgress",
  • "operationDateTime": "2018-08-09T18:31:42+03:30",
  • "cardInstanceId": "string",
  • "type": "purchase",
  • "details": {
    }
}

Получить список клиентов

query Parameters
nextCursor
string

Метка на следующую выборку

limit
integer

Количество объектов в выборке

Responses

Response samples

Content type
application/json
{
  • "nextCursor": "string",
  • "items": [
    ]
}

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

path Parameters
id
required
string

Уникальный идентификатор клиента

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "middleName": "string",
  • "gender": "string",
  • "birthDate": "2018-08-09T18:31:42+03:30",
  • "phoneNumber": "string",
  • "email": "string",
  • "city": "string",
  • "vkProfile": "string",
  • "instagramProfile": "string",
  • "acceptOffer": true,
  • "marketingChannels": [
    ]
}

Получить список пользователей

query Parameters
nextCursor
string

Метка на следующую выборку

limit
integer

Количество объектов в выборке

Responses

Response samples

Content type
application/json
{
  • "nextCursor": "string",
  • "items": [
    ]
}

Создание нового пользователя

Request Body schema: application/json

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

id
required
string

Уникальный идентификатор

required
UserStatus (string)

Статус пользователя

required
UserRole (string)

Роль пользователя

username
required
string

Логин пользователя

password
string

Пароль пользователя. Передается только при создании пользователя, и никогда не отдается в ответе.

firstName
required
string

Имя пользователя

lastName
required
string

Фамилия пользователя

middleName
string

Отчиство пользователя

Responses

Request samples

Content type
application/json
{
  • "id": "6d92480a-fb06-43ba-8765-6e4ed00ed349",
  • "status": "active",
  • "role": "operator",
  • "username": "string",
  • "password": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "middleName": "string"
}

Response samples

Content type
application/json
{
  • "id": "6d92480a-fb06-43ba-8765-6e4ed00ed349",
  • "status": "active",
  • "role": "operator",
  • "username": "string",
  • "password": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "middleName": "string"
}

Получить информацию по пользователю

path Parameters
id
required
string

Уникальный идентификатор пользователя

Responses

Response samples

Content type
application/json
{
  • "id": "6d92480a-fb06-43ba-8765-6e4ed00ed349",
  • "status": "active",
  • "role": "operator",
  • "username": "string",
  • "password": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "middleName": "string"
}

Обновить пользователя

path Parameters
id
required
string

Уникальный идентификатор пользователя

Request Body schema: application/json

Новая информация о пользователе

id
required
string

Уникальный идентификатор

required
UserStatus (string)

Статус пользователя

required
UserRole (string)

Роль пользователя

username
required
string

Логин пользователя

password
string

Пароль пользователя. Передается только при создании пользователя, и никогда не отдается в ответе.

firstName
required
string

Имя пользователя

lastName
required
string

Фамилия пользователя

middleName
string

Отчиство пользователя

Responses

Request samples

Content type
application/json
{
  • "id": "6d92480a-fb06-43ba-8765-6e4ed00ed349",
  • "status": "active",
  • "role": "operator",
  • "username": "string",
  • "password": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "middleName": "string"
}

Response samples

Content type
application/json
{
  • "id": "6d92480a-fb06-43ba-8765-6e4ed00ed349",
  • "status": "active",
  • "role": "operator",
  • "username": "string",
  • "password": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "middleName": "string"
}

Удалить пользователя

path Parameters
id
required
string

Уникальный идентификатор пользователя

Responses

Response samples

Content type
application/json
{
  • "id": "c58d861b-f56e-4a4a-abb0-11711c59f6b8",
  • "code": "string",
  • "message": "Карта не найдена"
}

Получить список отправленных уведомлений

query Parameters
nextCursor
string

Метка на следующую выборку

limit
integer

Количество объектов в выборке

Responses

Response samples

Content type
application/json
{
  • "nextCursor": "string",
  • "items": [
    ]
}

Отправить push-уведомления пользователям

Request Body schema: application/json

Информация об отправляемом уведомлении

message
string

Текст сообщения

Responses

Request samples

Content type
application/json
{
  • "message": "string"
}

Response samples

Content type
application/json
{
  • "id": "6d92480a-fb06-43ba-8765-6e4ed00ed349",
  • "message": "string",
  • "status": "inProgress",
  • "sentAt": "2018-08-09T18:31:42+03:30"
}

Получить информацию по отправленному уведомлению

path Parameters
id
required
string

Уникальный идентификатор уведомления

Responses

Response samples

Content type
application/json
{
  • "id": "6d92480a-fb06-43ba-8765-6e4ed00ed349",
  • "message": "string",
  • "status": "inProgress",
  • "sentAt": "2018-08-09T18:31:42+03:30"
}