# Dokumentacja ID Magico - TravelManager Integration

Zbiór dokumentacji opisującej integrację systemu TravelManager z ekosystemem Magico.

---

## Przegląd dokumentów

### 🔐 [Proces autentykacji ID Magico](ID_MAGICO_AUTH_PROCCESS.md)
**Dokumentacja autentykacji i sesji użytkowników**

Szczegółowy opis procesu logowania użytkowników przez system ID Magico oraz zarządzania sesjami w API TravelManager. Zawiera:
- Flow OAuth 2.0 Authorization Code
- Proces wymiany kodu autoryzacyjnego na token dostępu
- Ustawianie i zarządzanie sesjami w TravelManager API
- Weryfikację tokenów z systemem ID Magico
- Diagram sekwencji całego procesu autentykacji
- Obsługę wylogowania i błędów autoryzacji

**Kluczowe elementy:** OAuth flow, tokeny Bearer, sesje ciasteczkowe, weryfikacja użytkowników

---

### 🏢 [Zarządzanie aplikacjami - wersja 1](COMPANY_MAGICO_APP_MANAGMENT.md)
**Proces aktywacji aplikacji TravelManager (pierwotna wersja)**

Opis pierwotnego procesu aktywacji aplikacji TravelManager w systemie Magico. Obejmuje:
- Aktywację aplikacji przez użytkowników lub administratorów
- Tworzenie tenantów dla firm w systemie TravelManager
- Pobieranie listy użytkowników firmy z API Magico
- Tworzenie powiązań między systemami
- Diagram sekwencji procesu aktywacji

**Model:** Separate API calls - tworzenie tenanta, następnie pobieranie użytkowników

---

### 🏢 [Zarządzanie aplikacjami - wersja 2](COMPANY_MAGICO_APP_MANAGMENT_V2.md) ⭐
**Zaawansowany proces zarządzania aplikacjami (aktualna wersja)**

Ulepszona wersja procesu aktywacji z automatyczną synchronizacją użytkowników. Zawiera:
- **Jednoczesne tworzenie tenanta z użytkownikami** - podczas aktywacji przesyłana jest pełna lista użytkowników
- **Automatyczną synchronizację zmian** - system Magico automatycznie powiadamia o zmianach w użytkownikach
- Dwukierunkową komunikację między systemami
- Kompleksowe diagramy sekwencji dla aktywacji i synchronizacji
- Zaawansowaną obsługę błędów z mechanizmami retry
- Struktury baz danych i mapowanie użytkowników

**Model:** Unified API approach - wszystko w jednym zapytaniu z automatyczną synchronizacją

---

## Porównanie wersji zarządzania aplikacjami

| Aspekt | Wersja 1 | Wersja 2 (Aktualna) |
|--------|----------|---------------------|
| **Tworzenie tenanta** | Minimalne dane (nazwa, ID) | Pełne dane + lista użytkowników |
| **Pobieranie użytkowników** | Osobne zapytanie GET | Automatycznie z aktywacją |
| **Synchronizacja zmian** | Manualna/na żądanie | Automatyczna przez webhook |
| **Endpoints** | 2 oddzielne (tenant + users) | 2 zintegrowane (create + sync) |
| **Złożoność** | Prosta, sekwencyjna | Zaawansowana, reaktywna |
| **Niezawodność** | Bazowa obsługa błędów | Retry, kolejki, logi |

---

## Architektura integracji

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Użytkownik    │◄──►│   Magico.pro    │◄──►│ TravelManager   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                       │
                                │                       │
                         ┌─────────────────┐    ┌─────────────────┐
                         │  ID.magico.pro  │    │ Company API     │
                         │ (Autentykacja)  │    │ (Użytkownicy)   │
                         └─────────────────┘    └─────────────────┘
```

## Główne przepływy danych

1. **Autentykacja użytkownika:** Użytkownik → ID Magico → TravelManager API
2. **Aktywacja aplikacji:** Magico → TravelManager (tworzenie tenanta + użytkownicy)
3. **Synchronizacja zmian:** Magico → TravelManager (aktualizacja użytkowników)
4. **Sesje aplikacji:** TravelManager przechowuje sesje z tokenami z ID Magico

---

## Tokeny i bezpieczeństwo

### Rodzaje tokenów
- **User Access Token** - tokeny OAuth dla użytkowników (z ID Magico)
- **System Token (Magico)** - do tworzenia tenantów w TravelManager
- **System Token (TravelManager)** - do pobierania danych z Magico (tylko v1)

### Bezpieczeństwo
- Wszystkie zapytania przez HTTPS
- Tokeny Bearer w nagłówkach Authorization
- Weryfikacja tokenów przez ID Magico
- Sesje ciasteczkowe po udanej autentykacji

---

## Środowiska i konfiguracja

| Serwis | URL |
|--------|-----|
| **ID Magico (Auth)** | `https://id.magico.pro/` |
| **Magico Panel** | `https://magico.pro/` |
| **Company API** | `https://company.magico.pro/` |
| **TravelManager** | `https://manager.travelmanager.pl/` |

---


---

*Ostatnia aktualizacja: 17 lutego 2026*