Кексик для Telegram

Сервис для сбора донатов

Как работать с API?

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

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

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

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

Обязательные параметры для каждого запроса

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

Параметр Описание
accountinteger, обязательно ID аккаунта.
tokenstring, обязательно Секретный токен.
Ошибочный запрос

Если запрос был выполнен с ошибкой, то вы получите следующий ответ:

Параметр Описание
successboolean, обязательно Успешность обработки запроса сервером. Будет возвращено значение false
errorinteger, обязательно Индекс ошибки.
msgstring, обязательно Описание ошибки.
Список методов API
Общие методы
balance
Получение баланса аккаунта
Параметры запроса:
Дополнительных параметров для данного метода не предусмотрено.
Ответ сервера:
Параметр Описание
success
boolean, обязательно 		Успешность обработки запроса сервером.
balance
integer, обязательно 		Баланс аккаунта в копейках.
Работа со сборами
campaigns/get
Получение списка ваших сборов
Параметры запроса:
Параметр Описание
offset
integer 		Смещение по выборке сборов. Если не передать данный параметр, то вернется список последних 20 сборов.
Ответ сервера:
Параметр Описание
success
boolean, обязательно 		Успешность обработки запроса сервером.
list
array of objects, обязательно 		Список сборов.
id
integer, обязательно 		ID сбора в системе.
received
integer, обязательно 		Собрано на данный момент в рублях.
backers
integer, обязательно 		Количество задонативших.
goal
integer 		Цель сбора в рублях. Если цель не установлена, то данное поле не будет возвращено.
campaigns/change
Обновление информации по сбору
Параметры запроса:
Параметр Описание
id
integer, обязательно 		ID сбора в системе.
received
integer 		Собрано на данный момент в рублях.
backers
integer 		Количество задонативших.
goal
integer 		Цель сбора в рублях. Для удаления цели сбора следует передать 0 (ноль).
Ответ сервера:
Параметр Описание
success
boolean, обязательно 		Успешность обработки запроса сервером.
Работа с донатами
donates/get
Получение списка донатов

У данного метода есть лимиты. Лимит составляет 100 запросов в сутки. Для регулярной проверки новых донатов используйте метод donates/last.

Параметры запроса:
Параметр Описание
campaign
integer 		ID сбора в системе. Если не передать данный параметр, то вернутся донаты всех ваших сборов.
len
integer 		Количество донатов в списке.
Максимум 100. По умолчанию 20.
offset
integer 		Смещение по выборке донатов.
start_date
integer 		Временная метка по UNIX (в миллисекундах). Задает минимальную дату и время выбираемых донатов.
end_date
integer 		Временная метка по UNIX (в миллисекундах). Задает максимальную дату и время выбираемых донатов.
sort
string 		Метод сортировки. По умолчанию date.
Возможные значения:
date - сортировка по дате;
amount - сортировка по сумме.
reverse
boolean 		Направление сортировки. По умолчанию false.
Возможные значения:
false - сортировка по убыванию;
true - сортировка по возрастанию.
Ответ сервера:
Параметр Описание
success
boolean, обязательно 		Успешность обработки запроса сервером.
list
array of objects, обязательно 		Список донатов.
id
integer, обязательно 		ID доната в системе.
campaign
integer 		ID сбора в системе. Данное поле возвращается только если не передать параметр campaign в запросе.
user
integer 		ID пользователя совершившего донат. Если донат отправлен анонимно, то поле будет отсутствовать.
date
integer, обязательно 		Временная метка по UNIX (в миллисекундах) даты и времени доната.
amount
integer, обязательно 		Сумма доната в копейках.
total
integer, обязательно 		Сумма поступившая на баланс личного кабинета в копейках.
msg
string 		Сообщение прикрепленное к донату.
anonym
bool, обязательно 		Если донат был отправлен анонимно, то значение будет true.
answer
string 		Текст ответа администратора на донат.
answer_is_private
bool 		Если ответ администратора на донат виден только отправителю доната, то значение будет true.
status
string, обязательно 		Статус доната
Возможные значения:
new - новый донат;
public - опубликован;
hidden - скрыт;
refunded - по донату был оформлен возврат средств.
reward
array of objects 		Если не было выбрано вознаграждение, то данное поле будет отсутствовать.
id
integer, обязательно 		ID вознаграждения в системе.
title
string, обязательно 		Название вознаграждения.
opinteger Данный параметр содержит целое положительное число, которое присваивается донату, при переходе пользователя по ссылке при донате. Для использования данного параметра, добавьте к ссылке ?start=op123456789, где вместо 123456789 можно указать любое целое положительное число в интервале от 1 до 4294967295. Пример ссылки на приложение - https://t.me/keksikio_donate_bot?start=op123456789.
donates/last
Получение списка последних донатов

