Документация API

Все запросы должны отправляться на адрес https://api.vkdonuts.ru/{метод}

Все запросы должны передаваться через метод POST в виде JSON массива. В заголовке Content-type должно передаваться application/json.

Текущая версия API 1. Версия API будет повышаться при изменении полей в старых методах. При добавлении новых полей, а также при добавлении новых методов, версия API НЕ будет повышаться.

Внимание! У API есть ограничения. Суточный лимит запросов - 3000. Не чаще одного запроса в 5 секунд.

Ниже приведен PHP класс для работы с API. Версия PHP не ниже 7.0.

class Donuts {
	private $group;
	private $token;
	private $v = 1;
	
	function __construct($group, $token) {
		$this -> group = $group;
		$this -> token = $token;
	}
	public function request($method, $params = []) {
		if (!isset($params['group'])) $params['group'] = $this -> group;
		if (!isset($params['token'])) $params['token'] = $this -> token;
		if (!isset($params['v'])) $params['v'] = $this -> v;
		
		$ch = curl_init();
		curl_setopt_array($ch, [
			CURLOPT_URL => 'https://api.vkdonuts.ru/' . $method,
			CURLOPT_HTTPHEADER => ['Content-type: application/json'],
			CURLOPT_RETURNTRANSFER => true,
			CURLOPT_POST => true,
			CURLOPT_POSTFIELDS => json_encode($params)
		]);
		$response = curl_exec($ch);
		curl_close($ch);

		return json_decode($response, true);
	}
}

Список кодов ошибок и их описание

Список методов API

  1. donates/get - Получение списка донатов
  2. donates/change-status - Изменить статус доната
  3. donates/answer - Добавить/изменить ответ сообщества на донат
  4. donates/change-reward-status - Изменить выдачи вознаграждения
  5. campaigns/get - Получить список краудфандинговых кампаний (последние 20 кампаний)
  6. campaigns/get-active - Получить активную краудфандинговую кампанию
  7. campaigns/get-rewards - Получить список вознаграждений краудфандинговой кампании
  8. campaigns/change - Обновить информацию о краудфандинговой кампании
  9. campaigns/change-reward - Обновить информацию о вознаграждении краудфандинговой кампании
  10. payments/get - Получить список заявок на выплату (последние 20 заявок)
  11. payments/create - Создать заявку на выплату
  12. balance - Получить баланс группы в приложении

donates/get Получение списка донатов

Параметры запроса:
Параметр Описание
groupinteger, обязательно VK ID группы.
tokenstring, обязательно Секретный токен.
vint, обязательно Номер версии api. Текущая версия 1.
leninteger Количество донатов в списке.
Максимум 100. По умолчанию 20.
offsetinteger Смещение по выборе донатов
start_dateinteger Временная метка по UNIX (в миллисекундах). Задает минимальную дату и время выбираемых донатов.
end_dateinteger Временная метка по UNIX (в миллисекундах). Задает максимальную дату и время выбираемых донатов.
sortstring Метод сортировки. По умолчанию date.
Возможные значения:
date - сортировка по дате;
amount - сортировка по сумме.
reverseboolean Направление сортировки. По умолчанию false.
Возможные значения:
false - сортировка по убыванию;
true - сортировка по возрастанию.
Ответ сервера:
Параметр Описание
successboolean, обязательно Успешность обработки запроса сервером.
errorinteger Если запрос выполнен с ошибкой, то будет возвращен код ошибки. См. список кодов ошибок.
msgstring Текстовое сообщение с результатом выполнения запроса.
listarray of objects Список донатов.
idinteger, обязательно ID донаты в системе.
userinteger, обязательно VK ID пользователя совершившего донат. Если донаты отправлен анонимно, то значение данного поле будет 0.
dateinteger, обязательно Временная метка по UNIX (в миллисекундах) даты и времени доната.
amountinteger, обязательно Сумма доната в рублях.
msgstring Сообщение прикрепленное к донату.
anonymbool, обязательно Анонимность доната.
answerstring Ответ администратора группы на донат.
vkpaybool, обязательно Если донат был отправлен через VK Pay, то значение данного поля будет равно true.
statusstring, обязательно Статус доната
Возможные значения:
new - новый донат;
public - опубликован;
hidden - скрыт.
rewardarray of objects Если не было выбрано вознаграждение, то данное поле будет отсутствовать.
idinteger, обязательно ID вознаграждения в системе.
titlestring, обязательно Название вознаграждения.
statusstring, обязательно Статус выдачи вознаграждения.
Возможные значения:
not_sended - не выдано;
sended - выдано.

