> For the complete documentation index, see [llms.txt](https://docs.growcards.ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.growcards.ru/developers/api-methods.md).

# GrowCards Passes API v2

## Коллекция в 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 %}