GrowCards
GrowCards
О сервисе
Личный кабинет
[email protected]
VK
Добро пожаловать
Помощь
Пользователям
Начало работы
Компания
Шаблон карты
Распространение
Карты
Интеграции
Разработчикам
Общие сведения
Интеграционный ключ
GrowCards Passes API v2
WebHooks
Powered by GitBook

GrowCards Passes API v2

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

Коллекция в Postman

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

get
Список карт

https://api.growcards.ru/v2/passes
Получение списка выпущенных карт. По умолчанию возвращает все карты, созданные в рамках компании. Для получения карт, созданных в рамках шаблона, укажите в параметрах запроса templateId
Request
Response
Request
Headers
X-SECRET-KEY
required
string
Интеграционный ключ компании
Query Parameters
limit
optional
number
Количество карт на страницу (по умолчанию 10)
page
optional
number
Номер страницы
template
optional
string
ID шаблона
Response
200: OK
В массиве 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.

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

https://api.growcards.ru/v2/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": "[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: Bad Request
Неверно указан ID карты
{
    "statusCode": 400,
    "message": "Invalid ID",
    "error": "Bad Request"
}
404: Not Found
Карта с заданным ID не найдена
{
    "statusCode": 404,
    "message": "Not Found"
}

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

https://api.growcards.ru/v2/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": "[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: Bad Request
Неверно указан ID карты
{
    "statusCode": 400,
    "message": "Invalid ID",
    "error": "Bad Request"
}
404: Not Found
Карта с заданным серийным номером не найдена
{
    "statusCode": 404,
    "message": "Not Found"
}

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

https://api.growcards.ru/v2/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
201: Created
Тело ответа содержит ID созданной карты и её серийный номер
{
    "id": "6058f4c296d7dc2fb8b6ea52",
    "serialNumber": "9024585895"
}
400: Bad Request
Не указаны необходимые параметры для создания карты или неверно указан ID шаблона
Required fields
Wrong Template 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: Not Found
Шаблон не найден
{
    "statusCode": 404,
    "message": "Template Not Found",
    "error": "Not Found"
}
409: Conflict
Карта с заданным номером телефона уже создана в системе
{
    "statusCode": 409,
    "message": "Card with phone 79218678737 already exists",
    "error": "Conflict"
}

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

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

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

https://api.growcards.ru/v2/passes/:passId
Метод для обновления информации на карте клиента по ID карты. После каждого обновления на устройство пользователя, где установлена карта отправляется PUSH уведомление. Серийный номер карты содержится в данных штрих-кода на электронной карте клиента.
Request
Response
Request
Path Parameters
passId
required
string
ID карты клиента
Headers
X-SECRET-KEY
required
string
Интеграционный ключ компании
Body Parameters
phone
optional
string
Телефон владельца карты
name
optional
string
Имя владельца карты
fields
required
object
Объект с полями из шаблона карты в формате ключ:значение
Response
200: OK
Карта успешно обновлена. Если к карте привязано устройство, то на него отправлено уведомление.
{
    "id": "604fe30a25e0573d50bd131a",
    "serialNumber": "5064375019"
}
400: Bad Request
Для обновления отправлены несуществующие поля в карте или не заданы необходимые параметры в теле запроса
Unknown Fields
Validation Error
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: Not Found
Карта не найдена
{
    "statusCode": 404,
    "message": "Not Found"
}

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

https://api.growcards.ru/v2/passes/s/:serialNumber
Метод для обновления карты клиента по серийному номеру
Request
Response
Request
Path Parameters
serialNumber
required
string
Серийный номер карты
Headers
X-SECRET-KEY
required
string
Интеграционный ключ компании
Body Parameters
phone
optional
string
Телефон владельца карты
name
optional
string
Им владельца карты
fields
required
object
Объект с полями из шаблона карты в формате ключ:значение
Response
200: OK
Карта успешно обновлена. Если к карте привязано устройство, то на него отправлено уведомление.
{
    "id": "604fe30a25e0573d50bd131a",
    "serialNumber": "5064375019"
}
400: Bad Request
Для обновления отправлены несуществующие поля в карте или не заданы необходимые параметры в теле запроса.
Unknown Fields
Validation Error
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: Not Found
Карта не найдена
{
    "statusCode": 404,
    "message": "Not Found"
}

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

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

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

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

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

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

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

https://api.growcards.ru/v2/passes/:passId/notification
Отправка текстового PUSH-уведомления на карту по ID карты.
Request
Response
Request
Path Parameters
passId
required
string
ID карты клиента
Headers
X-SECRET-KEY
required
string
Интеграционный ключ компании
Body Parameters
message
required
string
Текст уведомления
Response
200: OK
Уведомление успешно отправлено
{
    "id": "604fe30a25e0573d50bd131a",
    "serialNumber": "5064375019",
    "message": "Текстовое уведомление!"
}
400: Bad Request
Не задан текст уведомления или неверно указан ID карты
Required FIelds
Invalid 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: Not Found
Карта не найдена
{
    "statusCode": 404,
    "message": "Not Found"
}

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

https://api.growcards.ru/v2/passes/s/:serialNumber/notification
Отправка текстового PUSH-уведомления на карту по серийному номеру карты.
Request
Response
Request
Path Parameters
serialNumber
required
string
Серийный номер карты
Headers
X-SECRET-KEY
required
string
Интеграционный ключ компании
Body Parameters
message
required
string
Текст уведомления
Response
200: OK
Уведомление успешно отправлено
{
    "id": "604fe30a25e0573d50bd131a",
    "serialNumber": "5064375019",
    "message": "Текстовое уведомление!"
}
400: Bad Request
Не задан текст уведомления или неверно указан ID карты
Required FIelds
Invalid 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: Not Found
Карта не найдена
{
    "statusCode": 404,
    "message": "Not Found"
}

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

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

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

https://api.growcards.ru/v2/templates/:templateId/notification
Отправка текстового PUSH-уведомления всем картам в заданном шаблоне, либо выбранным картам
Request
Response
Request
Path Parameters
templateId
required
string
ID шаблона
Headers
X-SECRET-KEY
required
string
Интеграционный ключ компании
Body Parameters
cards
optional
string
Массив с ID карт
message
required
string
Текст уведомления
Response
200: OK
Уведомления успешно отправлены
{
    "count": 7, // количество карт 
    "message": "Групповое уведомление"
}
400: Bad Request
Неверно указан один из ID карт, либо неверно заполнены требуемые поля
Invalid ID
Required Fields
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: Not Found
Карты не найдены
{
    "statusCode": 404,
    "message": "Not Found"
}

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

Разработчикам - Previous
Интеграционный ключ
Next - Разработчикам
WebHooks
Last updated 2 months ago
Contents
Коллекция в Postman
get
Список карт
get
Объект карты по ID
get
Объект карты по серийному номеру
post
Создание карты
Пример тела запроса
put
Обновление данных карты по ID
put
Обновление данных карты по серийному номеру
Пример тела запроса
post
Отправка PUSH-уведомления по ID карты
post
Отправка PUSH-уведомления по серийному номеру
post
Групповая отправка PUSH-уведомлений