Пример кода на PHP с использованием класса для работы с API.

$api = new Donuts(1, 'auth_token');
$result = $api -> request('donates/get', [
	'sort' => 'amount',
	'offset' => 30,
	'len' => 10
]);
print_r(result);

donates/change-status Изменить статус доната

Параметры запроса:
Параметр Описание
groupinteger, обязательно VK ID группы.
tokenstring, обязательно Секретный токен.
vint, обязательно Номер версии api. Текущая версия 1.
idinteger, обязательно ID доната в системе.
statusstring, обязательно Статус доната.
Возможные значения:
public - опубликован;
hidden - скрыт.
Ответ сервера:
Параметр Описание
successboolean, обязательно Успешность обработки запроса сервером.
errorinteger Если запрос выполнен с ошибкой, то будет возвращен код ошибки. См. список кодов ошибок.
msgstring Текстовое сообщение с результатом выполнения запроса.

Пример кода на PHP с использованием класса для работы с API.

$api = new Donuts(1, 'auth_token');
$result = $api -> request('donates/change-status', [
	'id' => 1,
	'status' => 'hidden'
]);
print_r(result);

donates/answer Добавить/изменить ответ сообщества на донат

Параметры запроса:
Параметр Описание
groupinteger, обязательно VK ID группы.
tokenstring, обязательно Секретный токен.
vint, обязательно Номер версии api. Текущая версия 1.
idinteger, обязательно ID доната в системе.
answerstring, обязательно Текст ответа. Для удаления ответа следует передать пустую строку.
Ответ сервера:
Параметр Описание
successboolean, обязательно Успешность обработки запроса сервером.
errorinteger Если запрос выполнен с ошибкой, то будет возвращен код ошибки. См. список кодов ошибок.
msgstring Текстовое сообщение с результатом выполнения запроса.

Пример кода на PHP с использованием класса для работы с API.

$api = new Donuts(1, 'auth_token');
$result = $api -> request('donates/answer', [
	'id' => 1,
	'answer' => 'Спасибо за помощь проекту! 😊'
]);
print_r(result);

donates/change-reward-status Изменить выдачи вознаграждения.

Параметры запроса:
Параметр Описание
groupinteger, обязательно VK ID группы.
tokenstring, обязательно Секретный токен.
vint, обязательно Номер версии api. Текущая версия 1.
idinteger, обязательно ID доната в системе.
statusstring, обязательно Статус выдачи вознаграждения.
not_sended - не вадно;
sended - выдано.
Ответ сервера:
Параметр Описание
successboolean, обязательно Успешность обработки запроса сервером.
errorinteger Если запрос выполнен с ошибкой, то будет возвращен код ошибки. См. список кодов ошибок.
msgstring Текстовое сообщение с результатом выполнения запроса.

Пример кода на PHP с использованием класса для работы с API.

$api = new Donuts(1, 'auth_token');
$result = $api -> request('donates/change-reward-status', [
	'id' => 1,
	'status' => 'sended'
]);
print_r(result);

campaigns/get Получить список краудфандинговых кампаний (последние 20 кампаний).