У данного метода есть лимиты. Если вы не передаете параметр last, то лимит составит 100 запросов в сутки. Если передавать параметр last, то допускается 1 запрос в минуту, но общее количество запросов к данному методу не ограничено. Для получения уведомлений о новых донатах советуем использовать Callback API.

Параметры запроса:
Параметр Описание
campaign
integer 		ID сбора в системе. Если не передать данный параметр, то вернутся донаты всех ваших сборов.
last
integer 		ID последнего полученного доната. Если данный параметр передан, вернется список с более новыми донатами. Если не передавать данный параметр, то вернется список последних 20 донатов. Таким образом вы можете при первом запросе не передав этот параметр получить актуальный список последних донатов, выбрать из списка самый последний донат и в следующем запросе передать ID этого доната, чтобы проверить наличие новых донатов. Если вернется пустой массив, то продолжайте передавать тот же ID. Как только в массиве вернется какое-то количество новых донатов, обновите ID последнего доната и в новом запросе передайте обновленный ID. Обратите внимание, что можно делать только 1 запрос в минуту. Для моментального оповещения о новых донатах используйте наш Callback API.
Ответ сервера:
Параметр Описание
success
boolean, обязательно 		Успешность обработки запроса сервером.
list
array of objects, обязательно 		Список донатов.
id
integer, обязательно 		ID доната в системе.
campaign
integer 		ID сбора в системе. Данное поле возвращается только если не передать параметр campaign в запросе.
user
integer, обязательно 		VK ID пользователя совершившего донат. Если донат отправлен анонимно, то значение данного поле будет 0.
date
integer, обязательно 		Временная метка по UNIX (в миллисекундах) даты и времени доната.
amount
integer, обязательно 		Сумма доната в копейках.
total
integer, обязательно 		Сумма поступившая на баланс личного кабинета в копейках.
msg
string 		Сообщение прикрепленное к донату.
anonym
bool, обязательно 		Если донат был отправлен анонимно, то значение будет true.
answer
string 		Текст ответа администратора на донат.
answer_is_private
bool 		Если ответ администратора на донат виден только отправителю доната, то значение будет true.
status
string, обязательно 		Статус доната
Возможные значения:
new - новый донат;
public - опубликован;
hidden - скрыт;
refunded - по донату был оформлен возврат средств.
reward
array of objects 		Если не было выбрано вознаграждение, то данное поле будет отсутствовать.
id
integer, обязательно 		ID вознаграждения в системе.
title
string, обязательно 		Название вознаграждения.
opinteger Данный параметр содержит целое положительное число, которое присваивается донату, при переходе пользователя по ссылке при донате. Для использования данного параметра, добавьте к ссылке ?start=op123456789, где вместо 123456789 можно указать любое целое положительное число в интервале от 1 до 4294967295. Пример ссылки на приложение - https://t.me/keksikio_donate_bot?start=op123456789.
donates/change-status
Изменение статуса видимости доната
Параметры запроса:
Параметр Описание
id
integer, обязательно 		ID доната в системе.
status
string, обязательно 		Новый статус видимости доната.
Возможные значения:
public - опубликован;
hidden - скрыт.
Ответ сервера:
Параметр Описание
success
boolean, обязательно 		Успешность обработки запроса сервером.
donates/answer
Добавление/изменение ответа сообщества на донат
Параметры запроса:
Параметр Описание
id
integer, обязательно 		ID доната в системе.
answer
string, обязательно 		Текст ответа. Для удаления ответа следует передать пустую строку.
private
boolean 		Сделать ответ видимым только для отправителя доната.
Ответ сервера:
Параметр Описание
success
boolean, обязательно 		Успешность обработки запроса сервером.
donates/send-message
Отправление сообщения отправителю доната через бота
Параметры запроса:
Параметр Описание
id
integer, обязательно 		ID доната в системе.
msg
string, обязательно 		Текст сообщения.
Ответ сервера:
Параметр Описание
success
boolean, обязательно 		Успешность обработки запроса сервером.
Работа с вознаграждениями
rewards/get
Получение списка вознаграждений сбора
Параметры запроса:
Параметр Описание
id
integer, обязательно 		ID сбора в системе.
Ответ сервера:
Параметр Описание
success
boolean, обязательно 		Успешность обработки запроса сервером.
list
array of objects, обязательно 		Список вознаграждений.
id
integer, обязательно 		ID вознаграждения в системе.
title
string, обязательно 		Название вознаграждения.
description
string 		Описание вознаграждения.
limits
integer 		Количество позиций данного вознаграждения.
min_donate
integer 		Минимальный донат для получения текущего вознаграждения.
rewards/change
Обновление информации о вознаграждении сбора
Параметры запроса:
Параметр Описание
id
integer, обязательно 		ID вознаграждения в системе.
title
string 		Название вознаграждения.
description
string 		Описание вознаграждения.
limits
integer 		Количество позиций данного вознаграждения. Для отключения лимита на количество позиций вознаграждения следует передать 0 (ноль).
min_donate
integer 		Минимальный донат для получения текущего вознаграждения. Для отключения минимального порога размера доната следует передать 0 (ноль).
Ответ сервера:
Параметр Описание
success
boolean, обязательно 		Успешность обработки запроса сервером.
Выплаты
payouts/get
Получение списка заявок на выплату
Параметры запроса:
Параметр Описание
len
integer 		Количество заявок на выплату в списке.
Максимум 100. По умолчанию 20.
offset
integer 		Смещение по выборке заявок на выплату.
Ответ сервера:
Параметр Описание
success
boolean, обязательно 		Успешность обработки запроса сервером.
list
array of objects, обязательно 		Список заявок на выплату.
id
integer, обязательно 		ID заявки на выплату в системе.
status
integer, обязательно 		Статус вывода.
processing - заявка обрабатывается;
paid - заявка выполнена;
canceled - заявка отклонена.
created
integer, обязательно 		Временная метка по unix (в миллисекундах) даты и времени создания заявки.
processed
integer 		Временная метка по unix (в миллисекундах) даты и времени обработки заявки. Не будет возвращено в случае если заявка на выплату находится в статусе processing.
system
string, обязательно 		Платежная система.
sbp - СБП;
card-rub - банковская карта (российская);
yoomoney - ЮMoney;
mobile - счет мобильного телефона.
purse
string, обязательно 		Номер счета в платежной системе, на который заказана выплата.
bank
string 		Индитификатор банка, в который была заказана выплата. Данный параметр возвращается только для СБП выплат.
amount
integer, обязательно 		Сумма выплаты в копейках указанная в заявке.
api
boolean, обязательно 		Если выплата была заказна через API, то вернется true.
payouts/status
Информация по конкретной заявке на выплату
Параметры запроса:
Параметр Описание
id
integer, обязательно 		ID заявки на выплату в системе.
Ответ сервера:
Параметр Описание
success
boolean, обязательно 		Успешность обработки запроса сервером.
status
integer, обязательно 		Статус вывода.
processing - заявка обрабатывается;
paid - заявка выполнена;
canceled - заявка отклонена.
created
integer, обязательно 		Временная метка по unix (в миллисекундах) даты и времени создания заявки.
processed
integer 		Временная метка по unix (в миллисекундах) даты и времени обработки заявки. Не будет возвращено в случае если заявка на выплату находится в статусе processing.
system
string, обязательно 		Платежная система.
sbp - СБП;
card-rub - банковская карта (российская);
yoomoney - ЮMoney;
mobile - счет мобильного телефона.
purse
string, обязательно 		Номер счета в платежной системе, на который заказана выплата.
bank
string 		Индитификатор банка, в который была заказана выплата. Данный параметр возвращается только для СБП выплат.
amount
integer, обязательно 		Сумма выплаты в копейках указанная в заявке.
api
boolean, обязательно 		Если выплата была заказна через API, то вернется true.
payouts/create
Создание заявки на выплату
Параметры запроса:
Параметр Описание
system
string, обязательно 		Платежная система.
sbp - СБП;
card-rub - банковская карта (российская), в первый раз карточку необходимо привязать;
yoomoney - ЮMoney;
mobile - счет мобильного телефона.
purse
string, обязательно 		Номер счета в платежной системе, на который заказана выплата.
bank
string 		Идентификатор банка, в который нужно произвести выплату. Данный параметр передается и обязателен только для СБП выплат. Список идентификаторов банков можно получить с помощью API метода payouts/sbp-banks.
amount
integer, обязательно 		Сумма выплаты в копейках указанная в заявке.
Ответ сервера:
Параметр Описание
success
boolean, обязательно 		Успешность обработки запроса сервером.
id
integer, обязательно 		ID заявки на выплату в системе.
Ответ сервера (в случае, если банковская карточка ранее не была привязана):
Параметр Описание
success
boolean, обязательно 		Успешность обработки запроса сервером.
link_bank_card
string, обязательно 		Ссылка для оплаты счета, чтобы мы смогли привязать карточку. После оплаты счета средства вернутся обратно на карточку.
payouts/check-bank-card
Проверка статуса привязки карточки
Параметры запроса:
Параметр Описание
card_number
string, обязательно 		Номер карточки.
Ответ сервера:
Параметр Описание
success
boolean, обязательно 		Успешность обработки запроса сервером.
status
string, обязательно 		Статус привязки карточки.
not_linked - карточка не была привязана ранее;
linked - карточка успешно привязана;
wrong_card - счет для привязки был оплачен с другой карточки.
payouts/sbp-banks
Получение списка банков доступных для выплаты через СБП
Параметры запроса:
Дополнительных параметров для данного метода не предусмотрено.
Ответ сервера:
Параметр Описание
success
boolean, обязательно 		Успешность обработки запроса сервером.
list
array of objects, обязательно 		Список банков.
id
integer, обязательно 		ID банка.
title
string, обязательно 		Название банка.
Callback API

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

