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

Получение платежной ссылки пользователя

Полученная ссылка используется пользователями для перехода на форму оплаты

Копируем {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)
• level_id (ID уровня подписки);

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

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

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

{
   "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"
         },
         "metadata": {
         "payer_id":"123"
         }
     },
      {
        "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
}