Документация 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.

Пример запроса:

sponsr.ru/api/v2/external-api/projects/subscribers?offset=0&limit=2&orderByType=desc&orderBy=id&level_id=16363&withProviders=true

Пример ответа:

{
  "total": 2,
  "list": [
    {
      "id": 168063,
      "name": "Testuser123",
      "avatar": "/images/avatars/63/168063/avatar.webp",
      "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",
      "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/post

Headers:

accept: application/json 
X-API-KEY

Пример тела запроса:

{
 "date": "2026-10-23",
 "title": "Демо-пост публикации через API",
 "text": "<h1>Демо-пост через API</h1>\n<p>Пример публикации через <b>внешний API</b>. Доступны <b>жирный</b>, <i>курсив</i>, <u>подчёркнутый</u>, <s>зачёркнутый</s> и <a href='LINK_URL'>ссылка</a>.</p>\n<h2>Списки</h2>\n<ul><li>Маркированный пункт</li><li>Ещё один пункт</li></ul>\n<ol><li>Нумерованный пункт</li><li>Второй пункт</li></ol>\n<h2>Фото</h2>\n<img src='IMAGE_URL' alt='Описание изображения' width='480'>\n<h2>Видео</h2>\n<iframe width='720' height='405' src='VIDEO_URL' style='border: none;' allowfullscreen></iframe>\n<h2>Цитата и код</h2>\n<blockquote>Цитата автора поста.</blockquote>\n<pre><code>console.log('Привет');</code></pre>\n<hr>\n<p><b>Проверьте: заголовки, списки, фото, видео, цитата и код отображаются корректно.</b></p>",
 "is_extended_view": true,
 "is_pinned": true,
 "is_markdown": false,
 "is_notified": false,
 "tag_id": [91419, 91420],
 "meta_title": "Демо-пост публикации через API",
 "meta_description": "SEO-описание страницы"
}

Перед отправкой запроса замените плейсхолдеры на свои ссылки:

  • «LINK_URL» — ссылка на внешний ресурс, например:
sponsr.ru
  • «IMAGE_URL» — прямая ссылка на изображение, например : 
media.sponsr.ru/project/1/post/93635/image/314322/imagesprojects11uunjcj38f6i785e6_original.webp?1760442786744
  • «VIDEO_URL» — ссылка на встраиваемое видео, например :
rutube.ru/play/embed/137be5b90abe7af601e12c92119c3ba2

Пример опубликованного поста:

sponsr.ru/projecttest/189902/Demopost_publikacii_cherez_API

Параметры тела запроса:

  • level_id — ID уровня подписки. Если параметр не передан, пост будет опубликован как бесплатный и доступный всем пользователям. При передаче level_id доступ к посту получают только пользователи указанного уровня;
  • date — дата публикации в формате ISO 8601;
  • title — заголовок поста. От 4 до 256 символов;
  • text — содержимое поста. От 0 до 150 000 символов;
  • is_extended_view — показывать пост в развернутом виде (true / false);
  • is_pinned — закрепить пост (true / false);
  • is_markdown — применить markdown к тексту (true / false);
  • is_notified — не оповещать о публикации поста (true / false)
  • tag_id — ID существующей подборки, в которую нужно добавить пост (можно передавать несколько tag_id массивом);
  • meta_title — SEO-заголовок страницы. От 1 до 1000 символов;
  • meta_description — SEO-описание страницы. От 1 до 1000 символов.


Контент в содержимом поста

Поле «text» позволяет передавать не только текстовые данные, но и медиа-элементы в составе HTML или Markdown.

Изображения вставляются по прямой ссылке на файл изображения, размещенного на платформе Sponsr или на стороннем хостинге. 

"text" : "<img src=\"example.com/image.webp\" alt=\"Описание изображения\">"

Видео встраивается через iframe с поддерживаемых сервисов, загружать его не требуется. Список поддерживаемых сервисов : Кинескоп, VK, RuTube, YouTube, Дзен.

"text": "<iframe src=\"rutube.ru/play/embed/123456\" allowfullscreen></iframe>"


Ограничения при публикации поста через API

  • прикрепление аудиофайлов, опросов к посту не поддерживается;
  • создание галереи изображений не поддерживается. Ссылки на изображения, переданные в поле «text» , выводятся последовательно друг за другом как отдельные элементы.
  • тизерную картинку и текст тизера пока что не получится передать через API. Однако, действует правило — в тизерную картинку вставляется первое фото/видео из поста.
  • прикрепленные файлы не создаются как отдельные вложения поста. Файл можно добавить только в виде ссылки на предварительно загруженный файл в поле «text» . В посте такой файл отображается как ссылка.


Пример ответа в случае успеха:

{
"data": {
        "id": 189250,
        "url": "sponsr.ru/projecttest/189250/Demopost_publikacii_cherez_API",
        "editor": "sponsr.ru/projecttest/manage/post/189250"
    }

Описание ответа:

  • id— ID созданного поста;
  • url— публичная ссылка на пост;
  • editor— ссылка на редактирование поста через UI.


Примеры ответов в случае ошибки:

Указанный уровень подписки не найден:

{ 
     "message" : "Level Not Found" ,
     "error" : "Not Found" , 
     "statusCode" : 404
 }

Слишком короткий заголовок

{ 
    "message" : [ 
    "title must be longer than or equal to 4 characters"
     ] , 
    "error" : "Bad Request" ,
    "statusCode" : 400 
}

Слишком длинный заголовок

{ 
    "message" : [
     "title must be shorter than or equal to 256 characters"
     ] , 
    "error" : "Bad Request" , 
    "statusCode" : 400
 }

Невалидное значение или отсутствие поля title или text

{ 
    "message" : [
     "title must be shorter than or equal to 256 characters" , 
     "title must be longer than or equal to 4 characters" , 
     "title must be a string" ,
     "text must be shorter than or equal to 16777200 characters" ,
     "text must be longer than or equal to 0 characters" , 
     "text must be a string" 
     ] , 
    "error" : "Bad Request" ,
    "statusCode" : 400
 }

Неверный формат даты

{ 
    "message" : [ 
    "Дата публикации должна быть корректной датой в формате ISO 8601" 
    ] , 
    "error" : "Bad Request" , 
    "statusCode" : 400 
}

Превышена длина поля meta_title

{ 
    "message" : [
     "meta_title must be shorter than or equal to 1000 characters" 
    ] ,
     "error" : "Bad Request" ,
     "statusCode" : 400 
}

Превышена длина поля meta_description

{ 
    "message" : [
     "meta_description must be shorter than or equal to 1000 characters" 
    ] , 
    "error" : "Bad Request" ,
    "statusCode" : 400 
}


Отправка личного сообщения подписчику

Вы можете отправить личное сообщение конкретному подписчику вашего проекта

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 
}
0
Бесплатный
Для авторов27
Sponsr API
Тему выбирает пользователь
Все посты проекта
Комментарии
avatar
Здесь будут комментарии к публикации