# API

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

Параметры могут передаваться как методом GET, так и POST. Если вы будете передавать большие данные (больше 2 килобайт), следует использовать POST.

Все вызовы методов имеют частотное ограничение 10 запросов в секунду. Ответ в формате JSON.

## rating.get

Возвращает рейтинг пользователей.

```
https://appcm.ru/api/rating.get?count=100&group_id=ID сообщества&secret_key=Секретный ключ
```

**count**\
\&#xNAN;*Положительное число. По умолчанию 10.*\
Количество первых мест рейтинга, которые нужно вернуть. Максимум 1000 за один запрос, поэтому если нужно больше используйте параметр offset. 

**offset**\
\&#xNAN;*Положительное число. По умолчанию 0.*\
Смещение, необходимое для выборки определенного подмножества участников. 

**secret\_key**\
\&#xNAN;*Строка. Обязательный параметр.*\
Секретный ключ сообщества.

**group\_id**\
\&#xNAN;*Положительное число. Обязательный параметр.*\
Id сообщества.

Успешный ответ:

```javascript
{ 
 response: {
  count: 3,
  users: [
   {
    id: 58420951,
    points: 100,
    likes: 45,
    comments: 12,
    karma: 110
   },
   {
    id: 80646760,
    points: 90,
    likes: 12,
    comments: 8,
    karma: 100
   },
   {
    id: 18480278,
    points: 50,
    likes: 7,
    comments: 5,
    karma: 100
   }
  ]
 }
}
```

## rating.getById

Возвращает информацию о пользователе из рейтинга.

```
https://appcm.ru/api/rating.getById?group_id=ID сообщества&user_id=ID пользователя&secret_key=Секретный ключ
```

**secret\_key**\
\&#xNAN;*Строка. Обязательный параметр.*\
Секретный ключ сообщества.

**group\_id**\
\&#xNAN;*Положительное число. Обязательный параметр.*\
Id сообщества. Соответствует идентификатору сообщества из ВКонтакте.

**user\_id**\
\&#xNAN;*Положительное число. Обязательный параметр.*\
Id пользователя. Соответствует идентификатору пользователя из ВКонтакте.

Успешный ответ:

```javascript
{ 
 response: {
  id:137777,
  points:709,
  karma:120,
  level:3,
  likes:2,
  comments:5,
  place:11
 }
}
```

## users.changePoints

Добавляет или отнимает баллы у заданных пользователей.

```
https://appcm.ru/api/users.changePoints?user_ids=ID пользователей&points=Количество баллов&group_id=ID сообщества&secret_key=Секретный ключ
```

**user\_ids**\
\&#xNAN;*Строка с числами. Обязательный параметр.*\
Числовые идентификаторы пользователей ВКонтакте, баллы которых нужно изменить. Можно управлять сразу несколькими. Для этого укажите id через запятую.

**points** \
\&#xNAN;*Строка с числами. Обязательный параметр.*\
Сколько баллов нужно добавить или отнять (число со знаком минус «-»). Можно указать либо одно число для всех, либо несколько через запятую для разного количества разным людям. Сопоставление пользователя и баллов происходит по порядку. Если в графе «points» задано меньшее количество чисел, чем айдишников, к не сопоставленным будет применяться последняя цифра. \
\
Пример запроса:

```
https://appcm.ru/api/users.changePoints?user_ids=5434511,9223337,123434,84652222&points=200,100,-50&group_id=ID сообщества&secret_key=a2c71b549185297480f0a66d209ff1ebfb215e1081e7bef62
```

В нашем случае, первому юзеру с id 5434511 будет добавлено 200 баллов, второму 9223337 плюс 100 баллов, а третьему 123434 и всем последующим, а у нас это только 84652222, снимется 50 баллов.

**secret\_key**\
\&#xNAN;*Строка. Обязательный параметр.*\
Секретный ключ сообщества.

**group\_id**\
\&#xNAN;*Положительное число. Обязательный параметр.*\
Id сообщества.

Успешный ответ:

```javascript
{ 
 response: 1 
}
```

{% hint style="info" %}
Изменение баллов через данный метод отображается в [истории начислений](https://docs.appcm.ru/osnovy/ballnaya-sistema/istoriya).
{% endhint %}

## users.resetPoints

Обнуляет/сбрасывает баллы у заданных пользователей.

```
https://appcm.ru/api/users.resetPoints?user_ids=ID пользователей&group_id=ID сообщества&secret_key=Секретный ключ
```

**user\_ids**\
\&#xNAN;*Строка с числами. Обязательный параметр.*\
*Ч*исловые идентификаторы пользователей ВКонтакте, баллы которых нужно обнулить.

**secret\_key**\
\&#xNAN;*Строка. Обязательный параметр.*\
Секретный ключ сообщества.

**group\_id**\
\&#xNAN;*Положительное число. Обязательный параметр.*\
Id сообщества.

Успешный ответ:

```javascript
{ 
 response: 1 
}
```

## users.ban

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

```
https://appcm.ru/api/users.ban?user_ids=ID пользователей&group_id=ID сообщества&secret_key=Секретный ключ
```

**user\_ids**\
\&#xNAN;*Строка с числами. Обязательный параметр.*\
*Ч*исловые идентификаторы пользователей ВКонтакте, которых нужно добавить в черный список.

**secret\_key**\
\&#xNAN;*Строка. Обязательный параметр.*\
Секретный ключ сообщества.

**group\_id**\
\&#xNAN;*Положительное число. Обязательный параметр.*\
Id сообщества.

Успешный ответ:

```javascript
{ 
 response: 1 
}
```

## users.unban

*Убирает пользователя из черного списка.*

```
https://appcm.ru/api/users.ban?user_ids=ID пользователей&group_id=ID сообщества&secret_key=Секретный ключ
```

**user\_ids**\
\&#xNAN;*Строка с числами. Обязательный параметр.*\
*Ч*исловые идентификаторы пользователей ВКонтакте, которых нужно исключить из черного списка.

**secret\_key**\
\&#xNAN;*Строка. Обязательный параметр.*\
Секретный ключ сообщества.

**group\_id**\
\&#xNAN;*Положительное число. Обязательный параметр.*\
Id сообщества.

Успешный ответ:

```javascript
{ 
 response: 1 
}
```

## Ошибки

При неудачном запросе приходит ответ в формате:

```javascript
{
 error: {
  error_code:4,
  error_msg:"One of the parameters is missing or invalid."
 }
}
```

**Коды ошибок:**

1 — отсутствуют обязательные параметры;\
2 — отсутствует секретный ключ;\
3 — секретный ключ недействителен;\
4 — один из параметров отсутствует или недействителен.\
1000 — слишком много запросов в секунду.