Методы API v1

Для интеграции GrowCards в вашу внутреннюю систему используйте методы, описанные на этой странице.

Коллекция в Postman

Мы создали коллекцию в Postman с описанными ниже методами и всеми необходимыми параметрами для удобного тестирования запросов.

get
Список карт

https://api.growcards.ru/v1/passes
Получение списка выпущенных карт. По умолчанию возвращает все карты, созданные в рамках компании. Для получения карт, созданных в рамках шаблона, укажите в параметрах запроса templateId
Request
Response
Request
Headers
X-SECRET-KEY
required
string
Интеграционный ключ компании
Query Parameters
page
optional
number
Номер страницы
template
optional
string
ID шаблона
Response
200: OK
В массиве docs содержится список созданных карт
{
"docs": [
{
"_id": "5e491ad54ebdb3640ff47a09",
"name": "Петр Иванов",
"serialNumber": "3239950756",
"company": {
"name": "2MOOD"
},
"template": {
"name": "Карта 2MOOD"
},
"created_at": "2020-02-16T10:35:01.554Z",
"devices": [
{
"os": "ios",
"application": "apple wallet"
}
]
},
{...}
],
"totalDocs": 3,
"limit": 3,
"page": 1,
"totalPages": 1,
"pagingCounter": 1,
"hasPrevPage": false,
"hasNextPage": false,
"prevPage": null,
"nextPage": null
}

Метод поддерживает пагинацию. Если параметр page не указан, то будут возвращены все карты.

get
Объект карты

https://api.growcards.ru/v1/passes/:passId
Получение данных выпущенной карты.
Request
Response
Request
Path Parameters
passId
required
string
ID карты клиента
Headers
X-SECRET-KEY
required
string
Интеграционный ключ компании
Response
200: OK
Тело ответа содержит данные запрашиваемой карты
{
"_id": "5e468c805d8d34644ebb34e6",
"formDataFields": [
{
"key": "email",
"value": "wavemeup1@gmail.com"
}
],
"name": "Вячеслав Осадчий",
"phone": "79218678737",
"serialNumber": "1282295653",
"company": {
"name": "2MOOD"
},
"template": {
"name": "Карта 2MOOD"
},
"created_at": "2020-02-14T12:03:12.891Z",
"devices": [
{
"os": "ios",
"application": "apple wallet",
"created_at": "2020-02-14T12:05:32.194Z"
}
],
"fields": [
{
"key": "discount",
"label": "Ваша скидка",
"value": "10%",
"enabled": true,
"changeMessage": "У вас новая скидка: %@"
},
{
"key": "levelname",
"label": "Уровень",
"value": "Welcome",
"enabled": true,
"changeMessage": "У вас новый уровень: %@"
}
]
}
404: Not Found
Карта с заданным ID не найдена
{
"message": "Card not found"
}

get
Объект карты по серийному номеру

https://api.growcards.ru/v1/passes/s/:serialNumber
Получение данных выпущенной карты по серийному номеру.
Request
Response
Request
Path Parameters
serialNumber
required
string
Серийный номер карты
Headers
X-SECRET-KEY
required
string
Интеграционный ключ компании
Response
200: OK
Тело ответа содержит данные запрашиваемой карты
{
"_id": "5e468c805d8d34644ebb34e6",
"formDataFields": [
{
"key": "email",
"value": "wavemeup1@gmail.com"
}
],
"name": "Вячеслав Осадчий",
"phone": "79218678737",
"serialNumber": "1282295653",
"company": {
"name": "2MOOD"
},
"template": {
"name": "Карта 2MOOD"
},
"created_at": "2020-02-14T12:03:12.891Z",
"devices": [
{
"os": "ios",
"application": "apple wallet",
"created_at": "2020-02-14T12:05:32.194Z"
}
],
"fields": [
{
"key": "discount",
"label": "Ваша скидка",
"value": "10%",
"enabled": true,
"changeMessage": "У вас новая скидка: %@"
},
{
"key": "levelname",
"label": "Уровень",
"value": "Welcome",
"enabled": true,
"changeMessage": "У вас новый уровень: %@"
}
]
}
404: Not Found
Карта с заданным серийному номером не найдена
{
"message": "Card not found"
}

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

https://api.growcards.ru/v1/passes
Создание клиентской карты на основе шаблона.
Request
Response
Request
Headers
X-SECRET-KEY
required
string
Интеграционный ключ компании
Body Parameters
surname
required
string
Фамилия владельца
name
required
string
Имя владельца
phone
required
string
Номер телефона
template
required
string
ID шаблона
Response
200: OK
Тело ответа содержит данные созданной карты в поле card
{
"card": {
"additionalFields": [],
"formDataFields": [],
"_id": "5e4b10afeee85432d7a38485",
"name": "Иван Иванов",
"phone": "79211234567",
"serialNumber": "8791825079",
"company": "5e467951258120641621e6a0",
"template": {
"id": "5e467b05258120641621e6a2",
"type": "loyaltyCard"
},
"informationMessage": "",
"created_at": "2020-02-17T22:16:15.936Z",
"updated_at": "2020-02-17T22:16:15.936Z",
"__v": 0,
"id": "5e4b10afeee85432d7a38485"
}
}

