ALLSWIPES API
Один сервер отвечает всем трём сторонам продукта и сам же рисует публичные страницы.
Три аудитории токена, а не роли в одном. Токен покупателя (app), токен кабинета (console) и токен платформы (admin) не взаимозаменяемы: токен партнёра не откроет админку даже при ошибке в проверке роли. Токен передаётся заголовком Authorization: Bearer <token>.
Отказ — это ответ. Коды 409 и 428 не означают поломку: 409 — правило («код уже использован», «приём закрыт»), 428 — незаконченный шаг («нужно согласие», «выбери цифру»). При 428 код не тратится, и запрос можно повторить, добавив недостающее.
Деньги, коды, баллы и призы считает только сервер, операции идемпотентны, и каждое решение попадает в аудит-журнал.
Все даты — ISO 8601 в UTC. Денежные суммы — целые, в минорных единицах валюты; доли — в базисных пунктах.
Язык. Параметр lang (ru, en) или заголовок Accept-Language. Переводы подставляет сервер: ту же акцию показывает и приложение, и серверная страница, и письмо, а три места подстановки — это три разных текста у одной акции. Непереведённое поле отдаётся на базовом русском.
Как этим пользоваться
Спецификация машиночитаема: /openapi.json импортируется в Postman, Insomnia, Swagger Editor или в генератор клиентов — описание API одно и то же и здесь, и там.
curl -s https://allswipes.com/api/v1/feed | jq '.active[0].campaign.name'
TOKEN=$(curl -s -X POST https://allswipes.com/api/v1/console/login \
-H 'content-type: application/json' \
-d '{"email":"owner@oila.tj","password":"..."}' | jq -r .token)
curl -s https://allswipes.com/api/v1/console/campaigns \
-H "authorization: Bearer $TOKEN" | jq '.campaigns | length'
Токен живёт в заголовке Authorization: Bearer <token>. Аудитория внутри токена
решает, какие ручки он открывает: app — приложение покупателя, console —
кабинет партнёра, admin — платформа. Перепутать их нельзя: токен кабинета не откроет
админку даже при ошибке в проверке роли.
Служебное
Проба живости и каталог механик.
GET /api/v1/catalog Каталог механик
Пятнадцать рецептов: десять готовых и пять со статусом «скоро». Признак implemented решает, примет ли сервер запуск такой акции, — каталог не обещает того, чего платформа не умеет.
Ответы
GET /api/v1/health Жив ли сервер
Отвечает без обращения к базе: это проба для балансировщика, а не проверка готовности.
Ответы
POST /api/v1/hit Маячок посещения
Приложения рисуются в браузере, и сервер их переходов не видит — экран отмечается этим запросом. Принимаются только вид экрана и путь без параметров: в параметрах лежат поиск и фильтры, а это уже не посещаемость. Ни адрес, ни заголовок браузера, ни cookie не хранятся: в базу попадает суточный отпечаток посетителя, по которому нельзя узнать, кто это, и нельзя связать два дня.
Тело запроса
Ответы
Публичное
Лента, акции, бренды, отчёты о розыгрышах. Токен не нужен — именно поэтому результат может пересчитать кто угодно.
GET /api/v1/archive токен Архив проведённых акций
Завершённые акции по годам, с числом участников и призов. Лента показывает то, что идёт сейчас, а история платформы — это её главное доказательство: «вот столько акций проведено, у каждой опубликован сид и список билетов, пересчитайте». Демонстрационные акции показываются наравне с настоящими, как и в ленте, но в поиск не попадают: карта сайта их пропускает. Разбивка по странам считается так, будто выбрана только дата: иначе, выбрав страну, человек видит нули у всех остальных и решает, что акций там не было. Неразборчивая дата — не ошибка, а отсутствие фильтра: архив должен открыться и по кривой ссылке. Без входа показываются первые десять акций, а limited отмечает, что список обрезан: итоги при этом считаются по всему архиву — прятать само число было бы нечестно. Страница каждой акции остаётся открытой всем: доказательство розыгрыша прятать нельзя, им человек подтверждает своё участие.
Параметры
| region | query | Код страны. |
| from | query | Начало промежутка по дате окончания акции (ГГГГ-ММ-ДД). |
| to | query | Конец промежутка, включительно. |
Ответы
GET /api/v1/brands Бренды витрины
Бренды, у которых есть хотя бы одна опубликованная акция. Заблокированные платформой сюда не попадают.
Параметры
| lang | query | Язык ответа. Сильнее заголовка Accept-Language: переключатель в интерфейсе должен работать независимо от настроек системы. (ru · en) |
Ответы
GET /api/v1/brands/{slug} Страница бренда
Бренд, его акции, рейтинг и отзывы о выданных призах. Скрытые модератором отзывы не приходят и не считаются в рейтинге.
Параметры
| slug | path · обязателен | |
| lang | query | Язык ответа. Сильнее заголовка Accept-Language: переключатель в интерфейсе должен работать независимо от настроек системы. (ru · en) |
Ответы
GET /api/v1/broadcast Эфиры: расписание розыгрышей
Розыгрыши платформы одной лентой: что идёт сейчас, что будет и что уже состоялось — с сидом и победителями. Пока у каждой акции свой отсчёт на своей странице, не видно главного: розыгрыши идут всё время, и у каждого есть результат, который можно пересчитать. Токен не нужен — на эфир смотрят со стороны, не заводя аккаунт.
Параметры
| region | query | Код страны: сужает расписание так же, как ленту. |
| limit | query | Сколько прошедших и будущих показывать. |
| lang | query | Язык ответа. Сильнее заголовка Accept-Language: переключатель в интерфейсе должен работать независимо от настроек системы. (ru · en) |
Ответы
GET /api/v1/campaigns/{id} Страница акции
Всё, что показывает экран акции: условия, призы, шанс билета, участники, результат розыгрыша. С токеном добавляются свои билеты и отметка напоминания.
Параметры
| id | path · обязателен | Идентификатор акции |
| lang | query | Язык ответа. Сильнее заголовка Accept-Language: переключатель в интерфейсе должен работать независимо от настроек системы. (ru · en) |
| k | query | Ключ канала: открывает содержимое скрытой карточки. |
Ответы
GET /api/v1/campaigns/{id}/deal Обмен «данные за ценность»
Что бренд просит, что даёт взамен и получена ли уже награда. Человек видит значения полей, а не их названия: «ты передаёшь имя» и «ты передаёшь Шах» — разные вещи.
Параметры
| id | path · обязателен |
Ответы
GET /api/v1/campaigns/{id}/draw Отчёт о розыгрыше
Сид, корень Меркла, множитель от выбранных цифр, победители и запасные — всё, что нужно для пересчёта. Отдаётся всем, без токена.
Параметры
| id | path · обязателен | Идентификатор акции |
Ответы
GET /api/v1/campaigns/{id}/participants Список участников
Публичный список билетов: номер, выбранная цифра, страна, пол, день участия и день регистрации аккаунта. Ни почты, ни имени здесь нет и не будет — список существует, чтобы розыгрыш можно было пересчитать, а не чтобы разглядывать людей.
Параметры
| id | path · обязателен | Идентификатор акции |
| limit | query | Сколько строк вернуть. |
Ответы
GET /api/v1/campaigns/{id}/quest Цепочка шагов
Шаги квеста и отметка о пройденных. Шаг — это уже существующее действие платформы: скан кода, квиз или отметка дня; новых способов участия цепочка не изобретает, она их выстраивает в порядок. Пропустить шаг нельзя — иначе это список, а не цепочка.
Параметры
| id | path · обязателен |
Ответы
GET /api/v1/campaigns/{id}/quiz Вопросы квиза
Вопросы без правильных ответов. Правильные знает только сервер — иначе квиз проходится из консоли браузера.
Параметры
| id | path · обязателен | Идентификатор акции |
Ответы
GET /api/v1/campaigns/{id}/recheck Пересчёт на сервере
Сервер пересчитывает свой же розыгрыш и отвечает, сошлось ли. Нужен для сверки с браузерным верификатором: если два независимых пересчёта расходятся, это видно сразу.
Параметры
| id | path · обязателен | Идентификатор акции |
Ответы
GET /api/v1/campaigns/{id}/streak Состояние серии
Сколько дней отмечено, что даёт следующий день и отмечен ли сегодняшний.
Параметры
| id | path · обязателен | Идентификатор акции |
Ответы
GET /api/v1/campaigns/{id}/verify Входные данные для верификатора
То же, что в отчёте, но в форме, которую браузерный верификатор скармливает движку честности. Пересчёт происходит у человека на устройстве — сервер здесь только отдаёт данные.
Параметры
| id | path · обязателен | Идентификатор акции |
Ответы
GET /api/v1/contests Конкурсы
Идущие и завершённые конкурсы. Черновики не видны: пока конкурс не открыт, обещать нечего.
Параметры
| region | query | |
| lang | query | (ru · en) |
Ответы
GET /api/v1/contests/{id} Экран конкурса
Условия, работы и голосование. Во время голосования работы перемешаны по идентификатору: список по дате давал бы фору тем, кто прислал раньше, а по голосам — тем, кто уже впереди. Счётчики скрыты до итогов, если конкурс так настроен. С токеном видно свою работу и сколько голосов осталось.
Параметры
| id | path · обязателен | Идентификатор или адрес конкурса. |
Ответы
GET /api/v1/feed Лента акций
Главный экран приложения. Токен необязателен: без него приходит та же лента, но без «моих участий», баллов и напоминаний. Разрезы по сферам, странам и механикам считаются так, будто выбран только этот разрез, — иначе, выбрав сферу, человек видит нули у всех остальных.
Параметры
| region | query | Код страны: TJ, UZ, KZ, KG, TM, AZ, GE, AM, TR, MN. |
| sphere | query | Ключ сферы из разрезов ленты. |
| recipe | query | Механика. |
| sort | query | Порядок. ( · ending · new · popular) |
| q | query | Поиск по названию акции и бренда. |
| lang | query | Язык ответа. Сильнее заголовка Accept-Language: переключатель в интерфейсе должен работать независимо от настроек системы. (ru · en) |
Ответы
GET /api/v1/links/{key} Условие по ссылке канала
Канал — ссылка с условием, которого нет на обычной странице акции: бренд вешает баннер или платит блогеру и хочет, чтобы пришедший оттуда получил надбавку. Обычно это делают промокодом, который через час лежит на форуме скидок; здесь у обещания две честные границы — срок и число мест, и обе видны сразу. Канал не меняет механику, призы и правила акции: он добавляет объявленную надбавку сверху и ничего не отнимает у пришедших обычным путём. Открыто без входа: человек приходит прямо с баннера. Переход считается этим же запросом — счётчик канала и есть ответ на вопрос «какой баннер сработал». У канала может быть личное окно: таймер начинается с первого перехода вошедшего человека и возвращается полем expires_at. Гостю окно не стартует — таймер принадлежит человеку, а не браузеру.
Параметры
| key | path · обязателен |
Ответы
POST /api/v1/subscribe Подписаться на новости и акции
Подписка живёт отдельно от аккаунта: подписаться можно, не заводя его, а участие в акции само по себе согласием на рассылку не является — это разные обещания. Повторная подписка тем же адресом не ошибка: она обновляет запись и снимает прошлую отписку. Частота запросов ограничена так же, как у входа: иначе форму перебирают чужими адресами. В журнал уходит факт подписки без адреса.
Тело запроса
Ответы
Вход покупателя
Код на почту. Ответ одинаков для знакомого и незнакомого адреса.
POST /api/v1/auth/otp/request Запросить код входа
Код уходит на почту. Ответ одинаков и для знакомого, и для незнакомого адреса — различие в ответе и есть то, чем перебирают чужие аккаунты. Код хранится только в виде HMAC.
Тело запроса
Ответы
POST /api/v1/auth/otp/verify Подтвердить код
Возвращает токен приложения. Аккаунт создаётся при первом входе.
Тело запроса
Ответы
Приложение покупателя
Токен `app`. Участие, призы, баллы, анкета и согласия.
POST /api/v1/claims/{id}/claim токен Оформить приз
Переводит приз в «оформляется». Повторный вызов ничего не ломает — операция идемпотентна.
Параметры
| id | path · обязателен | Идентификатор приза |
Ответы
POST /api/v1/claims/{id}/received токен Подтвердить получение
Только после того, как партнёр отметил приз готовым. Без этого шага отзыв невозможен — оценку ставит тот, кому действительно что-то выдали.
Параметры
| id | path · обязателен | Идентификатор приза |
Ответы
POST /api/v1/claims/{id}/review токен Оценить выдачу
Оценка и отзыв о полученном призе. Один раз на приз: вторая попытка отклоняется.
Параметры
| id | path · обязателен | Идентификатор приза |
Тело запроса
Ответы
GET /api/v1/me токен Профиль
Аккаунт, баллы, ранг, счётчики участий и выигрышей.
Ответы
POST /api/v1/me/campaigns/{id}/checkin токен Отметить день
Один раз в сутки. Пропуск не наказывается, если так настроена акция. Если передан ключ канала, надбавка начисляется так же, как при скане кода.
Параметры
| id | path · обязателен | Идентификатор акции |
Тело запроса
Ответы
GET /api/v1/me/campaigns/{id}/consent токен Что запрашивает акция
Список полей, которые бренд просит, и их значения — человек видит, что именно передаёт, до передачи.
Параметры
| id | path · обязателен | Идентификатор акции |
Ответы
POST /api/v1/me/campaigns/{id}/consent токен Согласиться передать данные
Без согласия участие не состоится, и это правильный отказ, а не ошибка.
Параметры
| id | path · обязателен | Идентификатор акции |
Тело запроса
Ответы
POST /api/v1/me/campaigns/{id}/deal токен Принять обмен данными
Человек передаёт запрошенные данные и получает награду. Награда даётся один раз: вторая анкета и вторая награда превратили бы обмен в кран. Кода здесь нет — предмет сделки сами данные. Если передан ключ канала, надбавка начисляется так же, как при скане кода.
Параметры
| id | path · обязателен |
Тело запроса
Ответы
GET /api/v1/me/campaigns/{id}/invite токен Моя ссылка-приглашение
Код приглашения и сколько друзей уже пришло.
Параметры
| id | path · обязателен | Идентификатор акции |
Ответы
POST /api/v1/me/campaigns/{id}/quiz токен Ответить на квиз
Ответы проверяет сервер. Пройти квиз можно один раз. Если передан ключ канала, надбавка начисляется так же, как при скане кода.
Параметры
| id | path · обязателен | Идентификатор акции |
Тело запроса
Ответы
PUT /api/v1/me/contacts токен Сохранить контакты
Телефон и Telegram. Пока они только хранятся: подтверждения нет, и писать «подтверждено» там, где ничего не проверено, нельзя.
Тело запроса
Ответы
POST /api/v1/me/contests/{id}/entry токен Прислать работу
Одна работа на человека: иначе один участник забивает ленту работ и собирает голоса количеством, а не качеством. Повторная отправка переписывает свою же работу и снова уходит на модерацию — проверенную работу нельзя подменить после одобрения.
Параметры
| id | path · обязателен |
Тело запроса
Ответы
POST /api/v1/me/contests/{id}/vote токен Проголосовать
Голос от подтверждённого аккаунта: иначе конкурс выигрывает тот, кто быстрее заводит почтовые ящики. За свою работу голосовать нельзя. Повторный голос не проходит — это держит первичный ключ, а не проверка в коде.
Параметры
| id | path · обязателен |
Тело запроса
Ответы
GET /api/v1/me/entries токен Мои участия
Билеты, мгновенные исходы и призы по всем акциям.
Ответы
POST /api/v1/me/invites/{code} токен Принять приглашение
Засчитывает приход по чужой ссылке. Себя пригласить нельзя.
Параметры
| code | path · обязателен |
Ответы
GET /api/v1/me/notifications токен Уведомления
Старты, розыгрыши, призы и переносы сроков.
Ответы
POST /api/v1/me/notifications/read токен Отметить прочитанными
Сбрасывает счётчик непрочитанного.
Ответы
GET /api/v1/me/points токен Баллы
Баланс и вся история начислений. Баланс — это сумма истории, а не отдельное число: так он не может с ней разойтись.
Ответы
GET /api/v1/me/profile токен Анкета и согласия
Восемь полей закрытого списка и журнал «кому я передал данные».
Ответы
PUT /api/v1/me/profile токен Сохранить анкету
Любое поле можно оставить пустым.
Тело запроса
Ответы
POST /api/v1/me/redeem токен Погасить код
Главная операция платформы. Код одноразовый: единственный условный UPDATE в базе гарантирует, что из двух одновременных сканов выиграет ровно один. Ответ 428 — это не ошибка, а незаконченный шаг: нужно согласие на передачу данных или выбор одной из трёх цифр. При таком отказе код не тратится.
Тело запроса
Ответы
PUT /api/v1/me/region токен Сменить страну
Только с подтверждённой почтой: страна определяет, в каких акциях человек участвует.
Тело запроса
Ответы
POST /api/v1/me/reminders токен Напомнить о розыгрыше
Ставит или снимает напоминание по акции.
Тело запроса
Ответы
GET /api/v1/me/tickets токен Мои билеты
Плоский список билетов с номерами и выбранными цифрами.
Ответы
GET /api/v1/me/wins токен Мои выигрыши
Призы и их статусы выдачи.
Ответы
GET /api/v1/outcomes/{id}/proof токен Доказательство мгновенного исхода
Сид, подпись и формула, по которой исход можно пересчитать самому после окончания акции.
Параметры
| id | path · обязателен | Идентификатор исхода |
Ответы
Кабинет партнёра
Токен `console`. Бренд берётся из токена: назвать чужой бренд кабинет не может.
GET /api/v1/console/audit токен Аудит-журнал бренда
Что делал сам бренд и что с ним делала платформа.
Параметры
| limit | query | Сколько записей. |
Ответы
PUT /api/v1/console/brand токен Профиль бренда
Только владелец. Отметку «проверен», блокировку и разрез ленты отсюда менять нельзя — это решения платформы.
Тело запроса
Ответы
GET /api/v1/console/campaigns токен Акции бренда
Все акции бренда из токена, включая черновики.
Ответы
POST /api/v1/console/campaigns токен Сохранить черновик
Создаёт или правит черновик. Запущенную акцию менять нельзя — только скопировать в новую.
Тело запроса
Ответы
GET /api/v1/console/campaigns/{id} токен Акция целиком
Акция, её показатели, партии кодов, обязательство честности и победители.
Параметры
| id | path · обязателен | Идентификатор акции |
Ответы
POST /api/v1/console/campaigns/{id}/close токен Закрыть приём кодов
Останавливает приём раньше срока и замораживает список билетов корнем Меркла.
Параметры
| id | path · обязателен | Идентификатор акции |
Ответы
POST /api/v1/console/campaigns/{id}/codes токен Загрузить коды
CSV или перенос строки: один код на строку. Хранятся только HMAC-хеши — из базы коды не восстановить. Дубликаты внутри файла пропускаются, а не роняют всю партию.
Параметры
| id | path · обязателен | Идентификатор акции |
Тело запроса
Ответы
GET /api/v1/console/campaigns/{id}/data токен Собранные данные
Обезличенная сводка по анкетам участников: бренду видна статистика, а не кто как ответил.
Параметры
| id | path · обязателен | Идентификатор акции |
Ответы
POST /api/v1/console/campaigns/{id}/draw токен Провести розыгрыш
Внешний сид — публичное число, которое организатор не выбирает: тираж гослото, курс, блок. Победители и запасные определяются одним проходом, и список публикуется целиком.
Параметры
| id | path · обязателен | Идентификатор акции |
Тело запроса
Ответы
POST /api/v1/console/campaigns/{id}/duplicate токен Копия акции
Копия запущенной акции в черновик: единственный законный способ «поменять условия».
Параметры
| id | path · обязателен | Идентификатор акции |
Ответы
GET /api/v1/console/campaigns/{id}/economics токен Экономика акции
Бюджет, расходы, себестоимость призов, ROI, ROMI, CAC и LTV. Тариф «Про».
Параметры
| id | path · обязателен | Идентификатор акции |
Ответы
PUT /api/v1/console/campaigns/{id}/economics токен Сохранить смету
Смета, в отличие от правил, правится и после запуска: это внутренний учёт бренда, а не обещание участникам.
Параметры
| id | path · обязателен | Идентификатор акции |
Тело запроса
Ответы
GET /api/v1/console/campaigns/{id}/links токен Каналы акции
Ссылки с условием и их счётчики: сколько человек пришло и сколько воспользовалось. Здесь же готовые адреса — партнёр копирует ссылку, а не склеивает её из домена и ключа.
Параметры
| id | path · обязателен |
Ответы
POST /api/v1/console/campaigns/{id}/links токен Создать или изменить канал
Условие канала правится и после запуска акции, в отличие от самих условий акции: акция — обещание всем участникам сразу, а канал — отдельное предложение одному каналу продвижения, и бренд вправе завести новый баннер завтра. Текст обещания обязателен: надбавка, о которой человек узнаёт постфактум, ничем не отличается от её отсутствия. Ключ уникален на всю платформу — он стоит в адресе.
Параметры
| id | path · обязателен |
Тело запроса
Ответы
GET /api/v1/console/campaigns/{id}/participants.csv токен Выгрузить участников акции
Таблица участников: билеты, призы, состояние выдачи и поля анкеты. Логин и телефон не выгружаются никогда — вход в приложение дело платформы. Поля анкеты попадают в выгрузку только те, что акция запрашивала и человек подтвердил; отказавшийся виден в списке, но его колонки пустые. Факт выгрузки пишется в журнал.
Параметры
| id | path · обязателен | Идентификатор акции. |
Ответы
PUT /api/v1/console/campaigns/{id}/proof токен Ролик и доказательство призов
Отдельно от черновика, потому что работает в любом статусе: условия запущенной акции не меняются — это обещание участникам, — а ролик и фото призового фонда обещанием не являются, это то, чем его подкрепляют. Ссылки принимаются только на https. Подмена доказательства снимает отметку платформы: проверяли предыдущий файл.
Параметры
| id | path · обязателен |
Тело запроса
Ответы
POST /api/v1/console/campaigns/{id}/publish токен Запустить акцию
Фиксирует правила хешем и создаёт обязательство честности: хеш сида публикуется до старта, иначе «сид опубликован заранее» — пустые слова. Бренд, заблокированный платформой, запустить акцию не может.
Параметры
| id | path · обязателен | Идентификатор акции |
Ответы
GET /api/v1/console/claims токен Очередь выдачи призов
Призы по статусам: что оформляют, что готово, что получено.
Параметры
| status | query | Статусы через запятую. |
Ответы
POST /api/v1/console/claims/{id}/ready токен Приз готов к выдаче
Указывает точку выдачи. До этого участник не может подтвердить получение.
Параметры
| id | path · обязателен | Идентификатор приза |
Тело запроса
Ответы
POST /api/v1/console/login Вход партнёра
Почта и пароль. Возвращает токен с аудиторией console: он не открывает ни приложение покупателя, ни админку платформы.
Тело запроса
Ответы
GET /api/v1/console/me токен Бренд и показатели
Бренд приходит из токена, а не из запроса: кабинет не может назвать чужой бренд. Рейтинг здесь — то же число, что покупатель видит на карточке.
Ответы
POST /api/v1/console/media токен Загрузить файл
Фото призового фонда или ролик на страницу акции. Тип определяется по содержимому, а не по имени файла: расширение пишет тот, кто загружает. Принимаются JPEG, PNG, WebP, MP4 и WebM; предел размера задаётся настройкой.
Тело запроса
Ответы
POST /api/v1/console/preview/landing токен Превью страницы акции
Настоящая серверная страница по черновику — та же, что увидит покупатель, а не её копия.
Тело запроса
Ответы
POST /api/v1/console/preview/rules токен Превью правил
Текст правил по черновику, без сохранения: мастер показывает его рядом с формой.
Тело запроса
Ответы
GET /api/v1/console/reviews токен Отзывы и рейтинг
Скрытые модератором отзывы сюда не приходят и в рейтинге не считаются.
Ответы
Админка платформы
Токен `admin`. Бренд приходит в запросе — сотрудник платформы по определению работает с чужими, и поэтому каждое его действие уходит в журнал.
GET /api/v1/admin/audit токен Журнал платформы
Один журнал на всех: действия партнёров и решения платформы. Актор вида admin:<почта> — это решение платформы.
Параметры
| entity | query | Тип объекта: brand, campaign, claim, slide, admin. |
| limit | query | Сколько записей. |
Ответы
GET /api/v1/admin/backups токен Резервные копии участников
Список ежедневных копий данных участников: сами участники, их анкеты, согласия, билеты, исходы, призы и конкурсные работы. Копия пишется раз в сутки планировщиком и хранится настроенное число дней — личные данные, лежащие дольше, чем нужно, это риск без пользы.
Ответы
POST /api/v1/admin/backups токен Сделать копию сейчас
Копия за сегодня перезаписывается. Нужна перед рискованной операцией, когда ждать ночного запуска незачем. Доступно модератору и выше.
Ответы
GET /api/v1/admin/brands токен Все бренды
Включая тех, у кого ещё нет ни одной опубликованной акции: именно они и ждут проверки.
Ответы
PUT /api/v1/admin/brands/{id} токен Проверка, блокировка, сфера
Три решения платформы о бренде. Блокировка снимает его с витрины и закрывает приём кодов, но не удаляет ни бренд, ни акции: у участников на руках билеты и незабранные призы. Причина обязательна. Пустая строка в sphere возвращает автоматический разбор категории. Поле demo помечает компанию витриной: пометка уходит и на её акции — компания-витрина не может проводить настоящий розыгрыш, потому что приза за ним нет и выдавать его некому. Ни у бренда, ни у акции пометка не попадает в публичный JSON: по ответу приложения не должно быть видно, витрина это или настоящий партнёр.
Параметры
| id | path · обязателен | Идентификатор бренда |
Тело запроса
Ответы
GET /api/v1/admin/campaigns токен Акции всех брендов
С фильтрами по бренду и статусу. Выдача ограничена лимитом: выгружать всю платформу одним ответом незачем.
Параметры
| brand | query | Идентификатор бренда. |
| status | query | Статус акции. (draft · scheduled · active · ended · drawn) |
Ответы
POST /api/v1/admin/campaigns токен Черновик от имени бренда
Бренд приходит в теле запроса — это и есть «создать акцию за компанию». Автором в журнале остаётся сотрудник платформы: подменять автора решения нельзя даже ради красоты ленты событий.
Тело запроса
Ответы
PUT /api/v1/admin/campaigns/{id} токен Пометки платформы на акции
Две пометки. «Демо» — витрина: акция видна в ленте и выглядит как настоящая, но участия сервер не проводит, и покупателю об этом не сообщается. «Призы проверены» — платформа посмотрела доказательство, которое приложил партнёр, и отвечает за это именем: в журнале остаётся кто и когда. Без приложенного доказательства отметку поставить нельзя — иначе это просто галочка, а правка доказательства её снимает: проверяли предыдущий файл.
Параметры
| id | path · обязателен | Идентификатор акции |
Тело запроса
Ответы
POST /api/v1/admin/campaigns/{id}/archive токен Убрать акцию в архив или вернуть
Архив отвечает на вопрос «показывать ли акцию в ленте», статус — на вопрос «что с ней происходит». Идущую акцию убрать нельзя: человек с кодом в руках должен найти её там, где она была. Страница акции, список билетов и доказательства розыгрыша остаются доступными по прежнему адресу всегда — это то, чем человек доказывает своё участие.
Параметры
| id | path · обязателен |
Тело запроса
Ответы
POST /api/v1/admin/campaigns/{id}/close токен Закрыть приём кодов
Останавливает приём и замораживает список билетов.
Параметры
| id | path · обязателен | Идентификатор акции |
Ответы
POST /api/v1/admin/campaigns/{id}/publish токен Запустить акцию
То же, что в кабинете, но от имени платформы. Заблокированному бренду сервер откажет.
Параметры
| id | path · обязателен | Идентификатор акции |
Ответы
GET /api/v1/admin/contests токен Все конкурсы
Включая черновики.
Ответы
POST /api/v1/admin/contests токен Новый конкурс
Создаётся черновиком: пока его не открыли, он не виден никому.
Тело запроса
Ответы
PUT /api/v1/admin/contests/{id} токен Правка конкурса
Меняются название, условия, сроки, способ голосования и переводы. Ключевое не меняется: этап задаётся отдельной ручкой, а снимок итогов пересчитать нельзя.
Параметры
| id | path · обязателен |
Тело запроса
Ответы
GET /api/v1/admin/contests/{id}/entries токен Работы конкурса
Очередь модерации.
Параметры
| id | path · обязателен | |
| status | query | (pending · approved · rejected) |
Ответы
POST /api/v1/admin/contests/{id}/stage токен Следующий этап
Черновик → приём работ → голосование → итоги. Только вперёд: вернуть голосование в приём означало бы посмотреть на расклад и дать «своим» дослать ещё. На итогах считается снимок результатов.
Параметры
| id | path · обязателен |
Тело запроса
Ответы
PUT /api/v1/admin/entries/{id} токен Решение по работе
Отказ требует причины: решение без причины нельзя оспорить. Участник получает уведомление.
Параметры
| id | path · обязателен |
Тело запроса
Ответы
POST /api/v1/admin/login Вход сотрудника платформы
Отдельный вход и отдельная аудитория токена admin: токен кабинета партнёра админку не открывает даже при ошибке в проверке роли.
Тело запроса
Ответы
GET /api/v1/admin/me токен Кто я и что мне можно
Роль проверяется при каждом обращении: доступ, отключённый после выдачи токена, перестаёт работать сразу.
Ответы
POST /api/v1/admin/media токен Загрузить файл
То же, что в кабинете: проверяющий тоже прикладывает снимок.
Тело запроса
Ответы
GET /api/v1/admin/overview токен Обзор платформы
Числа считаются запросами, а не по загруженному срезу: «отзывов 200» на тысяче отзывов выглядело бы как правда.
Ответы
GET /api/v1/admin/reviews токен Очередь модерации
Здесь, в отличие от публичного списка, видно и скрытые отзывы, и кто их скрыл.
Параметры
| only | query | Что показывать. ( · visible · hidden) |
| brand | query | Идентификатор бренда. |
| limit | query | Сколько записей. |
Ответы
PUT /api/v1/admin/reviews/{id} токен Скрыть или вернуть отзыв
Скрытие требует причины и всегда обратимо. Скрытый отзыв выпадает и из публичного списка, и из рейтинга — вместе с оценкой, иначе «скрыть» означало бы спрятать текст, оставив звёзды работать. Удаления нет: удалённый отзыв нельзя ни оспорить, ни восстановить.
Параметры
| id | path · обязателен | Идентификатор приза, к которому написан отзыв |
Тело запроса
Ответы
GET /api/v1/admin/settings токен Настройки платформы
Переключатели, которые платформа держит за собой. Сейчас один: video_upload — разрешена ли партнёрам загрузка роликов файлом. Выключен по умолчанию: ролик на 50 МБ, умноженный на число акций, упирается в диск сервера и в платный исходящий трафик, а ссылка на YouTube, Vimeo, Rutube или VK Видео даёт тот же ролик на странице акции и ничего не стоит. Отдельному бренду можно разрешить или запретить вопреки общей настройке — через video_upload в PUT /api/v1/admin/brands/{id}.
Ответы
PUT /api/v1/admin/settings токен Изменить настройку
Доступно модератору и выше. Факт изменения уходит в журнал.
Тело запроса
Ответы
GET /api/v1/admin/slides токен Слайды главной полосы
Все слайды, включая выключенные и те, чьё окно показа ещё не наступило.
Ответы
POST /api/v1/admin/slides токен Новый слайд
Слайды оператора идут первыми, остальное приложение собирает из ленты само. Ссылка принимается только как путь приложения или адрес на https.
Тело запроса
Ответы
PUT /api/v1/admin/slides/{id} токен Правка слайда
То же, что создание, но по идентификатору.
Параметры
| id | path · обязателен | Идентификатор слайда |
Тело запроса
Ответы
DELETE /api/v1/admin/slides/{id} токен Удалить слайд
У слайда нет истории, которую стоило бы хранить, — есть журнал действий.
Параметры
| id | path · обязателен | Идентификатор слайда |
Ответы
GET /api/v1/admin/spheres токен Категории ленты
Каталог разрезов ленты со счётчиком брендов у каждой категории: удалять её вслепую нельзя.
Ответы
POST /api/v1/admin/spheres токен Новая категория
Ключ задаётся один раз: он уезжает в адрес страницы и в аналитику, и менять его значит ломать чужие ссылки. Приметы — слова, по которым свободная категория бренда попадёт в эту сферу автоматически.
Тело запроса
Ответы
PUT /api/v1/admin/spheres/{key} токен Правка категории
Меняются название, иконка, приметы, порядок и признак «показывать». Ключ — нет.
Параметры
| key | path · обязателен |
Тело запроса
Ответы
DELETE /api/v1/admin/spheres/{key} токен Удалить категорию
Встроенную удалить нельзя — её можно выключить. Категорию, в которой есть бренды, сервер тоже не удалит: они пропали бы из разрезов ленты молча.
Параметры
| key | path · обязателен |
Ответы
GET /api/v1/admin/staff токен Сотрудники платформы
Только суперадмину: это карта доступов платформы.
Ответы
POST /api/v1/admin/staff токен Завести сотрудника
Пароль не короче десяти символов. Роли: суперадмин — всё, модератор — бренды, отзывы, акции и полоса, поддержка — только чтение.
Тело запроса
Ответы
PUT /api/v1/admin/staff/{id} токен Роль и доступ сотрудника
Отключение вместо удаления: в журнале остаются его решения, и по ним должно быть видно, кто их принял. Последнего живого суперадмина нельзя ни разжаловать, ни отключить. Пустой пароль означает «не менять».
Параметры
| id | path · обязателен | Идентификатор сотрудника |
Тело запроса
Ответы
GET /api/v1/admin/subscribers.csv токен Выгрузить список рассылки
CSV для почтового сервиса: адрес, страна, язык, откуда подписался и дата. Отписавшиеся в выгрузку не попадают. Факт выгрузки пишется в журнал.
Ответы
GET /api/v1/admin/visits токен Посещаемость
Сводка за период: визиты и посетители по дням, странам, видам страниц, источникам и акциям. Страна берётся из заголовка обратного прокси (CF-IPCountry и подобных); своей базы адресов у платформы нет, поэтому без прокси страна пустая — и в сводке это видно отдельной строкой.
Параметры
| days | query | За сколько последних суток считать. |
Ответы
Страницы
Серверный рендер: главная, страницы акций, юридические документы.
GET / Главная платформы
Серверный рендер: что это, кому, как работает, каталог механик, честность и вопросы. Страница должна индексироваться и открываться без JavaScript.
Ответы
GET /docs Этот справочник
Страница, которую ты сейчас читаешь: собирается из openapi.json.
Ответы
GET /e/{brand}/{campaign} Карточка акции для вставки
Компактная страница акции для чужого сайта: название, приз, отсчёт, отметки платформы и ссылки на акцию и правила. Встраивание разрешено с любого домена (frame-ancestors *) — в этом смысл виджета, и ничего, кроме уже опубликованного, на странице нет. Черновик не отдаётся.
Параметры
| brand | path · обязателен | Адрес бренда. |
| campaign | path · обязателен | Адрес акции. |
| theme | query | Тема карточки; по умолчанию следует за системной. (auto · dark · light) |
Ответы
GET /embed.js Скрипт виджета акции
Загрузчик, который партнёр вставляет к себе на сайт одной строкой: <script src="/embed.js" data-campaign="бренд/акция" async></script>. Скрипт ставит на своё место iframe с карточкой акции и подгоняет его высоту по сообщению изнутри. Атрибуты: data-theme (auto, dark, light) и data-width.
Ответы
GET /favicon.svg Знак платформы
Фавиконка, встроенная в бинарник.
Ответы
GET /i/{code} Ссылка-приглашение
Переадресация в приложение с кодом приглашения.
Параметры
| code | path · обязателен |
Ответы
GET /l/{key} Короткая ссылка канала
Переадресует на страницу акции с ключом канала. Короткий путь, а не длинный с параметром, потому что ссылку печатают на баннере и читают вслух. Переадресация временная (302): канал можно выключить, а постоянная осталась бы в кэше браузера навсегда.
Параметры
| key | path · обязателен |
Ответы
GET /llms.txt Описание платформы для языковых моделей
Поисковик индексирует страницы, а языковая модель пересказывает. Пересказ выходит точнее, когда есть короткий текст с фактами и ссылками: что это, кому, как устроена проверяемость и где лежит остальное.
Ответы
GET /media/{name} Загруженный файл
Отдаётся с запретом на исполнение: загруженный партнёром файл — это файл, а не страница на домене платформы. Имя случайное, поэтому кэш длинный.
Параметры
| name | path · обязателен |
Ответы
GET /og.png Картинка превью ссылки
Одна на все страницы: ссылки на акции чаще пересылают в мессенджерах, чем открывают из поиска, и карточка без картинки там теряется.
Ответы
GET /openapi.json Спецификация OpenAPI
Та же спецификация машиночитаемо: импортируется в Postman, Insomnia, Swagger Editor или в генератор клиентов.
Ответы
GET /participants Главная для участников
Вторая вкладка главной. Отдельный адрес, а не переключатель на JavaScript: у брендов и у участников разные вопросы — бренд спрашивает «что это мне даст», человек «не обманут ли меня», — а страница, отвечающая обоим сразу, не отвечает никому. На отдельную вкладку можно дать ссылку, и поиск видит две страницы, а не одну с пустой половиной.
Ответы
GET /privacy Политика конфиденциальности
Что собирается, зачем и что уходит бренду.
Ответы
GET /robots.txt Правила обхода для роботов
Закрыты API, виджеты для чужих сайтов (их индексация плодит дубли страниц акций) и служебные адреса. Там же ссылка на карту сайта.
Ответы
GET /sitemap.xml Карта сайта
Главная, юридические страницы, справочник API и все публичные страницы акций с датой последнего изменения и языковыми вариантами. Черновики не попадают — у них нет публичной страницы; демонстрационные акции и заблокированные бренды тоже: витрина нужна, чтобы лента не выглядела пустой для живого человека, а выдавать поиску акции несуществующих брендов значит обещать несуществующее незнакомым людям.
Ответы
GET /terms Условия использования
Кто за что отвечает. Пилотный статус назван прямо.
Ответы
GET /{brand}/{campaign} Страница акции
Серверный рендер страницы акции: условия, призы, правила с хешем, участники и результат. Работает без JavaScript. У заблокированного бренда страница остаётся открытой — на ней доказательства участия, — но призыв участвовать с неё исчезает.
Параметры
| brand | path · обязателен | |
| campaign | path · обязателен | |
| lang | query | Язык ответа. Сильнее заголовка Accept-Language: переключатель в интерфейсе должен работать независимо от настроек системы. (ru · en) |
Ответы
GET /{brand}/{campaign}/{page} Доп. страница акции
Правила, «о бренде», условия выдачи — всё, что партнёр добавил к акции отдельными страницами.
Параметры
| brand | path · обязателен | |
| campaign | path · обязателен | |
| page | path · обязателен |
Ответы
Покупатель
POST /api/v1/me/media токен Загрузить файл работы
Фото, иллюстрация или ролик для конкурсной работы. Тот же приём, что у партнёра: тип определяется по содержимому, принимаются JPEG, PNG, WebP, MP4 и WebM.