# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.growcards.ru/developers/api-methods.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.