API Abbonamenti

Endpoints per la gestione degli abbonamenti e monitoraggio utilizzo.

Autenticazione

Tutti gli endpoint richiedono autenticazione JWT nel header:

Authorization: Bearer <token>

Endpoint COMPANY_ADMIN

GET /api/companies/me/subscription

Ottiene l'abbonamento della propria azienda.

Risposta:

{
  "success": true,
  "subscription": {
    "id": "uuid",
    "companyId": "uuid",
    "status": "ACTIVE",
    "startDate": "2025-01-01T00:00:00Z",
    "expiresAt": null,
    "tokenResetType": "MONTHLY",
    "monthlyTokenLimit": null,
    "currentMonthTokens": 45000,
    "maxUsers": 10,
    "llmProvider": "OLLAMA_QWEN_32B",
    "enableDocumentSearch": true,
    "enableWebSearch": true,
    "enableChat": true,
    "enableWidget": true,
    "usagePercent": 0.45,
    "isUnlimited": true,
    "daysUntilExpiry": null
  }
}

GET /api/companies/me/usage

Ottiene le statistiche di utilizzo della propria azienda.

Risposta:

{
  "success": true,
  "usage": {
    "currentMonth": {
      "inputTokens": 25000,
      "outputTokens": 20000,
      "totalTokens": 45000,
      "requestCount": 150,
      "byService": {
        "chat": 30000,
        "search": 10000,
        "widget": 5000
      }
    },
    "limit": null,
    "usagePercent": 0,
    "isUnlimited": true,
    "status": "ACTIVE",
    "resetDate": "2025-02-01T00:00:00Z",
    "history": [
      {
        "year": 2025,
        "month": 1,
        "totalTokens": 45000,
        "chatTokens": 30000,
        "searchTokens": 10000,
        "widgetTokens": 5000
      }
    ]
  }
}

Endpoint SYSTEM_ADMIN

GET /api/subscriptions/analytics/dashboard

Statistiche aggregate di tutti gli abbonamenti.

Risposta:

{
  "success": true,
  "stats": {
    "total": 5,
    "byStatus": {
      "trial": 0,
      "active": 5,
      "warning": 0,
      "suspended": 0,
      "expired": 0,
      "cancelled": 0
    },
    "totalTokensThisMonth": 250000,
    "totalTokensAllTime": 1500000,
    "totalRequests": 5000,
    "averageUsagePercent": 0.35
  }
}

GET /api/subscriptions/analytics/top-consumers

Top N aziende per consumo token.

Query Parameters:

Parametro	Tipo	Default	Descrizione
limit	number	10	Numero di risultati

Risposta:

{
  "success": true,
  "consumers": [
    {
      "companyId": "uuid",
      "companyName": "Acme Corp",
      "totalTokens": 80000,
      "usagePercent": 0.80,
      "limit": 100000,
      "status": "WARNING"
    }
  ]
}

GET /api/subscriptions/analytics/warnings

Aziende che hanno superato l'80% del limite.

Risposta:

{
  "success": true,
  "warnings": [
    {
      "companyId": "uuid",
      "companyName": "Acme Corp",
      "currentTokens": 85000,
      "limit": 100000,
      "usagePercent": 0.85,
      "status": "WARNING",
      "daysUntilExpiry": 15
    }
  ]
}

GET /api/subscriptions/analytics/status-distribution

Distribuzione abbonamenti per stato.

Risposta:

{
  "success": true,
  "distribution": [
    {
      "status": "ACTIVE",
      "count": 5,
      "percentage": 100,
      "color": "#22c55e"
    }
  ]
}

GET /api/companies/:companyId/subscription

Ottiene l'abbonamento di una specifica azienda.

Parametri:

Parametro	Tipo	Descrizione
companyId	string	UUID dell'azienda

GET /api/companies/:companyId/usage

Ottiene l'utilizzo di una specifica azienda.

Parametri:

Parametro	Tipo	Descrizione
companyId	string	UUID dell'azienda

Tipi

SubscriptionStatus

