GrowCards Passes API v2

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

Коллекция в Postman

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

10KB

GrowCards API V2.postman_collection.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": "[e-mail]"
        }
    ],
    "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 карты

{
    "statusCode": 400,
    "message": "Invalid ID",
    "error": "Bad Request"
}

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

{
    "statusCode": 404,
    "message": "Not Found"
}

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

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": "[e-mail]"
        }
    ],
    "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 карты

{
    "statusCode": 400,
    "message": "Invalid ID",
    "error": "Bad Request"
}

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

{
    "statusCode": 404,
    "message": "Not Found"
}

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

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 шаблона

Required fields

{
    "statusCode": 400,
    "message": [
        "surname should not be empty",
        "name should not be empty",
        "phone should not be empty",
        "template should not be empty"
    ],
    "error": "Bad Request"
}

Wrong Template ID

{
    "statusCode": 400,
    "message": "Invalid ID",
    "error": "Bad Request"
}

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

{
    "statusCode": 404,
    "message": "Template Not Found",
    "error": "Not Found"
}

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

{
    "statusCode": 409,
    "message": "Card with phone [phone] already exists",
    "error": "Conflict"
}

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

{
	"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 Для обновления отправлены несуществующие поля в карте или не заданы необходимые параметры в теле запроса

Unknown Fields

{
    "statusCode": 400,
    "message": "Unknown fields: someField, anotherField",
    "error": "Bad Request"
}

Validation Error

{
    "statusCode": 400,
    "message": [
        "fields should not be empty"
    ],
    "error": "Bad Request"
}

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

{
    "statusCode": 404,
    "message": "Not Found"
}

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

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 Для обновления отправлены несуществующие поля в карте или не заданы необходимые параметры в теле запроса.

Unknown Fields

{
    "statusCode": 400,
    "message": "Unknown fields: someField, anotherField",
    "error": "Bad Request"
}

Validation Error

{
    "statusCode": 400,
    "message": [
        "fields should not be empty"
    ],
    "error": "Bad Request"
}

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

{
    "statusCode": 404,
    "message": "Not Found"
}

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

{
	"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 карты

Required FIelds

{
    "statusCode": 400,
    "message": [
        "message must be a string",
        "message should not be empty"
    ],
    "error": "Bad Request"
}

Invalid ID

{
    "statusCode": 400,
    "message": "Invalid ID",
    "error": "Bad Request"
}

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

{
    "statusCode": 404,
    "message": "Not Found"
}

Отправка 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 карты

Required FIelds

{
    "statusCode": 400,
    "message": [
        "message must be a string",
        "message should not be empty"
    ],
    "error": "Bad Request"
}

Invalid ID

{
    "statusCode": 400,
    "message": "Invalid ID",
    "error": "Bad Request"
}

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

{
    "statusCode": 404,
    "message": "Not Found"
}

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

Если отправляемое сообщение полностью совпадает с последним отправленным сообщением, то 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 карт, либо неверно заполнены требуемые поля

Invalid ID

{
    "statusCode": 400,
    "message": "Invalid ID",
    "error": "Bad Request"
}

Required Fields

{
    "statusCode": 400,
    "message": [
        "message must be a string",
        "message should not be empty"
    ],
    "error": "Bad Request"
}

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

{
    "statusCode": 404,
    "message": "Not Found"
}

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