sno-quiz/backend/QR_API_EXAMPLES.md

QR API Endpoints - Примеры запросов

1. Генерация QR кодов (Admin endpoint)

POST /api/admin/qrcodes

Генерирует уникальные QR токены указанного типа.

Request:

curl -X POST http://localhost:8080/api/admin/qrcodes \
  -H "Content-Type: application/json" \
  -d '{
    "type": "reward",
    "value": "50",
    "count": 5
  }'

Response (200 OK):

{
  "success": true,
  "message": "5 unique QR codes generated successfully",
  "data": {
    "tokens": [
      "a1b2c3d4e5f678901234567890abcdef",
      "b2c3d4e5f678901234567890abcdef12",
      "c3d4e5f678901234567890abcdef1234",
      "d4e5f678901234567890abcdef123456",
      "e5f678901234567890abcdef12345678"
    ]
  }
}

---

Генерация QR для викторины

Request:

curl -X POST http://localhost:8080/api/admin/qrcodes \
  -H "Content-Type: application/json" \
  -d '{
    "type": "quiz",
    "value": "123",
    "count": 3
  }'

Response (200 OK):

{
  "success": true,
  "message": "3 unique QR codes generated successfully",
  "data": {
    "tokens": [
      "f678901234567890abcdef1234567890a",
      "78901234567890abcdef1234567890ab",
      "8901234567890abcdef1234567890abc"
    ]
  }
}

---

Генерация QR для магазина

Request:

curl -X POST http://localhost:8080/api/admin/qrcodes \
  -H "Content-Type: application/json" \
  -d '{
    "type": "shop",
    "value": "discount_10",
    "count": 2
  }'

Response (200 OK):

{
  "success": true,
  "message": "2 unique QR codes generated successfully",
  "data": {
    "tokens": [
      "901234567890abcdef1234567890abcd",
      "01234567890abcdef1234567890bcde"
    ]
  }
}

---

2. Валидация QR кодов (User endpoint)

POST /api/qr/validate

Валидирует уникальный токен и выполняет соответствующее действие.

Request:

curl -X POST http://localhost:8080/api/qr/validate \
  -H "Content-Type: application/json" \
  -d '{
    "payload": "a1b2c3d4e5f678901234567890abcdef"
  }'

---

Успешная валидация reward токена

Response (200 OK):

{
  "success": true,
  "message": "QR payload validated successfully",
  "data": {
    "type": "REWARD",
    "data": {
      "amount": 50
    }
  }
}

---

Успешная валидация quiz токена

Response (200 OK):

{
  "success": true,
  "message": "QR payload validated successfully",
  "data": {
    "type": "OPEN_QUIZ",
    "data": {
      "id": 123,
      "title": "Знаешь ли ты бренд?",
      "description": "Тест на знание популярных брендов",
      "reward_stars": 100,
      "has_timer": false,
      "can_repeat": true,
      "repeat_cooldown_hours": 24,
      "questions": [
        {
          "id": 1,
          "text": "Какой бренд использует слоган 'Just Do It'?",
          "type": "single",
          "options": [
            {"id": 1, "text": "Adidas", "is_correct": false},
            {"id": 2, "text": "Nike", "is_correct": true},
            {"id": 3, "text": "Puma", "is_correct": false}
          ],
          "order_index": 0
        }
      ]
    }
  }
}

---

Успешная валидация shop токена

Response (200 OK):

{
  "success": true,
  "message": "QR payload validated successfully",
  "data": {
    "type": "SHOP_ACTION",
    "data": {
      "action": "discount_10"
    }
  }
}

---

3. Ошибки валидации

Неверный или просроченный токен

Response (400 Bad Request):

{
  "success": false,
  "message": "invalid or expired token"
}

Токен уже использован

Response (400 Bad Request):

{
  "success": false,
  "message": "token has already been used"
}

Пустой payload

Request:

curl -X POST http://localhost:8080/api/qr/validate \
  -H "Content-Type: application/json" \
  -d '{
    "payload": ""
  }'

Response (400 Bad Request):

{
  "success": false,
  "message": "Payload cannot be empty"
}

---

4. Ошибки генерации QR кодов

Неверный тип

Request:

curl -X POST http://localhost:8080/api/admin/qrcodes \
  -H "Content-Type: application/json" \
  -d '{
    "type": "invalid_type",
    "value": "50",
    "count": 1
  }'

Response (400 Bad Request):

{
  "success": false,
  "message": "Invalid type. Must be 'reward', 'quiz', or 'shop'"
}

Неверное количество

Request:

curl -X POST http://localhost:8080/api/admin/qrcodes \
  -H "Content-Type: application/json" \
  -d '{
    "type": "reward",
    "value": "50",
    "count": 0
  }'

Response (400 Bad Request):

{
  "success": false,
  "message": "Count must be between 1 and 100"
}

---

5. Как использовать сгенерированные токены

1. Сгенерируйте токены через админский эндпоинт
2. Создайте QR коды с полученными токенами (используйте любой QR генератор)
3. Разместите QR коды в физических локациях или в цифровых материалах
4. Пользователи сканируют QR коды через приложение
5. Приложение отправляет токен на /api/qr/validate
6. Система выполняет действие (начисляет звезды, открывает викторину и т.д.)

Пример QR кода для награды:

Содержимое QR кода: a1b2c3d4e5f678901234567890abcdef

Пример QR кода для викторины:

Содержимое QR кода: f678901234567890abcdef1234567890a

---

6. Технические особенности

• Токены имеют 128-битную энтропию (32 шестнадцатеричных символа)
• Хранятся в Redis с 30-дневным сроком действия
• Одноразовые - после использования помечаются как использованные
• Типы: reward (награда), quiz (викторина), shop (магазин)
• Валидация проверяет существование, срок действия и факт использования