sno-quiz/backend/QR_API_EXAMPLES.md

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

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

### POST /api/admin/qrcodes

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

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

**Response (200 OK):**
```json
{
  "success": true,
  "message": "5 unique QR codes generated successfully",
  "data": {
    "tokens": [
      "a1b2c3d4e5f678901234567890abcdef",
      "b2c3d4e5f678901234567890abcdef12",
      "c3d4e5f678901234567890abcdef1234",
      "d4e5f678901234567890abcdef123456",
      "e5f678901234567890abcdef12345678"
    ]
  }
}
```

---

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

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

**Response (200 OK):**
```json
{
  "success": true,
  "message": "3 unique QR codes generated successfully",
  "data": {
    "tokens": [
      "f678901234567890abcdef1234567890a",
      "78901234567890abcdef1234567890ab",
      "8901234567890abcdef1234567890abc"
    ]
  }
}
```

---

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

**Request:**
```bash
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):**
```json
{
  "success": true,
  "message": "2 unique QR codes generated successfully",
  "data": {
    "tokens": [
      "901234567890abcdef1234567890abcd",
      "01234567890abcdef1234567890bcde"
    ]
  }
}
```

---

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

### POST /api/qr/validate

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

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

---

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

**Response (200 OK):**
```json
{
  "success": true,
  "message": "QR payload validated successfully",
  "data": {
    "type": "REWARD",
    "data": {
      "amount": 50
    }
  }
}
```

---

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

**Response (200 OK):**
```json
{
  "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):**
```json
{
  "success": true,
  "message": "QR payload validated successfully",
  "data": {
    "type": "SHOP_ACTION",
    "data": {
      "action": "discount_10"
    }
  }
}
```

---

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

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

**Response (400 Bad Request):**
```json
{
  "success": false,
  "message": "invalid or expired token"
}
```

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

**Response (400 Bad Request):**
```json
{
  "success": false,
  "message": "token has already been used"
}
```

### Пустой payload

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

**Response (400 Bad Request):**
```json
{
  "success": false,
  "message": "Payload cannot be empty"
}
```

---

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

### Неверный тип

**Request:**
```bash
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):**
```json
{
  "success": false,
  "message": "Invalid type. Must be 'reward', 'quiz', or 'shop'"
}
```

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

**Request:**
```bash
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):**
```json
{
  "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 (магазин)
- **Валидация** проверяет существование, срок действия и факт использования