idmagicodocs/COMPANY_MAGICO_APP_MANAGMENT.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 dwóch głównych kroków:

1. Aktywacja aplikacji – użytkownik/admin włącza TravelManager w panelu Magico
2. Tworzenie tenanta – automatyczne utworzenie środowiska dla firmy w TravelManager
3. Synchronizacja użytkowników – pobranie listy użytkowników firmy z Magico do TravelManager

---

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 wykonuje automatycznie POST do TravelManager API w celu utworzenia nowego tenanta.

---

Krok 2: Tworzenie tenanta w TravelManager

Endpoint tworzenia tenanta

POST manager.travelmanager.pl/api/tenant

System Magico automatycznie wywołuje ten endpoint po aktywacji aplikacji.

Nagłówki

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

Body żądania (minimalne/przykładowe)

{
  "company_name": "Nazwa Firmy Sp. z o.o.",
  "company_id": 34
}

Parametr	Typ	Opis
company_name	string	Pełna nazwa firmy z systemu Magico
company_id	int	Unikalny identyfikator firmy w Magico

Odpowiedź sukces (201)

{
  "status": "success",
  "message": "Tenant created successfully",
  "tenant_id": "tenant_34_travelmanager",
  "company_id": 34,
  "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 użytkowników z Magico

Po utworzeniu tenanta, TravelManager automatycznie pobiera listę użytkowników firmy z systemu Magico.

Endpoint pobierania użytkowników

GET company.magico.pro/api/company/{company_id}/users

TravelManager wykonuje to zapytanie używając tokena systemowego.

Nagłówki

Authorization: Bearer {travelmanager_system_token}
Accept: application/json

Parametry URL

Parametr	Typ	Opis
company_id	int	ID firmy (np. 34) z kroku tworzenia tenanta

Przykładowe zapytanie

GET https://company.magico.pro/api/company/34/users
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
Accept: application/json

Odpowiedź Magico API (200)

{
  "status": "success",
  "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
    }
  ],
  "total_users": 2
}

Struktura użytkownika

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

---

Krok 4: Tworzenie powiązań użytkowników w TravelManager

Proces powiązywania

Po otrzymaniu listy użytkowników z Magico, TravelManager:

1. Tworzy rekordy użytkowników w swoim tenantcie
2. Zapisuje mapowanie między global_user_id (Magico) a lokalnym ID w TravelManager
3. Umożliwia powiązanie użytkowników między systemem Magico a TravelManager

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 T as TravelManager
    participant C as Company.Magico.pro

    U->>M: Kliknięcie "Aktywuj TravelManager"
    M->>T: POST /api/tenant (company_name, company_id)
    T->>T: Tworzenie tenanta w bazie
    T->>M: 201 Tenant created
    T->>C: GET /api/company/{id}/users
    C->>T: Lista użytkowników firmy
    T->>T: Tworzenie powiązań użytkowników
    M->>U: Aplikacja aktywowana pomyślnie

---

Bezpieczeństwo i tokeny

Tokeny systemowe

• Magico System Token - używany do tworzenia tenantów w TravelManager
• TravelManager System Token - używany do pobierania użytkowników z Magico

Konfiguracja tokenów

Tokeny muszą być skonfigurowane w:

• Magico - endpoint TravelManager dla tworzenia tenantów
• TravelManager - endpoint Magico dla pobierania użytkowników
• Company.Magico.pro - autoryzacja zapytań od TravelManager

---

Obsługa błędów

Scenariusze błędów

1. Błąd tworzenia tenanta

   • Logowanie błędu w systemie Magico
   • Informowanie użytkownika o problemie z aktywacją

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

   • Tenant zostaje utworzony, ale bez użytkowników
   • Możliwość ponownej synchronizacji

3. Problemy z tokenami

   • Sprawdzanie ważności tokenów systemowych
   • Procedury odnawiania tokenów

Retry i ponowne próby

• Retry logic dla zapytań HTTP
• Timeout dla długotrwałych operacji
• Kolejka zadań dla operacji asynchronicznych

---

Logi systemowe

Każda operacja powinna być logowana:

• Aktywacja aplikacji przez użytkownika
• Tworzenie tenanta
• Pobieranie użytkowników
• Błędy i wyjątki