Параметры запроса:
Параметр Описание
groupinteger, обязательно VK ID группы.
tokenstring, обязательно Секретный токен.
vint, обязательно Номер версии api. Текущая версия 1.
idsarray of int Можно передать массив системных ID кампаний для выборки конкрентных кампаний. Если данный параметр не передан, то вернутся 20 последних кампаний.
Ответ сервера:
Параметр Описание
successboolean, обязательно Успешность обработки запроса сервером.
errorinteger Если запрос выполнен с ошибкой, то будет возвращен код ошибки. См. список кодов ошибок.
msgstring Текстовое сообщение с результатом выполнения запроса.
listarray of objects Список кампаний.
idinteger, обязательно ID кампании в системе.
titlestring, обязательно Заголовок кампании.
statusstring, обязательно Статус кампании.
draft - черновик;
active - активная кампания;
archive - кампания архивирована.
startinteger, обязательно Временная метка по unix (в миллисекундах) начала кампании.
endinteger, обязательно Временная метка по unix (в миллисекундах) окончания кампании.
pointinteger, обязательно Цель по сбору в рублях.
start_receivedinteger, обязательно Собрано за пределами приложения в рублях.
start_backersinteger, обязательно Кол-во спонсоров пожертвовавших за пределами приложения.
receivedinteger, обязательно Собрано на данный момент в рублях.
backersinteger, обязательно Кол-во спонсоров.

Пример кода на PHP с использованием класса для работы с API.

$api = new Donuts(1, 'auth_token');
$result = $api -> request('campaigns/get');
print_r(result);
$api = new Donuts(1, 'auth_token');
$result = $api -> request('campaigns/get', [
	'ids' => [1, 3]
]);
print_r(result);

campaigns/get-active Получить активную краудфандинговую кампанию.

Параметры запроса:
Параметр Описание
groupinteger, обязательно VK ID группы.
tokenstring, обязательно Секретный токен.
vint, обязательно Номер версии api. Текущая версия 1.
Ответ сервера:
Параметр Описание
successboolean, обязательно Успешность обработки запроса сервером.
errorinteger Если запрос выполнен с ошибкой, то будет возвращен код ошибки. См. список кодов ошибок.
msgstring Текстовое сообщение с результатом выполнения запроса.
campaignobject Объект кампании.
idinteger, обязательно ID кампании в системе.
titlestring, обязательно Заголовок кампании.
statusstring, обязательно Статус кампании.
draft - черновик;
active - активная кампания;
archive - кампания архивирована.
startinteger, обязательно Временная метка по unix (в миллисекундах) начала кампании.
endinteger, обязательно Временная метка по unix (в миллисекундах) окончания кампании.
pointinteger, обязательно Цель по сбору в рублях.
start_receivedinteger, обязательно Собрано за пределами приложения в рублях.
start_backersinteger, обязательно Кол-во спонсоров пожертвовавших за пределами приложения.
receivedinteger, обязательно Собрано на данный момент в рублях.
backersinteger, обязательно Кол-во спонсоров.

Пример кода на PHP с использованием класса для работы с API.

$api = new Donuts(1, 'auth_token');
$result = $api -> request('campaigns/get-active');
print_r(result);

campaigns/get-rewards Получить список вознаграждений краудфандинговой кампании.

Параметры запроса:
Параметр Описание
groupinteger, обязательно VK ID группы.
tokenstring, обязательно Секретный токен.
vint, обязательно Номер версии api. Текущая версия 1.
campaigninteger, обязательно ID кампании в системе.
Ответ сервера:
Параметр Описание
successboolean, обязательно Успешность обработки запроса сервером.
errorinteger Если запрос выполнен с ошибкой, то будет возвращен код ошибки. См. список кодов ошибок.
msgstring Текстовое сообщение с результатом выполнения запроса.
listarray of objects Массив объектов вознаграждений.
idinteger, обязательно ID вознаграждения в системе.
titlestring, обязательно Название вознаграждения.
descstring, обязательно Описание вознаграждения.
min_donateinteger, обязательно Минимальный донат для получения текущего вознаграждения.
limitsinteger Ограничение кол-во вознаграждений. Если ограничений нет, данное поле не передается.
statusstring, обязательно Статус вознаграждения.
public - вознаграждение опубликовано;
hidden - вознаграждение скрыто.
backersinteger, обязательно Кол-во спонсоров выбравших данное вознаграждение.

Пример кода на PHP с использованием класса для работы с API.

