API Перевірки Скіпасів

API для перевірки скіпасів через зовнішню систему Bukovel.

Огляд

Цей API дозволяє перевіряти валідність скіпасів перед створенням уроків або бронювань. Система автоматично звертається до зовнішнього API Bukovel для отримання актуальної інформації про скіпас.

Кінцеві точки

Перевірити один скіпас

Запит:

POST /api/v1/skipasses/check/
Authorization: Token YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "skipass_number": "30-2167-26-72093"
}

Відповідь (Успіх):

{
  "status": "success",
  "skipass_number": "30-2167-26-72093",
  "valid": true,
  "error": null,
  "data": {
    "ticket_num": "30-2167-26-72093",
    "card_number": "16147115513376519261",
    "date_issue": "2013-12-22T09:31:20",
    "type_name": "5 днів СЕЗОН",
    "date_begin": "2013-12-22 09:31:00",
    "date_end": "2050-05-15 00:00:00"
  }
}

Відповідь (Невалідний):

{
  "status": "error",
  "skipass_number": "1-1-2-99999",
  "valid": false,
  "error": "Скіпас не знайдено в системі Bukovel",
  "data": null
}

Приклад cURL:

curl -X POST http://localhost:8000/api/v1/skipasses/check/ \
  -H "Authorization: Token YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"skipass_number": "30-2167-26-72093"}'

---

Перевірити декілька скіпасів

Запит:

POST /api/v1/skipasses/check-multiple/
Authorization: Token YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "skipass_numbers": [
    "30-2167-26-72093",
    "1-1-2-20907",
    "12-345-67-89012"
  ]
}

Відповідь:

{
  "status": "success",
  "results": {
    "30-2167-26-72093": {
      "valid": true,
      "error": null,
      "data": {
        "ticket_num": "30-2167-26-72093",
        "card_number": "16147115513376519261",
        "date_issue": "2013-12-22T09:31:20",
        "type_name": "5 днів СЕЗОН",
        "date_begin": "2013-12-22 09:31:00",
        "date_end": "2050-05-15 00:00:00"
      }
    },
    "1-1-2-20907": {
      "valid": false,
      "error": "Скіпас не знайдено в системі Bukovel",
      "data": null
    },
    "12-345-67-89012": {
      "valid": true,
      "error": null,
      "data": {
        "ticket_num": "12-345-67-89012",
        "card_number": "98765432109876543210",
        "date_issue": "2025-11-01T10:00:00",
        "type_name": "День",
        "date_begin": "2025-11-01 10:00:00",
        "date_end": "2025-11-01 23:59:59"
      }
    }
  },
  "summary": {
    "total": 3,
    "valid": 2,
    "invalid": 1
  }
}

Приклад cURL:

curl -X POST http://localhost:8000/api/v1/skipasses/check-multiple/ \
  -H "Authorization: Token YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "skipass_numbers": [
      "30-2167-26-72093",
      "1-1-2-20907",
      "12-345-67-89012"
    ]
  }'

---

Інтеграція з Bukovel API

Система використовує зовнішнє API Bukovel для перевірки скіпасів:

Кінцева точка зовнішнього API:

POST https://skipass-api.bukovel.dev/check-ticket

Аутентифікація:

Authorization: Bearer gkPTzYSRUB1Wj5GUoUuzALdqE4j8VP70zzrjqe1BWdywGHqub6kS6va8Q1BTPwIW

Формат зовнішнього запиту:

{
  "ticketNum": "30-2167-26-72093"
}

Формат зовнішньої відповіді:

{
  "results": [
    {
      "error_id": 0,
      "error_msg": "",
      "TicketNum": "30-2167-26-72093",
      "CardNumberFull": "16147115513376519261",
      "DateIssue": "2013-12-22T09:31:20",
      "TypeName": "5 днів СЕЗОН",
      "DateBegin": "2013-12-22T09:31:00",
      "DateEnd": "2050-05-15T00:00:00"
    }
  ]
}

---

Використання в лижній школі

Процес створення уроку з перевіркою скіпасів:

1. Крок 1: Система продажу лижної школи викликає /api/v1/skipasses/check-multiple/ з масивом скіпасів
2. Крок 2: API перевіряє кожен скіпас через Bukovel API
3. Крок 3: Повертається результат перевірки для кожного скіпасу
4. Крок 4: Якщо всі скіпаси валідні, система створює урок через /api/v1/lessons/
5. Крок 5: Дані про скіпаси (type_name, date_begin, date_end) автоматично зберігаються

Приклад послідовності запитів:

// 1. Перевірити скіпаси
const checkResponse = await fetch('/api/v1/skipasses/check-multiple/', {
  method: 'POST',
  headers: {
    'Authorization': 'Token YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    skipass_numbers: ['30-2167-26-72093', '1-1-2-20907']
  })
});

const checkResult = await checkResponse.json();

// 2. Якщо всі скіпаси валідні - створити урок
if (checkResult.summary.invalid === 0) {
  const lessonResponse = await fetch('/api/v1/lessons/', {
    method: 'POST',
    headers: {
      'Authorization': 'Token YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      booking_number: 'LESSON-123',
      start_datetime: '2025-11-10T10:00:00Z',
      end_datetime: '2025-11-10T12:00:00Z',
      instructor_name: 'Іван Петренко',
      location: 'Буковель-1',
      status: 'active',
      participants: [
        {
          customer: {
            name: 'Олексій',
            surname: 'Коваленко',
            phone_number: '+380501234567'
          },
          skipasses: [
            {
              skipass_number: '30-2167-26-72093',
              // Дані з checkResult автоматично заповнюються
              valid_from: checkResult.results['30-2167-26-72093'].data.date_begin,
              valid_until: checkResult.results['30-2167-26-72093'].data.date_end,
              skipass_type: checkResult.results['30-2167-26-72093'].data.type_name
            }
          ]
        }
      ]
    })
  });
}

---

Обробка помилок

Можливі помилки:

Помилка	HTTP Status	Опис
Поле 'skipass_number' обов'язкове	400	Не передано номер скіпасу
Поле 'skipass_numbers' має бути масивом	400	Невірний формат даних
Скіпас не знайдено в системі Bukovel	400	Скіпас не існує
Timeout: API Bukovel не відповідає	400	Зовнішнє API недоступне
Помилка зв'язку з API	400	Проблеми з мережею

---

Примітки

• ✅ Вимагає аутентифікації (Token)
• ⚡ Кожен скіпас перевіряється окремим запитом до Bukovel API
• 🕒 Таймаут для зовнішніх запитів: 10 секунд
• 📝 Всі перевірки логуються в журналі аудиту
• 🔄 Рекомендується перевіряти скіпаси перед створенням уроків/бронювань