idmagicodocs/COMPANY_MAGICO_APP_MANAGMENT_V2.md

Zarządzanie aplikacją TravelManager w ekosystemie Magico

Dokumentacja procesu aktywacji i zarządzania aplikacją TravelManager dla firm w systemie Magico.

---

Przegląd

Proces aktywacji TravelManager dla firmy składa się z następujących kroków:

1. Aktywacja aplikacji – użytkownik/admin włącza TravelManager w panelu Magico
2. Tworzenie tenanta z użytkownikami – automatyczne utworzenie środowiska dla firmy w TravelManager wraz z przesłaniem listy użytkowników
3. Synchronizacja zmian – automatyczne aktualizowanie listy użytkowników przy każdej zmianie w systemie Magico

---

Krok 1: Aktywacja aplikacji TravelManager

Scenariusze aktywacji

Scenariusz A: Użytkownik w sklepie aplikacji (magico.pro)

• Użytkownik przegląda sklep aplikacji w magico.pro
• Kliknięcie "Aktywuj" przy aplikacji TravelManager

Scenariusz B: Administrator w panelu zarządzania Magico

• Administrator loguje się do panelu zarządzania całym systemem Magico
• Włączenie aplikacji TravelManager dla konkretnej firmy

Rezultat aktywacji

Po kliknięciu aktywacji system Magico:

1. Pobiera listę użytkowników firmy z bazy danych
2. Wykonuje automatycznie POST do TravelManager API z pełnymi danymi tenanta i użytkowników

---

Krok 2: Tworzenie tenanta z użytkownikami w TravelManager

Endpoint tworzenia tenanta z użytkownikami

POST manager.travelmanager.pl/api/tenant

System Magico automatycznie wywołuje ten endpoint po aktywacji aplikacji, przesyłając od razu pełną listę użytkowników firmy.

Nagłówki

Content-Type: application/json
Authorization: Bearer {magico_system_token}

Body żądania

{
  "company_name": "Nazwa Firmy Sp. z o.o.",
  "company_id": 34,
  "users": [
    {
      "name": "Jan Kowalski",
      "email": "jan.kowalski@firma.pl",
      "global_user_id": 123,
      "username": "jan.kowalski",
      "role": "admin",
      "active": true
    },
    {
      "name": "Anna Nowak",
      "email": "anna.nowak@firma.pl",
      "global_user_id": 124,
      "username": "anna.nowak",
      "role": "user",
      "active": true
    }
  ]
}

Parametr	Typ	Opis
company_name	string	Pełna nazwa firmy z systemu Magico
company_id	int	Unikalny identyfikator firmy w Magico
users	array	Lista wszystkich użytkowników firmy

Struktura użytkownika w tablicy users

Pole	Typ	Opis
name	string	Pełne imię i nazwisko użytkownika
email	string	Adres email użytkownika
global_user_id	int	Globalny ID użytkownika w systemie Magico
username	string	Login użytkownika
role	string	Rola użytkownika (admin, user, etc.)
active	boolean	Status aktywności konta

Odpowiedź sukces (201)

{
  "status": "success",
  "message": "Tenant created successfully with users",
  "tenant_id": "tenant_34_travelmanager",
  "company_id": 34,
  "users_imported": 2,
  "created_at": "2026-02-17T10:30:00Z"
}

Odpowiedź błąd

400 Bad Request - Nieprawidłowe dane

{
  "status": "error",
  "message": "Invalid company data",
  "errors": ["company_id is required", "company_name is required"]
}

409 Conflict - Tenant już istnieje

{
  "status": "error",
  "message": "Tenant already exists for this company",
  "existing_tenant_id": "tenant_34_travelmanager"
}

---

Krok 3: Synchronizacja zmian użytkowników

Kiedy lista użytkowników w systemie Magico ulegnie zmianie (dodanie, usunięcie, edycja użytkownika), system automatycznie wysyła aktualizację do wszystkich połączonych aplikacji, w tym TravelManager.

Endpoint aktualizacji użytkowników

PUT manager.travelmanager.pl/api/tenant/{company_id}/users

Magico.pro wywołuje ten endpoint za każdym razem gdy:

• Dodany zostanie nowy użytkownik do firmy
• Usunięty zostanie użytkownik z firmy
• Zmienione zostaną dane użytkownika (email, rola, status aktywności)
• Zmieniony zostanie status aktywności użytkownika

Nagłówki

Content-Type: application/json
Authorization: Bearer {magico_system_token}

Parametry URL

Parametr	Typ	Opis
company_id	int	ID firmy (np. 34) dla której aktualizujemy użytkowników

Body żądania