$api = new Donuts(1, 'auth_token');
$result = $api -> request('campaigns/get-rewards', [
	'campaign' => 1
]);
print_r(result);

campaigns/change Обновить информацию о краудфандинговой кампании.

Параметры запроса:
Параметр Описание
groupinteger, обязательно VK ID группы.
tokenstring, обязательно Секретный токен.
vint, обязательно Номер версии api. Текущая версия 1.
idinteger, обязательно ID кампании в системе.
titlestring Заголовок кампании.
statusstring Статус кампании.
draft - черновик;
active - активная кампания;
archive - кампания архивирована.
endinteger Временная метка по unix (в миллисекундах) окончания кампании.
pointinteger Цель по сбору в рублях.
start_receivedinteger Собрано за пределами приложения в рублях.
start_backersinteger Кол-во спонсоров пожертвовавших за пределами приложения.
Ответ сервера:
Параметр Описание
successboolean, обязательно Успешность обработки запроса сервером.
errorinteger Если запрос выполнен с ошибкой, то будет возвращен код ошибки. См. список кодов ошибок.
msgstring Текстовое сообщение с результатом выполнения запроса.

Пример кода на PHP с использованием класса для работы с API.

$api = new Donuts(1, 'auth_token');
$result = $api -> request('campaigns/change', [
	'id' => 1,
	'title' => 'Новое название кампании'
]);
print_r(result);

campaigns/change-reward Обновить информацию о вознаграждении краудфандинговой кампании.

Параметры запроса:
Параметр Описание
groupinteger, обязательно VK ID группы.
tokenstring, обязательно Секретный токен.
vint, обязательно Номер версии api. Текущая версия 1.
idinteger, обязательно ID вознаграждения в системе.
titlestring Название вознаграждения.
descstring Описание вознаграждения.
min_donateinteger Минимальный донат для получения текущего вознаграждения.
limitsinteger Ограничение кол-во вознаграждений. Если ограничений нет, данное поле должно быть равно 0.
statusstring Статус вознаграждения.
public - вознаграждение опубликовано;
hidden - вознаграждение скрыто.
Ответ сервера:
Параметр Описание
successboolean, обязательно Успешность обработки запроса сервером.
errorinteger Если запрос выполнен с ошибкой, то будет возвращен код ошибки. См. список кодов ошибок.
msgstring Текстовое сообщение с результатом выполнения запроса.

Пример кода на PHP с использованием класса для работы с API.

$api = new Donuts(1, 'auth_token');
$result = $api -> request('campaigns/change-reward', [
	'id' => 1,
	'title' => 'Новое название вознаграждения'
]);
print_r(result);

payments/get Получить список заявок на выплату (последние 20 заявок).

Параметры запроса:
Параметр Описание
groupinteger, обязательно VK ID группы.
tokenstring, обязательно Секретный токен.
vint, обязательно Номер версии api. Текущая версия 1.
idsarray of int Можно передать массив системных ID заявок на выплату для выборки конкрентных заявок на выплату. Если данный параметр не передан, то вернутся 20 последних заявок на выплату.
Ответ сервера:
Параметр Описание
successboolean, обязательно Успешность обработки запроса сервером.
errorinteger Если запрос выполнен с ошибкой, то будет возвращен код ошибки. См. список кодов ошибок.
msgstring Текстовое сообщение с результатом выполнения запроса.
listarray of objects Массив объектов заявок на выплату.
idinteger, обязательно ID выплаты в системе.
statusstring, обязательно Статус вывода.
created - заявка обрабаывается;
ready - заявка выполнена;
error - произошла ошибка.
processedinteger, обязательно Временная метка по unix (в миллисекундах) даты и времени обработки заявки.
systemstring, обязательно Платежная система.
bank - Банковская карта;
qiwi - Qiwi;
webmoney - WebMoney;
yandex_money - Яндекс.Деньги;
mobile - Счет мобильного телефона.
pursestring, обязательно Счет в платежной системе на который заказана выплата.
amountinteger, обязательно Сумма выплаты в рублях указанная в заявке.
userinteger, обязательно VK ID пользователя создавшего заявку.

