GrowCards Passes API v2

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

Коллекция в Postman

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

10KB

GrowCards API V2.postman_collection.json

Open

JSON коллекции

Список карт

GET https://api.growcards.ru/v2/passes

Получение списка выпущенных карт. По умолчанию возвращает все карты, созданные в рамках компании. Для получения карт, созданных в рамках шаблона, укажите в параметрах запроса templateId

Query Parameters

Name	Type	Description
limit	number	Количество карт на страницу (по умолчанию 10)
page	number	Номер страницы
template	string	ID шаблона

Headers

Name	Type	Description
X-SECRET-KEY	string	Интеграционный ключ компании

200 В массиве data содержится список созданных карт

{
    "data": [
        {
            "_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"
                }
            ]
        },
        {...}
    ],
    "meta": {
        "total": 7,
        "limit": 10,
        "page": 1,
        "pages": 1
    }
}

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

При включенной пагинации по умолчанию отдаётся 10 объектов на страницу. Вы можете изменить это через параметр limit.

Объект карты по ID

GET https://api.growcards.ru/v2/passes/:passId

Получение данных выпущенной карты.

Path Parameters

Name	Type	Description
passId	string	ID карты клиента

Headers

Name	Type	Description
X-SECRET-KEY	string	Интеграционный ключ компании

200 Тело ответа содержит данные запрашиваемой карты

{
    "_id": "5e468c805d8d34644ebb34e6",
    "formDataFields": [
        {
            "key": "email",
            "value": "[email protected]"
        }
    ],
    "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": "У вас новый уровень: %@"
        }
    ]
}

400 Неверно указан ID карты

404 Карта с заданным ID не найдена

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

GET https://api.growcards.ru/v2/passes/s/:serialNumber

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

Path Parameters

Name	Type	Description
serialNumber	string	Серийный номер карты

Headers

Name	Type	Description
X-SECRET-KEY	string	Интеграционный ключ компании

200 Тело ответа содержит данные запрашиваемой карты

{
    "_id": "5e468c805d8d34644ebb34e6",
    "formDataFields": [
        {
            "key": "email",
            "value": "[email protected]"
        }
    ],
    "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": "У вас новый уровень: %@"
        }
    ]
}

400 Неверно указан ID карты

404 Карта с заданным серийным номером не найдена

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

POST https://api.growcards.ru/v2/passes

Создание клиентской карты на основе шаблона.

Headers

Name	Type	Description
X-SECRET-KEY	string	Интеграционный ключ компании

Request Body

Name	Type	Description
surname	string	Фамилия владельца
name	string	Имя владельца
phone	string	Номер телефона
template	string	ID шаблона

201 Тело ответа содержит ID созданной карты и её серийный номер

{
    "id": "6058f4c296d7dc2fb8b6ea52",
    "serialNumber": "9024585895"
}

400 Не указаны необходимые параметры для создания карты или неверно указан ID шаблона

404 Шаблон не найден

409 Карта с заданным номером телефона уже создана в системе

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

{
	"phone": "79211234567",
	"name": "Иван",
	"surname": "Иванов",
	"template": "604fde02f8a4763d25469445"
}

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

PUT https://api.growcards.ru/v2/passes/:passId

Метод для обновления информации на карте клиента по ID карты. После каждого обновления на устройство пользователя, где установлена карта отправляется PUSH уведомление. Серийный номер карты содержится в данных штрих-кода на электронной карте клиента.

Path Parameters

Name	Type	Description
passId	string	ID карты клиента

Headers

Name	Type	Description
X-SECRET-KEY	string	Интеграционный ключ компании

Request Body

Name	Type	Description
phone	string	Телефон владельца карты
name	string	Имя владельца карты
fields	object	Объект с полями из шаблона карты в формате ключ:значение

200 Карта успешно обновлена. Если к карте привязано устройство, то на него отправлено уведомление.

{
    "id": "604fe30a25e0573d50bd131a",
    "serialNumber": "5064375019"
}

400 Для обновления отправлены несуществующие поля в карте или не заданы необходимые параметры в теле запроса

404 Карта не найдена

Обновление данных карты по серийному номеру

PUT https://api.growcards.ru/v2/passes/s/:serialNumber

Метод для обновления карты клиента по серийному номеру

Path Parameters

Name	Type	Description
serialNumber	string	Серийный номер карты

Headers

Name	Type	Description
X-SECRET-KEY	string	Интеграционный ключ компании

Request Body

Name	Type	Description
phone	string	Телефон владельца карты
name	string	Им владельца карты
fields	object	Объект с полями из шаблона карты в формате ключ:значение

200 Карта успешно обновлена. Если к карте привязано устройство, то на него отправлено уведомление.

{
    "id": "604fe30a25e0573d50bd131a",
    "serialNumber": "5064375019"
}

400 Для обновления отправлены несуществующие поля в карте или не заданы необходимые параметры в теле запроса.

404 Карта не найдена

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

{
	"name": "Иван Иванов",
	"phone": "79211234567",
	"fields": {
		"bonuses": "220" 
	}
}

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

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

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

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

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

POST https://api.growcards.ru/v2/passes/:passId/notification

Отправка текстового PUSH-уведомления на карту по ID карты.

Path Parameters

Name	Type	Description
passId	string	ID карты клиента

Headers

Name	Type	Description
X-SECRET-KEY	string	Интеграционный ключ компании

Request Body

Name	Type	Description
message	string	Текст уведомления

200 Уведомление успешно отправлено

{
    "id": "604fe30a25e0573d50bd131a",
    "serialNumber": "5064375019",
    "message": "Текстовое уведомление!"
}

400 Не задан текст уведомления или неверно указан ID карты

404 Карта не найдена

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

POST https://api.growcards.ru/v2/passes/s/:serialNumber/notification

Отправка текстового PUSH-уведомления на карту по серийному номеру карты.

Path Parameters

Name	Type	Description
serialNumber	string	Серийный номер карты

Headers

Name	Type	Description
X-SECRET-KEY	string	Интеграционный ключ компании

Request Body

Name	Type	Description
message	string	Текст уведомления

200 Уведомление успешно отправлено

{
    "id": "604fe30a25e0573d50bd131a",
    "serialNumber": "5064375019",
    "message": "Текстовое уведомление!"
}

400 Не задан текст уведомления или неверно указан ID карты

404 Карта не найдена

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

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

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

POST https://api.growcards.ru/v2/templates/:templateId/notification

Отправка текстового PUSH-уведомления всем картам в заданном шаблоне, либо выбранным картам

Path Parameters

Name	Type	Description
templateId	string	ID шаблона

Headers

Name	Type	Description
X-SECRET-KEY	string	Интеграционный ключ компании

Request Body

Name	Type	Description
cards	string	Массив с ID карт
message	string	Текст уведомления

200 Уведомления успешно отправлены

{
    "count": 7, // количество карт 
    "message": "Групповое уведомление"
}

400 Неверно указан один из ID карт, либо неверно заполнены требуемые поля

404 Карты не найдены

Если переданный массив cards пустой, то уведомление будет отправлено всем картам в шаблоне.