type SubscriptionStatus =
  | 'TRIAL'      // Periodo di prova
  | 'ACTIVE'     // Attivo
  | 'WARNING'    // Vicino al limite
  | 'SUSPENDED'  // Sospeso per superamento limite
  | 'EXPIRED'    // Scaduto
  | 'CANCELLED'  // Cancellato

TokenResetType

type TokenResetType =
  | 'MONTHLY'    // Reset mensile
  | 'LIFETIME'   // Mai (token a vita)

LLMProvider

type LLMProvider =
  | 'OLLAMA_QWEN_32B'  // Qwen 2.5 32B (default)

CustomLlmProvider

type CustomLlmProvider =
  | 'OPENAI'     // GPT-4o, o1, gpt-4-turbo
  | 'ANTHROPIC'  // Claude Sonnet 4, Claude 3.5
  | 'GOOGLE'     // Gemini 2.0 Flash, Gemini 1.5 Pro

---

Custom LLM Endpoints

Endpoint per configurare provider AI personalizzati con API key aziendali.

GET /api/subscriptions/custom-llm/providers

Lista provider e modelli disponibili.

Risposta:

{
  "success": true,
  "providers": [
    {
      "id": "OPENAI",
      "name": "OpenAI",
      "models": [
        { "id": "gpt-4o", "name": "GPT-4o", "recommended": true },
        { "id": "gpt-4o-mini", "name": "GPT-4o Mini" },
        { "id": "o1", "name": "O1" },
        { "id": "o1-mini", "name": "O1 Mini" }
      ]
    },
    {
      "id": "ANTHROPIC",
      "name": "Anthropic",
      "models": [
        { "id": "claude-sonnet-4-20250514", "name": "Claude Sonnet 4", "recommended": true },
        { "id": "claude-3-5-sonnet-20241022", "name": "Claude 3.5 Sonnet" }
      ]
    },
    {
      "id": "GOOGLE",
      "name": "Google",
      "models": [
        { "id": "gemini-2.0-flash", "name": "Gemini 2.0 Flash", "recommended": true },
        { "id": "gemini-1.5-pro", "name": "Gemini 1.5 Pro" }
      ]
    }
  ]
}

POST /api/subscriptions/custom-llm/validate

Valida una API key prima di salvarla.

Body:

{
  "provider": "OPENAI",
  "model": "gpt-4o",
  "apiKey": "sk-..."
}

Risposta:

{
  "success": true,
  "valid": true,
  "message": "API key valida"
}

GET /api/companies/me/subscription/custom-llm

Ottiene la configurazione custom LLM della propria azienda.

Ruolo: COMPANY_ADMIN

Risposta:

{
  "success": true,
  "customLlm": {
    "provider": "OPENAI",
    "model": "gpt-4o",
    "apiKeyMasked": "sk-a...xyz1",
    "validatedAt": "2025-12-20T10:00:00Z"
  }
}

PUT /api/companies/me/subscription/custom-llm

Salva la configurazione custom LLM per la propria azienda.

Ruolo: COMPANY_ADMIN

Body:

{
  "provider": "OPENAI",
  "model": "gpt-4o",
  "apiKey": "sk-..."
}

Risposta:

{
  "success": true,
  "message": "Configurazione salvata"
}

DELETE /api/companies/me/subscription/custom-llm

Rimuove la configurazione custom LLM.

Ruolo: COMPANY_ADMIN

Risposta:

{
  "success": true,
  "message": "Configurazione rimossa"
}

GET /api/companies/:companyId/subscription/custom-llm

Ottiene la configurazione custom LLM di una specifica azienda.

Ruolo: SYSTEM_ADMIN

PUT /api/companies/:companyId/subscription/custom-llm

Salva la configurazione custom LLM per una specifica azienda.

Ruolo: SYSTEM_ADMIN

DELETE /api/companies/:companyId/subscription/custom-llm

Rimuove la configurazione custom LLM di una specifica azienda.

Ruolo: SYSTEM_ADMIN

---

Codici Errore

Codice	Descrizione
NOT_FOUND	Abbonamento non trovato
UNAUTHORIZED	Token non valido o mancante
FORBIDDEN	Ruolo non autorizzato