API Reference

Вызовите API Promify, чтобы запросить рекламный креатив и зарегистрировать показ выбранного объявления.

1. Базовый URL и авторизация

• Базовый URL: https://api.promify.org/v1/
• Авторизация: добавьте токен приложения в каждый запрос:

X-App-Token: <ваш_токен>

2. Эндпоинты API

2.1. Получение рекламы

Запросите рекламный креатив, чтобы подобрать креатив для конкретного пользователя.

• Путь: /v1/ad
• Метод: POST
• Тип контента: application/json

Тело запроса

Пример metadata: {"artist": "Darci", "genre": "rap"}.

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

{
  "user_id": 12345,
  "metadata": {
    "genre": "rap",
    "artist": "Darci",
    "track": "On My Own"
  },
  "format": "teaser"
}

Ответы сервера

200 OK — креатив подобран

Возвращает объект креатива в зависимости от запрошенного формата.

Формат Teaser (type: "teaser")

{
  "type": "teaser",
  "text": "Рекламный текст объявления",
  "image_url": "https://example.com/image.jpg",
  "link": "https://c.promify.org/...",
  "impression_id": "уникальный_id_показа"
}

• text (string): текст рекламного объявления.
• image_url (string, optional): ссылка на изображение. Может быть null.
• link (string): URL для перенаправления пользователя при клике на объявление.
• impression_id (string): уникальный идентификатор показа.

Используйте impression_id для отправки подтверждения показа.

Формат Caption (type: "caption")

{
  "type": "caption",
  "text": "Рекламный текст объявления",
  "link": "https://c.promify.org/...",
  "impression_id": "уникальный_id_показа"
}

204 No Content — нет рекламы

Нет подходящих рекламных объявлений для показа. Отобразите собственный резервный баннер.

400 Bad Request — ошибка в запросе

Некорректный JSON, отсутствуют обязательные поля или указан неизвестный формат рекламы.

401 Unauthorized — ошибка авторизации

Отсутствует или недействителен заголовок X-App-Token.

2.2. Регистрация показа

Отправьте подтверждение о том, что выбранный креатив был отображен на экране пользователя.

• Путь: /v1/impression
• Метод: POST
• Тип контента: application/json

Тело запроса

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

{
  "impression_id": "уникальный_id_показа"
}

Ответы сервера

200 OK — показ зарегистрирован

Показ успешно учтен платформой. Тело ответа пустое.

400 Bad Request — неверный ID показа

Указан несуществующий или некорректный impression_id.

401 Unauthorized — ошибка авторизации

Невалидный токен приложения или попытка отправить показ для чужого приложения.