{
  "company_id": 34,
  "company_name": "Nazwa Firmy Sp. z o.o.",
  "users": [
    {
      "name": "Jan Kowalski",
      "email": "jan.kowalski@firma.pl",
      "global_user_id": 123,
      "username": "jan.kowalski",
      "role": "admin",
      "active": true
    },
    {
      "name": "Anna Nowak",
      "email": "anna.nowak@firma.pl",
      "global_user_id": 124,
      "username": "anna.nowak",
      "role": "user",
      "active": true
    },
    {
      "name": "Michał Wiśniewski",
      "email": "michal.wisniewski@firma.pl",
      "global_user_id": 125,
      "username": "michal.wisniewski",
      "role": "user",
      "active": true
    }
  ],
  "total_users": 3,
  "updated_at": "2026-02-17T11:45:00Z"
}

Odpowiedź TravelManager (200)

{
  "status": "success",
  "message": "Users synchronized successfully",
  "company_id": 34,
  "users_updated": 3,
  "users_added": 1,
  "users_removed": 0,
  "users_modified": 2,
  "synchronized_at": "2026-02-17T11:45:15Z"
}

---

Krok 4: Zarządzanie użytkownikami w TravelManager

Proces zarządzania

TravelManager otrzymuje pełną listę użytkowników od Magico i:

1. Podczas tworzenia tenanta:

   • Tworzy rekordy wszystkich użytkowników w swoim tenantcie
   • Zapisuje mapowanie między global_user_id (Magico) a lokalnym ID w TravelManager

2. Podczas synchronizacji zmian:

   • Porównuje otrzymaną listę z aktualnym stanem
   • Dodaje nowych użytkowników
   • Usuwa użytkowników nieobecnych na nowej liście
   • Aktualizuje dane zmodyfikowanych użytkowników

Przykładowa struktura w bazie TravelManager

-- Tabela tenantów
CREATE TABLE tenants (
  id VARCHAR(50) PRIMARY KEY,
  company_id INT NOT NULL,
  company_name VARCHAR(255) NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);

-- Tabela użytkowników tenanta
CREATE TABLE tenant_users (
  id INT AUTO_INCREMENT PRIMARY KEY,
  tenant_id VARCHAR(50) NOT NULL,
  global_user_id INT NOT NULL, -- ID z Magico
  local_user_id INT, -- lokalne ID w TravelManager
  name VARCHAR(255) NOT NULL,
  email VARCHAR(255) NOT NULL,
  username VARCHAR(100) NOT NULL,
  role VARCHAR(50),
  active BOOLEAN DEFAULT TRUE,
  synced_at TIMESTAMP DEFAULT NOW(),
  FOREIGN KEY (tenant_id) REFERENCES tenants(id)
);

---

Pełny flow aktywacji

sequenceDiagram
    participant U as Użytkownik/Admin
    participant M as Magico.pro
    participant DB as Magico DB
    participant T as TravelManager

    U->>M: Kliknięcie "Aktywuj TravelManager"
    M->>DB: Pobierz listę użytkowników firmy
    DB->>M: Lista użytkowników
    M->>T: POST /api/tenant (company_name, company_id, users[])
    T->>T: Tworzenie tenanta + import użytkowników
    T->>M: 201 Tenant created with users
    M->>U: Aplikacja aktywowana pomyślnie

Flow synchronizacji zmian

sequenceDiagram
    participant A as Admin/System
    participant M as Magico.pro
    participant DB as Magico DB
    participant T as TravelManager

    A->>M: Dodanie/edycja/usunięcie użytkownika
    M->>DB: Aktualizacja danych użytkownika
    M->>DB: Pobierz aktualną listę użytkowników firmy
    DB->>M: Aktualna lista użytkowników
    M->>T: PUT /api/tenant/{company_id}/users (users[])
    T->>T: Synchronizacja użytkowników
    T->>M: 200 Users synchronized

---

Bezpieczeństwo i tokeny

Tokeny systemowe

• Magico System Token - używany do tworzenia tenantów i synchronizacji użytkowników w TravelManager

Konfiguracja tokenów

Tokeny muszą być skonfigurowane w:

• Magico - endpoint TravelManager dla tworzenia tenantów i synchronizacji użytkowników
• TravelManager - autoryzacja zapytań od systemu Magico

---

Obsługa błędów

Scenariusze błędów

1. Błąd tworzenia tenanta z użytkownikami

   • Logowanie błędu w systemie Magico
   • Informowanie użytkownika o problemie z aktywacją
   • Rollback - brak utworzenia tenanta

2. Błąd synchronizacji użytkowników

   • Logowanie błędu synchronizacji
   • Retry automatyczny po określonym czasie
   • Alert dla administratorów o problemach synchronizacji

3. Problemy z tokenami

   • Sprawdzanie ważności tokena systemowego Magico
   • Procedury odnawiania tokenów

Retry i ponowne próby

• Retry logic dla zapytań synchronizacji użytkowników (maksymalnie 3 próby)
• Timeout dla długotrwałych operacji (30 sekund)
• Kolejka zadań dla operacji synchronizacji w przypadku błędów

---

Logi systemowe

Każda operacja powinna być logowana:

• Aktywacja aplikacji przez użytkownika
• Tworzenie tenanta z użytkownikami
• Synchronizacja zmian użytkowników (dodanie, usunięcie, modyfikacja)
• Błędy i wyjątki