Пример кода на PHP с использованием класса для работы с API.

$api = new Donuts(1, 'auth_token');
$result = $api -> request('payments/get');
print_r(result);
$api = new Donuts(1, 'auth_token');
$result = $api -> request('payments/get', [
	'ids' => [1, 3]
]);
print_r(result);

payments/create Создать заявку на выплату.

Параметры запроса:
Параметр Описание
groupinteger, обязательно VK ID группы.
tokenstring, обязательно Секретный токен.
vint, обязательно Номер версии api. Текущая версия 1.
systemstring, обязательно Платежная система.
bank - Банковская карта;
qiwi - Qiwi;
webmoney - WebMoney;
yandex_money - Яндекс.Деньги;
mobile - Счет мобильного телефона
pursestring, обязательно Счет в платежной системе на который будет произведена выплата.
amountinteger, обязательно Сумма выплаты в рублях.
Ответ сервера:
Параметр Описание
successboolean, обязательно Успешность обработки запроса сервером.
errorinteger Если запрос выполнен с ошибкой, то будет возвращен код ошибки. См. список кодов ошибок.
msgstring Текстовое сообщение с результатом выполнения запроса.
idinteger ID выплаты в системе.

Пример кода на PHP с использованием класса для работы с API.

$api = new Donuts(1, 'auth_token');
$result = $api -> request('payments/create', [
	'system' => 'mobile',
	'purse' => '78005553535',
	'amount' => 50
]);
print_r(result);

balance Получить баланс группы в приложении.

Параметры запроса:
Параметр Описание
groupinteger, обязательно VK ID группы.
tokenstring, обязательно Секретный токен.
vint, обязательно Номер версии api. Текущая версия 1.
Ответ сервера:
Параметр Описание
successboolean, обязательно Успешность обработки запроса сервером.
errorinteger Если запрос выполнен с ошибкой, то будет возвращен код ошибки. См. список кодов ошибок.
msgstring Текстовое сообщение с результатом выполнения запроса.
balanceinteger Баланс группы в копейках.

Пример кода на PHP с использованием класса для работы с API.

$api = new Donuts(1, 'auth_token');
$result = $api -> request('balance');
print_r(result);

Callback API

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

Ниже приведен пример кода страницы для приема уведомлений о новых донатах. Версия PHP не ниже 7.0.

class Callback {
	private $secret_key;
	
	function __construct($secret_key) {
		$this -> secret_key = $secret_key;
	}
	
	public function get() {
		$response = json_decode(file_get_contents('php://input'), true);
		if (!$this -> check_hash($response)) return false;
		unset($response['hash']);
		return $response;
	}
	private function check_hash($params) {
		$hash = $params['hash'];
		unset($params['hash']);
		$params = $this -> get_hash_array($params);
		ksort($params);
		array_push($params, $this -> secret_key);
		$hash_str = join(',', $params);
		$sha256 = hash('sha256', $hash_str);
		return ($sha256 == $hash) ? true : false;
	}
	private function get_hash_array($params, $indx = '') {
		$arr = [];
		if ($indx) $indx .= '/';
		foreach ($params as $key => $val) {
			if (is_array($val)) {
				$newarr = $this -> get_hash_array($val, $indx . $key);
				$arr = array_merge($newarr, $arr);
			}
			else {
				$arr[$indx . $key] = $val;
			}
		}
		return $arr;
	}
}

$secret_key = 'секретный_ключ_из_настроек_приложения';
$code = 'код_подтверждения_из_настроек_приложения';

$callback = new Callback($secret_key);
$response = $callback -> get();
if ($response === false) exit('Неверный хеш запроса.');

switch ($response['type']) {
	case 'confirmation':
		echo '{"code": "' . $code . '"}';
		break;
	case 'new_donate':
		// Записываем данные в response.txt
		$json = json_encode($response, JSON_UNESCAPED_UNICODE);
		file_put_contents('donates.txt', $json . "\n", FILE_APPEND);
	case 'payment_status':
		// Записываем данные в response.txt
		$json = json_encode($response, JSON_UNESCAPED_UNICODE);
		file_put_contents('payments.txt', $json . "\n", FILE_APPEND);
}