put
Обновление данных карты

https://api.growcards.ru/v1/passes
Метод для обновления информации на карте клиента по серийному номеру или по ID карты. После каждого обновления на устройство пользователя, где установлена карта отправляется PUSH уведомление. Серийный номер карты содержится в данных штрих-кода на электронной карте клиента.
Request
Response
Request
Headers
X-SECRET-KEY
required
string
Интеграционный ключ компании
Query Parameters
passId
optional
string
ID карты
serialNumber
optional
string
Серийный номер карты
Body Parameters
fields
required
string
Объект с полями из шаблона карты в формате ключ:значение
Response
200: OK
Карта успешно обновлена. Если к карте привязано устройство, то на него отправлено уведомление
{
"card": {
"template": {
"id": "5e467b05258120641621e6a2",
"type": "loyaltyCard"
},
"additionalFields": [
{
"key": "discount",
"value": "20%"
}
],
"formDataFields": [],
"_id": "5e4b10afeee85432d7a38485",
"name": "Иван Иванов",
"phone": "79211234567",
"serialNumber": "8791825079",
"company": "5e467951258120641621e6a0",
"informationMessage": "",
"created_at": "2020-02-17T22:16:15.936Z",
"updated_at": "2020-02-17T22:33:38.768Z",
"__v": 1,
"id": "5e4b10afeee85432d7a38485"
},
"notifications": {
// ответы от сервисов отправки уведомлений
}
"devices": {
// список устройств, на которое отправленны уведомления
}
}
400: Bad Request
Не заданы необходимые параметры в теле запроса
{ "message": "Update data not provided" }
// ... or if unknown fields provided
{ "message": "Unknown fields",
"info": ["fieldName1", "fieldName2"]
}
401: Unauthorized
Указан неверный интеграционный ключ или нет доступа к компании
{ "message": "Invalid secret key" }
// ... or if company access error
{ "message": "You don't have access to this company" }
404: Not Found
Карта не найдена
{ "message": "Card not found" }

Пример тела запроса

{
"fields": {
"bonuses": "220"
}
}

Если в объекте fields переданы ключи полей, отсутствующие в шаблоне, то сервис вернет ошибку 400 и список ошибочных полей.

В теле запроса обязателен как минимум один параметр. При отправке обновления с несколькими параметрами в PUSH-уведомлении отобразится сообщение "Данные карты обновлены", поэтому мы рекомендуем отправлять обновление с одним параметром для отображения в уведомлении уникального сообщения с обновленными данными.

Обратите внимание

Если обновляемые данные совпадают с текущими данными на карте пользователя, то PUSH-уведомление не придет, т.к. в карте не будет обновлений.

post
Отправка PUSH-уведомления

https://api.growcards.ru/v1/passes/notification
Отправка текстового PUSH-уведомления на карту по серийному номеру или ID карты.
Request
Response
Request
Headers
X-SECRET-KEY
required
string
Интеграционный ключ компании
Query Parameters
serialNumber
optional
string
Серийный номер карты
passId
optional
string
ID карты
Body Parameters
message
required
string
Текст уведомления
Response
200: OK
Уведомление успешно отправлено
{
"notifications": [
{
"sent": [
{
"device": "6dbd70edf07b33722acd0d34b543233a7105e3b110e4ce4b475a03a124220828"
}
],
"failed": []
}
],
"devices": [
{
"_id": "5e468d0cea480564477a6da8",
"version": "v1",
"deviceLibraryIdentifier": "b9833fe68462f0568a249375c38fa426",
"passTypeIdentifier": "pass.com.growire.loyalty",
"serialNumber": "1282295653",
"pushToken": "6dbd70edf07b33722acd0d34b543233a7105e3b110e4ce4b475a03a124220828",
"os": "ios",
"application": "apple wallet",
"created_at": "2020-02-14T12:05:32.194Z",
"updated_at": "2020-02-17T22:53:49.334Z",
"__v": 0,
"cardUpdatedAt": "2020-02-17T22:53:49.332Z"
}
]
}
400: Bad Request
Не задан текст уведомления
{
"message": "Notification message not provided"
}
404: Not Found
Карта не найдена или к карте не привязано устройство
{
"message": "Card not found"
}
// ... or device not found
{
"message": "Device associated with card not found"
}

Обратите внимание

Если отправляемое сообщение полностью совпадает с последним отправленным сообщением, то PUSH-уведомление не придет, т.к. в карте не будет обновлений.