Обратите внимание! На любое уведомление, ваш сервер должен ответить в JSON формате:

{"status": "ok"}

Если не ответить подобным образом, то наш сервер будет считать, что уведомление не доставлено и повторит отправку уведомления еще раз через какое-то время.

На уведомления типа confirmation ваш сервер должен ответить:

{"status": "ok", "code": "a1b2c3"}

Код подтверждения можно найти в личном кабинете.

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

Для того, чтобы проверить входящее сообщение, нужно получить хеш сообщения и сравнить его с хешом переданным нашим сервером в заголовке X-Signature. Для получения хеша воспользуйтесь алгоритмом HMAC-SHA256. В него необходимо передать тело сообщения без изменений (до того как оно будет расшифровано из JSON объекта) и секретный ключ, который можно получить в личном каибенете во вкладке API.

Пример получения хеша для PHP:

$data = file_get_contents("php://input");
hash_hmac("sha256", $data, $secretKey);
Обязательные данные для каждого запроса
Содержание уведомления:
Параметр Описание
account
integer, обязательно 		ID аккаунта.
type
string, обязательно 		Тип события.
Возможные значения:
confirmation - подтверждение адреса вашего сервера;
new_donate - новый донат;
payment_status - изменение статуса заявки на выплату.
hash
string, обязательно 		Хеш запроса. Нужен для проверки того, что уведомление получено от нашего сервера, а не от злоумышленника. Подробнее про проверку хеша читайте в разделе Проверка хеша запроса.
События Callback API
confirmation
Событие подтверждения адреса вашего сервера
Содержание уведомления:
Дополнительные данные для данного события не передаются.
new_donate
Событие нового доната
Содержание уведомления:
Параметр Описание
data
array of objects, обязательно 		Объект с информацией о донате.
id
integer, обязательно 		ID доната в системе.
campaign
integer, обязательно 		ID сбора в системе. Если не передать данный параметр, то вернутся донаты всех ваших сборов.
user
integer, обязательно 		ID пользователя совершившего донат. Если донат отправлен анонимно, то значение данного поле будет 0.
date
integer, обязательно 		Временная метка по UNIX (в миллисекундах) даты и времени доната.
amount
integer, обязательно 		Сумма доната в копейках.
total
integer, обязательно 		Сумма поступившая на баланс личного кабинета в копейках.
msg
string 		Сообщение прикрепленное к донату.
anonym
bool, обязательно 		Если донат был отправлен анонимно, то значение будет true.
reward
array of objects 		Если не было выбрано вознаграждение, то данное поле будет отсутствовать.
id
integer, обязательно 		ID вознаграждения в системе.
title
string, обязательно 		Название вознаграждения.
opinteger Данный параметр содержит целое положительное число, которое присваивается донату, при переходе пользователя по ссылке при донате. Для использования данного параметра, добавьте к ссылке ?start=op123456789, где вместо 123456789 можно указать любое целое положительное число в интервале от 1 до 4294967295. Пример ссылки на приложение - https://t.me/keksikio_donate_bot?start=op123456789.
payout
Событие изменения статуса заявки на выплату
Содержание уведомления:
Параметр Описание
data
array of objects, обязательно 		Объект с информацией о заявке на выплату.
status
integer, обязательно 		Статус вывода.
paid - заявка выполнена;
canceled - заявка отклонена.
created
integer, обязательно 		Временная метка по unix (в миллисекундах) даты и времени создания заявки.
processed
integer, обязательно 		Временная метка по unix (в миллисекундах) даты и времени обработки заявки.
system
string, обязательно 		Платежная система.
sbp - СБП;
card-rub - банковская карта (российская);
yoomoney - ЮMoney;
mobile - счет мобильного телефона;
usdt-trc20 - USDT (TRC20).
purse
string, обязательно 		Номер счета в платежной системе, на который заказана выплата.
bank
string 		Индитификатор банка, в который была заказана выплата. Данный параметр возвращается только для СБП выплат.
amount
integer, обязательно 		Сумма выплаты в копейках указанная в заявке.
api
boolean, обязательно 		Если выплата была заказна через API, то вернется true.
member
Событие добавления или окончания подписки пользователя
Содержание уведомления:
Параметр Описание
data
array of objects, обязательно 		Объект с информацией о подписке.
channel
integer, обязательно 		ID канала в Telegram.
campaign
integer, обязательно 		ID сбора.
user
integer, обязательно 		ID пользователя.
action
string, обязательно 		Тип действия. Возможные варианты:
added - пользователь добавлен в подписку;
ended - подписка пользователя закончилась;
removed - подписка пользователя была принудительно аннулирована.
added_at
integer, обязательно 		Время начала подписки.
remove_at
integer 		Время окончания подписки. Если к каналу предоставлен безлимитный по времени доступ, то данное поле не будет возвращено.