Документация Sponsr API
Максимальное количество запросов в минуту — 200
Валидация API ключа
Проверка полученного X-API-KEY на валидность
GET sponsr.ru/api/v2/external-api/api-keys/validate
Headers:
accept: application/json X-API-KEY
Ответ в случае успеха
{
"valid": true,
"expires_at": "2024-11-10T15:30:11.000Z"
}
Ответ в случае неверного ключа:
{
"message": "Unauthorized",
"statusCode": 401
}
Ответ в случае устаревшего ключа:
{
"message": "Api key expired",
"error": "Forbidden",
"statusCode": 403
}
Описание ответа:
- message — текст ошибки;
- statusCode — код ошибки.
Генерация {uuid} для платежной ссылки
Создание {uuid} по заданным параметрам в теле запроса
POST sponsr.ru/api/v2/external-api/donate-urls
Headers:
accept: application/json X-API-KEY Content-Type: application/json
Тело запроса:
{
"type": "subscribe",
"level_id": 123,
"period": "monthly"
}
Параметры запроса:
- type — тип оплаты (one_time_payment, subscribe);
- level_id — идентификатор уровня, необходимый для подписки. Обязателен, если type = subscribe;
- period — период подписки (monthly, annual). Обязателен, если type = subscribe;
- redirect_url — URL для перенаправления после успешного завершения платежа (планируется в будущем);
- web_hook_url —URL для получения уведомлений о статусе платежа (планируется в будущем).
Пример ответа в случае успеха:
{
"data": {
"donateUrl": "sponsr.ru/api/v2/external-api/payment/e41aeeb2-9a44-4c06-8b82-8ed2f9c1eeef"
}
}
uuid из примера: e41aeeb2-9a44-4c06-8b82-8ed2f9c1eeef
Примеры ответов в случае неудачи:
{
"message": [
"level_id must be a number conforming to the specified constraints"
],
"error": "Bad Request",
"statusCode": 400
}
{
"message": [
"period should not be empty",
"period must be one of the following values: monthly, annual"
],
"error": "Bad Request",
"statusCode": 400
}
{
"message": [
"redirect_url must be a URL address",
"web_hook_url must be a URL address"
],
"error": "Bad Request",
"statusCode": 400
}
Описание ответа:
- message — текст ошибки;
- statusCode — код ошибки;
- error — тип ошибки.
Получение платежной ссылки пользователя
Полученная ссылка используется пользователями для перехода на форму оплаты. Чтобы оплатить пользователю необходимо быть авторизованным на Sponsr
Копируем {uuid} из POST запроса и вставляем в конец запроса
GET sponsr.ru/api/v2/external-api/payment{uuid}?payer_id=123
Headers:
accept: */*
При переходе по URL оплаты ({URL сервиса} + payment/{uuid}) автор может передать GET-параметр payer_id — обозначив какой-либо уникальный идентификатор пользователя перенаправляемого на оплату. После успешного платежа передаваемый параметр payer_id будет отображен для соответствующего юзера в ответе запроса GET subscribers.
В будущем планируется отправление параметра payer_id на web_hook_url вместе с результатом платежа.
Получение списка уровней подписки
Вы можете получить список уровней вашего проекта
GET sponsr.ru/api/v2/external-api/projects/levels
Headers:
accept: application/json X-API-KEY
Query параметры в ссылке:
- offset — пагинационный отступ (вы можете сделать через этот параметр постраничное получение данных, offset = 0 будет означать page = 1);
- limit — лимит записей в ответе;
- orderByType — направление сортировки (asc, desc);
- orderBy — поле сортировки.
Пример запроса:
sponsr.ru/api/v2/external-api/projects/levels?offset=0&limit=1&orderByType=desc&orderBy=level_price
Пример ответа:
{
"total": 12,
"list": [
{
"id": 4369,
"project_id": 1877,
"level_name": "Платина",
"level_description": "Укажите здесь, что получат подписчики уровня. Что входит в стоимость, как часто публикуется контент, какие дополнительные преимущества у подписчиков этого уровня..",
"level_price": "5000",
"level_subscribers": 0,
"level_limit": null,
"level_status": "deleted",
"level_visible": "visible",
"level_can_comment": 0,
"level_comment_disable": 0,
"ts": "2022-11-30T16:08:00.000Z",
"can_comment": false
}
],
"page": 1,
"limit": 1
}
Получение списка подписчиков
Вы можете получить подписчиков вашего проекта и их данные
GET sponsr.ru/api/v2/external-api/projects/subscribers
Headers:
accept: application/json X-API-KEY
Query параметры в ссылке:
- offset — пагинационный отступ (вы можете сделать через этот параметр постраничное получение данных, offset = 0 будет означать page = 1);
- limit — лимит записей в ответе;
- orderByType — направление сортировки (asc, desc);
- orderBy — поле сортировки;
- total_paid — оборот для каждого пользователя (true, false);
- withProviders — подключенные соцсети пользователя (true, false);
- level_id — ID уровня подписки;
- provider — фильтр по подключённому oauth-провайдеру. Указывается строго один провайдер(ok, vk, google, telegram, yandex, mailru, steam);
- provider_mode — фильтр по провайдеру (include — у пользователя провайдер подключён, exclude — не подключён). Работает только вместе с provider.
Пример запроса:
Пример ответа:
{
"total": 2,
"list": [
{
"id": 168063,
"name": "Testuser123",
"avatar": "/images/avatars/63/168063/avatar.webp",
"email": null,
"telegram_id": "123456",
"subscription_expired": "2025-06-24T10:00:34.000Z",
"last_payment": "2025-05-24T10:00:34.000Z",
"level": {
"id": 16363,
"name": "TestTest",
"level_price": "244"
},
"metadata": {
"payer_id":"123"
}
"withProviders": [
{
"provider": "vk",
"provider_id": "123123"
}
]
},
{
"id": 148169,
"name": "TEST123",
"avatar": "/images/avatars/169/148169/avatar.webp",
"email": null,
"telegram_id": null,
"subscription_expired": "2025-06-24T10:00:34.000Z",
"last_payment": "2025-05-24T10:00:34.000Z",
"level": {
"id": 16363,
"name": "133"
}
}
],
"page": 1,
"limit": 2
}
Отправка личного сообщения подписчику
Вы можете отправить личное сообщение конкретному подписчику
POST sponsr.ru/api/v2/external-api/projects/subscribers/message
Headers:
accept: application/json Content-Type: application/json X-API-KEY
Тело запроса:
{
"user_id": 0,
"content": "string"
}
Параметры запроса:
- user_id — ID получателя. Обязательный параметр. Получатель должен быть активным подписчиком вашего проекта;
- content — текст сообщения. Обязателен, до 5000 символов.
Пример ответа в случае успеха:
{
"success": true
}
Примеры ответов в случае неудачи:
{ "message": "User is not an active subscriber of the project",
"statusCode": 403 }
{ "message": "content should not be empty",
"error": "Bad Request",
"statusCode": 400 }
{ "message": "Unauthorized",
"statusCode": 401 }
Публикация поста
Вы можете создать и опубликовать пост в проекте
POST sponsr.ru/api/v2/external-api/post
Headers:
accept: application/json X-API-KEY
Тело запроса:
{
"level_id": 0,
"date": "2026-06-17",
"title": "string",
"text": "string",
"is_extended_view": true,
"is_pinned": false,
"is_markdown": false,
"is_notified": true,
"access_type": "all",
"access_value": 4294967295,
"tag_id": [1,2],
"meta_title": "string",
"meta_description": "string"
}
Параметры запроса:
- level_id — ID уровня подписки;
- date — дата публикации в формате ISO 8601;
- title — заголовок поста. От 4 до 256 символов;
- text — содержимое поста;
- is_extended_view — показывать пост в развернутом виде (true / false);
- is_pinned — закрепить пост (true / false);
- is_markdown — применить markdown к тексту (true / false);
- is_notified — не оповещать о публикации поста (true / false)
- access_type — тип доступа к посту (all , active , continuity);
- access_value — дополнительный параметр для access_type при значении active , continuity ;
- tag_id — ID существующей подборки, в которую нужно добавить пост (можно передавать несколько tag_id);
- meta_title — SEO-заголовок страницы;
- meta_description — SEO-описание страницы.
Пример ответа в случае успеха:
{
"data": {
"id": 222,
"url": "sponsr.ru/spnsrtst/51753/Proverka",
"editor": "sponsr.ru/spnsrtst/manage/post/51753"
}
}
Описание ответа:
- id — ID созданного поста;
- url — публичная ссылка на пост;
- editor — ссылка на редактирование поста через UI.
