# Добро пожаловать

Описание сервиса электронных карт GrowCards и основных принципов работы

### Привет!

Мы очень рады видеть вас среди пользователей **GrowCards** :)

Чтобы использование системы прошло максимально гладко, мы создали эту базу знаний, где вы можете найти подробную информацию по каждой функции GrowCards и узнать все основные принципы работы.

Уверены, что вам очень понравится!

{% hint style="success" %}
Если у вас возникают вопросы по использованию системы - сразу пишите в наш чат, расположенный в правой нижней части личного кабинета. Наши специалисты ответят на все интересующие вопросы :)
{% endhint %}

### Общая информация

Здесь мы собрали основную информацию по использованию нашего сервиса.

{% content-ref url="/pages/-Lyjo\_DLCB1ybgxbSM5X" %}
[Начало работы](/users/start)
{% endcontent-ref %}

Также мы собрали ответы на самые часто задаваемые вопросы

{% content-ref url="/pages/-LykAMl7A5EUQ61lg7uP" %}
[Помощь](/help)
{% endcontent-ref %}

### Разработчикам

Для подключения GrowCards к вашей системе мы создали удобное API, подробное описание которого вы найдете в соответствующем разделе

{% content-ref url="/pages/-LyjotN9Xx7-r16q6IPC" %}
[Разработчикам](/developers/general)
{% endcontent-ref %}


# Помощь

Здесь мы собрали ответы на самые часто задаваемые вопросы.

## Что такое GrowCards?

**GrowCards** позволяет компаниям и различным заведениям разрабатывать, выпускать и распространять собственные электронные карты.

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

## Что такое электронная карта?

Электронная карта - аналог традиционной пластиковой карты для ваших клиентов, но с несравнимо более широкими возможностями для вашего бизнеса.

Карта хранится непосредственно на смартфоне ваших клиентов и может содержать в себе самые разные данные:

* Имя владельца карты
* Данные системы лояльности
* Серийный номер карты
* Контактную информацию вашей организации
* Последние новости
* **И многое другое!**

И все эти данные вы можете обновлять в любой момент времени, **включая дизайн!**

## Что еще умеет электронная карта?

* Карта будет автоматически отображаться на смартфоне клиента, когда он находится рядом с вашим заведением
* Вы можете отправлять PUSH-уведомления прямо на устройства клиентов
* Можно настроить желаемый формат штрих-кода карты

## Какие телефоны поддерживают карту?

Мы создаем карту в формате .pkpass - это специальный формат электронных карт, разработанный компанией Apple. Соответственно, все устройстве на базе **iOS** поддерживают весь функционал созданных у нас карт.

Для пользователей **Android** мы предлагаем установить карты в **Google Pay** - это нативное приложение от Google, разработанное специально под устройства Android.

{% hint style="success" %}
Кроме того, у многих пользователей уже стоят различные приложения, которые поддерживают формат .pkpass. Если они не хотят добавлять карту в Google Pay - они без проблем добавят нашу карту в одно из таких приложений.
{% endhint %}

## Что насчет PUSH-уведомлений?

Карты, загруженные на устройства с **iOS** поддерживают весь функционал уведомлений, доступный в нашем сервисе, включая уведомления по геопозиции.

Сервис **Google Pay** полностью поддерживает уведомления по геопозиции, однако PUSH-уведомления пока что не входят в их функционал.

{% hint style="success" %}
Но данный сервис активно развивается и мы ожидаем в ближайшее время появления подобного функционала!
{% endhint %}

Некоторые сторонние приложения для Android, поддерживающие формат .pkpass также поддерживают функционал уведомлений по гео-позиции и PUSH-уведомлений.

{% hint style="info" %}
Мы интегрированны с некоторыми подобными приложениями и при регистрации пользователю предлагается добавить карту именно в эти приложения.
{% endhint %}

## Вы сможете интегрироваться с нашей системой?

**Да!**

Разрабатывая **GrowCards** мы сразу учитывали важность осуществления удобной и гибкой интеграции, поэтому мы сделали **API GrowCards,** с помощью которого мы сможем подключить наш сервис к вашей системе в самые кратчайшие сроки.

{% content-ref url="/pages/-LyjotN9Xx7-r16q6IPC" %}
[Разработчикам](/developers/general)
{% endcontent-ref %}