Проверка хеша запроса.

Для того, чтобы удостовериться в подлиности данных, следует проверять хеш запроса.

Для проверки хеша:

  1. Удалите из массива входящих данных элемент с ключом hash.
  2. Удалите все подмассивы добавив их элементы в основной массив. При добавлении элементов, добавьте к началу их ключей ключ родителя и слеш. То есть из изначального массива ...
    [
    	"a" => "Элемент 1",
    	"b" => [
    		"c" => "Элемент 2",
    		"d" => [
    			"e" => "Элемент 3",
    			"f" => "Элемент 4"
    		]
    	],
    	"g" => "Элемент 5"
    ]
    	
    ... должен получиться массив ...
    [
    	"a" => "Элемент 1",
    	"b/c" => "Элемент 2",
    	"b/d/e" => "Элемент 3",
    	"b/d/f" => "Элемент 4",
    	"g" => "Элемент 5"
    ]
    	
  3. Отсортируйте массив по ключу.
  4. Объедините все элементы массива через запятую сохранив порядок сортировки.
  5. В конец строки добавьте еще одну запятую и секретный ключ из настроек приложения (не путать с токеном api!).
  6. Полученную строку преобразуйте в sha256 хеш. Полученный хеш должен совпадать с присланным нашим сервером.

Данные, которые наш сервер передаст на вашу страницу.

Данные передаются в виде JSON методом POST.

Общие данные (присутствуют в запросах всех типов уведомлений):
Параметр Описание
groupinteger, обязательно VK ID группы.
typestring, обязательно Тип уведомления.
Возможные значения:
confirmation - подтверждение страницы при настройке адреса сервера в приложении;
new_donate - новый донат;
payment_status - изменение статуса заявки на выплату.
hashstring, обязательно Хеш запроса. Нужен для проверки того, что уведомление получено от нашего сервера, а не от злоумышленника. Подробнее про проверку хеша читайте в разделе Проверка хеша запроса.
Данные для уведомления типа new_donate:
donateobject Объект с информацией о донате.
idinteger, обязательно ID донаты в системе.
userinteger, обязательно VK ID пользователя совершившего донат. Если донаты отправлен анонимно, то значение данного поле будет 0.
dateinteger, обязательно Временная метка по UNIX (в миллисекундах) даты и времени доната.
amountinteger, обязательно Сумма доната в рублях.
msgstring Сообщение прикрепленное к донату.
anonymbool, обязательно Анонимность доната.
answerstring Ответ администратора группы на донат.
vkpaybool, обязательно Если донат был отправлен через VK Pay, то значение данного поля будет равно true.
statusstring, обязательно Статус доната
Возможные значения:
new - новый донат;
public - опубликован;
hidden - скрыт.
rewardarray of objects Если не было выбрано вознаграждение, то данное поле будет отсутствовать.
idinteger, обязательно ID вознаграждения в системе.
titlestring, обязательно Название вознаграждения.
statusstring, обязательно Статус выдачи вознаграждения.
Возможные значения:
not_sended - не выдано;
sended - выдано.
Данные для уведомления типа payment_status:
paymentobject Объект с информацией о заявке на выплату.
idinteger, обязательно ID выплаты в системе.
statusstring, обязательно Статус вывода.
created - заявка обрабаывается;
ready - заявка выполнена;
error - произошла ошибка.
processedinteger, обязательно Временная метка по unix (в миллисекундах) даты и времени обработки заявки.
systemstring, обязательно Платежная система.
bank - Банковская карта;
qiwi - Qiwi;
webmoney - WebMoney;
yandex_money - Яндекс.Деньги;
mobile - Счет мобильного телефона.
pursestring, обязательно Счет в платежной системе на который заказана выплата.
amountinteger, обязательно Сумма выплаты в рублях указанная в заявке.
userinteger, обязательно VK ID пользователя создавшего заявку.