# Начало работы

Добро пожаловать в сервис электронных карт GrowCards!

## Подключение

Если вы решили подключить GrowCards к вашему заведению, то обратитесь к техническую поддержку через чат и мы сориентируем вас по дальнейшим шагам. 

## Личный кабинет

Все действия в нашей системе осуществляются через ваш персональный [личный кабинет](https://app.growcards.ru).

Для регистрации достаточно email адреса - после ввода вы сразу получите доступ, а на вашу почту мы отправим временный пароль и ссылку для подтверждения email адреса.

{% hint style="warning" %}
Не забудьте сменить временный пароль в настройках вашего профиля и подтвердить email адрес.
{% endhint %}

{% hint style="success" %}
Мы уже создали для вас тестовые данные в каждом из разделов, чтобы вы сразу могли ознакомиться со всем функционалом системы.

**Во время ознакомления с сервисом вы можете создать максимум 5 новых электронных карт через формы регистрации.**
{% endhint %}

### Хотите ознакомиться со всеми функциями с нуля? Начните с создания компании!

{% content-ref url="/pages/-Lyk4heVhJCtrRZ5J3-y" %}
[Новая компания](/users/company/new-company)
{% endcontent-ref %}


# Компания

Компании в личном кабинете

### Общая информация

Каждая созданная электронная карта в нашем сервисе привязана к определенной компании.

В вашем аккаунте может быть столько компаний, сколько вы пожелаете.

Список ваших компаний можно посмотреть в разделе "Мои компании".

#### Давайте создадим вашу первую компанию!

{% content-ref url="/pages/-Lyk4heVhJCtrRZ5J3-y" %}
[Новая компания](/users/company/new-company)
{% endcontent-ref %}


# Новая компания

Создание компании в GrowCards

Перед созданием шаблона карты вам нужно создать компанию в вашем личном кабинете.

### Создание компании

Процесс создания новой компании очень простой:

1. Выберите пункт "Создать компанию" в меню, либо на странице списка компаний нажмите "Создать новую компанию"
2. Введите название вашей компании и описание (опционально)
3. Нажмите "Создать"
4. Готово!

{% hint style="warning" %}
Имя компании является уникальным, вы не сможете создать две компании с одним именем.
{% endhint %}

#### **Теперь вы можете отредактировать данные компании или создать шаблон карты**


# Шаблон карты

Описание принципов работы с шаблонами карты в GrowCards

### Общая информация

Шаблон карты - главный элемент в системе **GrowCards**. Именно на основе вашего шаблона будут создаваться новые электронные карты клиентов.

**GrowCards** предоставляет мощный инструмент для гибкого создания уникального шаблона карты.

Каждый созданный шаблон привязан к одной из ваших компаний. В рамках одной компании вы можете создать несколько шаблонов.

Перейдем к созданию вашего шаблона!

{% content-ref url="/pages/-Lz-Sx6O1BkGSFc62ZTG" %}
[Новый шаблон](/users/template/new-template)
{% endcontent-ref %}


# Новый шаблон

Для создания нового шаблона карты нажмите "Создать шаблон" в основном меню.

### Основные данные

Прежде чем перейти к детальному редактированию шаблона, заполните основные данные:

1. Выберите компанию, в которой хотите создать шаблон
2. Укажите название шаблона
3. Укажите описание шаблона (при желании)
4. Нажмите "Создать"

После этого можно приступать к детальному редактированию шаблона.

{% content-ref url="/pages/-Lz-X51NTfRN5Ht41HaD" %}
[Редактирование шаблона](/users/template/edit-template)
{% endcontent-ref %}


# Редактирование шаблона

Описание возможностей редактирования шаблона карты

Настройки шаблона карты в системе GrowCards делятся на 3 основные категории.

Итоговый вид вашей карты сразу обновляется в правой части экрана при каждом изменении.

## 1. Лицевая сторона

Лицевая сторона карты - это первое, что видит пользователь при открытии вашей карты.

### Настройка полей

Для вашей карты всегда доступны поля с именем владельца и серийным номером карты. Вы можете изменить названия этих полей или скрыть их

Также вы можете добавить 2 дополнительных основных поля и поле в правой верхней части карты. Эти поля можно настроить максимально гибко:

1. Название поля
2. Значение по умолчанию
3. Уведомление при изменении поля
4. Отображение поля
5. Ключ поля

{% hint style="warning" %}
**Обратите внимание!**

Если вы хотите использовать поле для отображения бонусов, то используйте ключ **bonuses**, для кэшбека - **cashback**, для процента скидки - **discount**.

Эти ключи зарезервированы в нашей системе для правильной работы интеграций с внешними системами.
{% endhint %}

{% hint style="success" %}
Если вы указали текст для уведомления, то при каждом обновлении поля пользователю будут приходить PUSH-уведомления.

В тексте уведомления обязательно наличие "**%@**", именно вместо этих символов подставляется новое присланное значение этого поля.
{% endhint %}

{% hint style="warning" %}
**Ключ поля** должен быть уникальным. Этот ключ используется при обновлении данных карты через наше [API](/developers/api-methods).
{% endhint %}

### Настройка цвета

Каждая карта использует 3 основных цвета:

1. Фон - цвет для подложки карты
2. Текст - цвет для значения полей карты
3. Названия - цвет для названий полей карты

Вы можете задать любой цвет для этих элементов с помощью инструмента подбора цвета, либо указав HEX-код цвета.

### Настройка изображений

Для карты можно загрузить два изображения:

1. Логотип - изображение в левой верхней части карты
2. Основное - прямоугольное изображение в основной части карты

{% hint style="success" %}
Мы подготовили для вас макеты этих изображений в подходящих размерах, на основе которых вы можете создать собственные варианты.

* Логотип - 
* Основное - 
  {% endhint %}

### Настройка параметров карты

Вы можете задать тип отображаемого штрих-кода на карте, а также включить отображение названия компании справа от логотипа.

Типы штрих-кодов:

* QR-код
* PDF417
* Aztec
* Code128

Для обновления шаблона нажмите кнопку "Сохранить".

## 2. Обратная сторона

Для обратной стороны карты вы можете добавить собственные текстовые блоки. Каждый блок представляет из себя структуру из двух полей:

* Название блока
* Текст блока

Для создания нового блока нажмите на плюсик и задайте параметры блока. Если в тексте блока содержатся номера телефонов или ссылки - они автоматически станут активными для пользователя.

Для редактирования или удаления поля нажмите на соответствующую иконку справа от поля.

Для обновления шаблона нажмите кнопку "Сохранить".

## 3. Местоположение

Вы можете добавить несколько гео-точек к вашей карте, чтобы пользователю отображалось уведомление с вашей картой на заблокированном экране, когда он находится рядом с одной точек.

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

Вы можете проверить корректность адреса на карте, нажав кнопку "показать на карте".

Для обновления шаблона нажмите кнопку "Сохранить".


# Распространение

Описание принципов распространения карты пользователям

Для распространения карт пользователям в системе **GrowCards** используется раздел **"Формы"**

Вы создаете форму для каждого шаблона карты. С помощью формы ваши клиенты могут заполнять необходимые данные и получать карты на свое устройство.

Начните с создания формы:

{% content-ref url="/pages/-M-UnBgks-tWZiCDqYij" %}
[Новая форма](/users/share/new-form)
{% endcontent-ref %}


# Новая форма

Для создания формы перейдите в раздел "Новая форма" в основном меню и заполните основные данные:

1. Выберите шаблон, для которого вы создаете форму
2. Укажите название формы. Этот название будет отображаться пользователям на странице формы
3. При желании укажите описание формы. Оно также будет отображаться пользователям на странице формы

После создания можно перейти к детальному редактированию формы:

{% content-ref url="/pages/-M-Uo6DkJqVXXcu8Xnvc" %}
[Редактирование формы](/users/share/share-form)
{% endcontent-ref %}


# Редактирование формы

В форме регистрации всегда отображаются и обязательны к заполнения следующие поля:

1. Имя
2. Фамилия
3. Телефон

### Дополнительные поля

Вы можете добавить дополнительные текстовые поля в вашу форму.

Для каждого поля нужно задать название и ключ поля.

{% hint style="info" %}
Ключ должен быть уникальным для каждого поля
{% endhint %}

Вы можете сделать дополнительные обязательным к заполнению, а также временно отключить это поле в форме.

### Распространение формы

В правой части редактора формы отображается ссылка на форму и уникальный QR-код формы, в котором содержится ссылка на созданную форму регистрации.

{% hint style="success" %}
Вы можете изменять форму в любой момент - ссылка и QR-код останутся такими же.
{% endhint %}

Для регистрации пользователей вы можете как распространять прямую ссылку на форму, так и скачать QR-код формы и разместить его в нужных вам местах.


# Карты

Описание раздела "Карты" в системе GrowCards

В этом разделе вы видите все созданные пользователями электронные карты и их подробную информацию.

Список отсортирован по дате создания карт, самые новые - наверху.

Можно отфильтровать карты по шаблону или по значению одного из параметров карты с помощью фильтров.


# Детали карты

Вы можете посмотреть и отредактировать детали каждой созданной в системе электронной карты.

Данные карты мы разделили на 3 вкладки.

## Детали шаблона

Здесь отображается информация на основе используемого шаблона карты, номер карты и дата создания карты.

Также отображаются все дополнительные поля, которые указаны в шаблоне карты и данные этих полей.

Вы можете изменить данные этих дополнительных полей.

{% hint style="success" %}
При обновлении этих данных пользователю придет PUSH-уведомление, если для этого поля задан текст [уведомления при изменении данных](/users/template/edit-template#nastroika-polei).
{% endhint %}

## Персональные данные

На данной вкладке отображаются личные данные пользователя карты:

* Имя
* Фамилия
* Телефон

...а также дополнительные поля, которые заполнил пользователь в форме регистрации.

## Устройства

Здесь отображается информация по устройствам, на которые установлена карта:

* Тип устройства (Android/iOS)
* Приложение
* Дата установки карты на устройство


# Интеграции

Вы можете подключить различные внешние системы для работы с электронным картами.

{% hint style="success" %}
Если вашей системы нет в списке - напишите нам и мы добавим для нее интеграцию!
{% endhint %}

{% content-ref url="/pages/-M-su30ZCBBBYN3b0h9O" %}
[Poster](/users/integrations/poster)
{% endcontent-ref %}


# Poster

Описание процесса подключения Poster

## Подключение

Для того, чтобы подключить **Poster** к системе **GrowCards**, перейдите на страницу редактирования компании, в нижней части страницы введите название аккаунта в **Poster** и нажмите подключить. После этого вы будете перенаправлены на страницу авторизации в **Poster**.

![Подключение Poster](/files/-M-uCm9H9sZ7UnfcLUwq)

Затем зайдите в нужный вам шаблон карты (шаблон должен быть уже создан), во вкладке "Общая информация" выберите группу клиентов из **Poster** и нажмите "обновить".

![Выбор группы клиентов](/files/-M-uD4pnIauY0csBdG-q)

Если для группы выбрана скидочная система лояльности, то полю в шаблоне карты, отвечающему за отображение скидки, необходимо задать ключ **discount.**

Если для группы используется бонусная система лояльности, то полю в шаблоне карты, отвечающему за количество бонусов необходимо задать ключ **bonuses**, а для поля с размером кэшбека - **cashback.**

{% hint style="success" %}
Теперь все гости, которые будут регистрироваться через вашу форму будут  попадать в **Poster** в выбранную группу клиентов.

Также для всех клиентов, созданных в **Poster** вручную в выбранной группе, автоматически будет создавать карта в нашей системе.
{% endhint %}

{% hint style="warning" %}
Обратите внимание, что при создании клиента в **Poster** необходимо указать номер телефона, чтобы для этого клиента автоматически создалась карта.
{% endhint %}

## Обновление данных

Вы можете обновлять персональные данные клиента как из **Poster**, так и из нашей системы напрямую - они синхронизируются.

Также данные автоматически обновляются при изменении бонусного счета клиента после закрытия заказа.

## Уведомления

Если вы используете бонусную систему лояльности и задали в настройках шаблона отображение уведомления при изменении поля с ключом **bonuses,** то при закрытии заказа с привязанным клиентом ему автоматически придет уведомлении об изменении бонусного счета.

## Синхронизация

Мы можем синхронизировать существующих клиентов из группы, автоматически создать для них электронные карты и привязать номер карты к клиенту в **Poster**.

После этого ваши клиенты смогут получить карты сразу после ввода номера телефона в форме регистрации, без необходимости повторно заполнять данные.

Для осуществления синхронизации просто напишите в чат поддержки.

{% hint style="warning" %}
Обратите внимание, что карты будут созданы только для клиентов, у которых в **Poster** задан номер телефона.
{% endhint %}


# Общие сведения

Описание основных принципов работы с GrowCards Passes API

### О нашем API

GrowCards Passes API предназначено для возможности интегрировать функционал создания и обновления электронных карт в вашу внутреннюю систему.

### Формат запросов

При общении с нашим API данные передаются в формате JSON по протоколу HTTPS.

```http
Content-Type: "application/json"
```

Описание структуры запросов и ответов смотрите на [странице описания методов API](/developers/api-methods).

{% hint style="warning" %}
Для некоторых запросов может потребоваться [интеграционный ключ](/developers/integrations).
{% endhint %}


# Интеграционный ключ

Описание принципов работы с интеграционным ключом GrowCards

### Получение интеграционного ключа

Для доступа к некоторым из методов может потребоваться интеграционный ключ, привязанный к компании.

Получить интеграционный ключ можно через ваш личный кабинет на странице компании, для этого достаточно нажать "Создать ключ".

### Использование интеграционного ключа

Полученный интеграционный ключ необходимо добавлять в заголовок запроса в поле **'X-SECRET-KEY'.**

```http
X-SECRET-KEY: {{your_secret_key}}
```

### **Обновление интеграцинного ключа**

Интеграционный ключ можно обновить в любой момент из вашего личного кабинета на странице соответствующей компании.

Для обновления ключа нажмите на иконку обновления справа от интеграционного ключа.

{% hint style="warning" %}
**Обратите внимание**

После обновления, методы, использующие старый интеграционный ключ перестанут работать. Поэтому, перед обновлением и установкой нового ключа убедитесь, что соответствующие методы не используются в данный момент, чтобы сохранить целостность данных между системой и клиентами.
{% endhint %}


# GrowCards Passes API v2

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

## Коллекция в Postman

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

{% file src="/files/-MWVFctx38-uQC\_W4U-U" %}
JSON коллекции
{% endfile %}

## Список карт

<mark style="color:blue;">`GET`</mark> `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 | Интеграционный ключ компании |

{% tabs %}
{% tab title="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
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
Метод поддерживает пагинацию. Если параметр **page** не указан, то будут возвращены все карты.

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

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

<mark style="color:blue;">`GET`</mark> `https://api.growcards.ru/v2/passes/:passId`

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

#### Path Parameters

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

#### Headers

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

{% tabs %}
{% tab title="200 Тело ответа содержит данные запрашиваемой карты" %}

```
{
    "_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": "У вас новый уровень: %@"
        }
    ]
}
```

{% endtab %}

{% tab title="400 Неверно указан ID карты" %}

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

{% endtab %}

{% tab title="404 Карта с заданным ID не найдена" %}

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

{% endtab %}
{% endtabs %}

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

<mark style="color:blue;">`GET`</mark> `https://api.growcards.ru/v2/passes/s/:serialNumber`

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

#### Path Parameters

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

#### Headers

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

{% tabs %}
{% tab title="200 Тело ответа содержит данные запрашиваемой карты" %}

```
{
    "_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": "У вас новый уровень: %@"
        }
    ]
}
```

{% endtab %}

{% tab title="400 Неверно указан ID карты" %}

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

{% endtab %}

{% tab title="404 Карта с заданным серийным номером не найдена" %}

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

{% endtab %}
{% endtabs %}

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

<mark style="color:green;">`POST`</mark> `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 шаблона        |

{% tabs %}
{% tab title="201 Тело ответа содержит ID созданной карты и её серийный номер" %}

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

{% endtab %}

{% tab title="400 Не указаны необходимые параметры для создания карты или неверно указан ID шаблона" %}
{% tabs %}
{% tab title="Required fields" %}

```javascript
{
    "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"
}
```

{% endtab %}

{% tab title="Wrong Template ID" %}

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

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="404 Шаблон не найден" %}

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

{% endtab %}

{% tab title="409 Карта с заданным номером телефона уже создана в системе" %}

```javascript
{
    "statusCode": 409,
    "message": "Card with phone 79218678737 already exists",
    "error": "Conflict"
}
```

{% endtab %}
{% endtabs %}

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

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

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

<mark style="color:orange;">`PUT`</mark> `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 | Объект с полями из шаблона карты в формате ключ:значение |

{% tabs %}
{% tab title="200 Карта успешно обновлена. Если к карте привязано устройство, то на него отправлено уведомление." %}

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

{% endtab %}

{% tab title="400 Для обновления отправлены несуществующие поля в карте или не заданы необходимые параметры в теле запроса" %}
{% tabs %}
{% tab title="Unknown Fields" %}

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

{% endtab %}

{% tab title="Validation Error" %}

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

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="404 Карта не найдена" %}

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

{% endtab %}
{% endtabs %}

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

<mark style="color:orange;">`PUT`</mark> `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 | Объект с полями из шаблона карты в формате ключ:значение |

{% tabs %}
{% tab title="200 Карта успешно обновлена. Если к карте привязано устройство, то на него отправлено уведомление." %}

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

{% endtab %}

{% tab title="400 Для обновления отправлены несуществующие поля в карте или не заданы необходимые параметры в теле запроса." %}
{% tabs %}
{% tab title="Unknown Fields" %}

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

{% endtab %}

{% tab title="Validation Error" %}

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

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="404 Карта не найдена" %}

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

{% endtab %}
{% endtabs %}

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

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

{% hint style="warning" %}
Если в объекте **fields** переданы ключи полей, отсутствующие в шаблоне, то сервис вернет ошибку **400** и список ошибочных полей.
{% endhint %}

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

{% hint style="warning" %}
**Обратите внимание**

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

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

<mark style="color:green;">`POST`</mark> `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 | Текст уведомления |

{% tabs %}
{% tab title="200 Уведомление успешно отправлено" %}

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

{% endtab %}

{% tab title="400 Не задан текст уведомления или неверно указан ID карты" %}
{% tabs %}
{% tab title="Required FIelds" %}

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

{% endtab %}

{% tab title="Invalid ID" %}

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

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="404 Карта не найдена" %}

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

{% endtab %}
{% endtabs %}

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

<mark style="color:green;">`POST`</mark> `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 | Текст уведомления |

{% tabs %}
{% tab title="200 Уведомление успешно отправлено" %}

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

{% endtab %}

{% tab title="400 Не задан текст уведомления или неверно указан ID карты" %}
{% tabs %}
{% tab title="Required FIelds" %}

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

{% endtab %}

{% tab title="Invalid ID" %}

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

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="404 Карта не найдена" %}

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

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
**Обратите внимание**

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

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

<mark style="color:green;">`POST`</mark> `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 | Текст уведомления |

{% tabs %}
{% tab title="200 Уведомления успешно отправлены" %}

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

{% endtab %}

{% tab title="400 Неверно указан один из ID карт, либо неверно заполнены требуемые поля" %}
{% tabs %}
{% tab title="Invalid ID" %}

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

{% endtab %}

{% tab title="Required Fields" %}

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

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="404 Карты не найдены" %}

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

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Если переданный массив **cards** пустой, то уведомление будет отправлено всем картам в шаблоне.
{% endhint %}


# WebHooks

Система GrowCards может отправлять уведомление после создания новой карты на ваш принимающий URL.

## Добавление WebHook

Перейдите на страницу вашей компании и нажмите кнопку **"Создать WebHook".**

Выберите формат отправляемых данных и укажите URL, на который система будет отправлять данные.

![](/files/-MXNBqN-bnONGJyI8eoa)

## Формат данных

Система отправляет данные **POST** запросом со следующим **JSON** объектом

```javascript
{
        _id: '60687d084ab37b37e7a58df9',
        name: 'Ivan Ivanov',
        phone: '79211234567',
        serialNumber: '1314827051',
        company: '604fddebf8a4763d25469444',
        template: '604fde02f8a4763d25469445'
}
```

{% hint style="info" %}
&#x20;WebHook считается успешно отправлен, если сервер вернул **HTTP STATUS 200**
{% endhint %}

## Тестирование WebHook

Вы можете протестировать созданный **WebHook** нажав соответствующую кнопку.

![](/files/-MXNCGB23Yo0LZfqxkcC)