Architettura del Sistema

Backend API

CodeIgniter 4 con API REST complete per la gestione di contenuti SEO, analisi keyword e intelligenza artificiale.

  • API RESTful complete
  • Autenticazione JWT
  • CORS configurato per frontend esterni
  • Integrazione Google Search Console
  • Servizi AI (OpenAI/DeepSeek)
  • Sistema Session ID centralizzato
Frontend React

Applicazione React separata che consuma le API di backend per fornire un'interfaccia utente moderna e reattiva.

  • Frontend React completamente separato
  • Comunicazione via API REST
  • Autenticazione tramite JWT
  • Gestione stato con Context/Redux
  • UI moderna e responsive

Gestione Session ID

Sistema Centralizzato

Quill utilizza un sistema centralizzato per la generazione di session_id tramite il SessionIdGeneratorService.

Formato Session ID

Tutti i session_id seguono il formato unificato:

project_X_type_hash
Esempio:
project_37_editorial_planning_68813089a66e3
Componenti:
  • project - Prefisso fisso
  • X - ID del progetto (numerico)
  • type - Tipo di conversazione (es. editorial_planning, chat, analysis)
  • hash - Hash univoco generato automaticamente

Vantaggi per Frontend

Tracciabilità
  • Identificazione immediata del progetto
  • Tipo di conversazione chiaramente identificabile
  • Supporto per analytics e monitoring
Consistenza
  • Formato unificato in tutta l'applicazione
  • Facilità di parsing lato frontend
  • Compatibilità con sistemi di caching

Utilizzo in JavaScript/React

// Parsing di un session_id
const parseSessionId = (sessionId) => {
  const parts = sessionId.split('_');
  if (parts.length >= 4 && parts[0] === 'project') {
    return {
      projectId: parseInt(parts[1]),
      type: parts[2],
      hash: parts[3]
    };
  }
  return null;
};

// Esempio di utilizzo
const sessionId = 'project_37_editorial_planning_68813089a66e3';
const parsed = parseSessionId(sessionId);
console.log(parsed);
// Output: { projectId: 37, type: 'editorial_planning', hash: '68813089a66e3' }
Importante

I session_id sono generati automaticamente dal backend. Il frontend non deve mai generare session_id manualmente, ma solo utilizzare quelli forniti dalle API.

Documentazione API Quill

Informazioni Generali

Base URL Backend: http://api.testapplication.it:8080/api/v1

Base URL Auth: http://api.testapplication.it:8080/api/auth

Frontend React: http://localhost:5173 (sviluppo)

Formato: JSON

Autenticazione: Bearer Token (JWT)

CORS: Abilitato per domini React configurati

Content-Type: application/json

Le API Quill forniscono accesso completo a tutte le funzionalità della piattaforma per la gestione di contenuti SEO, analisi keyword, piani editoriali e servizi di intelligenza artificiale. Il sistema è progettato per supportare un frontend React completamente separato.

Autenticazione JWT

Tutte le API protette richiedono un token JWT nell'header Authorization:

Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json
Importante per Frontend React
  • Il token JWT ha una validità di 24 ore
  • Memorizza il token in localStorage o sessionStorage
  • Implementa refresh automatico prima della scadenza
  • Gestisci logout automatico in caso di token non valido

Endpoints di Autenticazione

POST /api/auth/login IMPLEMENTATO

Effettua il login e ottiene un token JWT per l'autenticazione API.

Parametri Body (JSON):
{
  "email": "user@example.com",
  "password": "password123"
}
Risposta di Successo:
{
  "success": true,
  "message": "Login effettuato con successo",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "first_name": "Nome",
    "last_name": "Cognome"
  },
  "expires_in": 86400
}

POST /api/auth/register IMPLEMENTATO

Registra un nuovo utente nella piattaforma.

Parametri Body (JSON):
{
  "first_name": "Nome",
  "last_name": "Cognome", 
  "email": "user@example.com",
  "password": "password123"
}
Risposta di Successo:
{
  "success": true,
  "message": "Registrazione completata con successo",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "first_name": "Nome",
    "last_name": "Cognome"
  }
}

GET /api/auth/me IMPLEMENTATO

Ottiene le informazioni dell'utente corrente dal token JWT.

Headers richiesti:
Authorization: Bearer YOUR_JWT_TOKEN
Risposta di Successo:
{
  "success": true,
  "user": {
    "id": 1,
    "email": "user@example.com",
    "first_name": "Nome",
    "last_name": "Cognome",
    "company": null,
    "phone": null,
    "role": "user",
    "is_admin": false,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

POST /api/auth/verify IMPLEMENTATO

Verifica la validità di un token JWT.

Headers richiesti:
Authorization: Bearer YOUR_JWT_TOKEN

POST /api/auth/refresh IMPLEMENTATO

Rinnova un token JWT utilizzando il token corrente.

Gestione Progetti

GET /api/v1/projects IMPLEMENTATO

Ottiene la lista di tutti i progetti dell'utente autenticato.

Risposta di Successo:
{
  "success": true,
  "projects": [
    {
      "id": 1,
      "name": "Il mio sito web",
      "description": "Progetto principale",
      "domain": "https://example.com",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}

POST /api/v1/projects IMPLEMENTATO

Crea un nuovo progetto.

Parametri Body (JSON):
{
  "name": "Nome del progetto",
  "description": "Descrizione del progetto",
  "domain": "https://example.com"
}
Risposta di Successo:
{
  "success": true,
  "message": "Progetto creato con successo",
  "project": {
    "id": 1,
    "name": "Nome del progetto",
    "description": "Descrizione del progetto",
    "domain": "https://example.com",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

GET /api/v1/projects/{id} IMPLEMENTATO

Ottiene i dettagli base di un progetto specifico.

Risposta di Successo:
{
  "success": true,
  "project": {
    "id": 1,
    "name": "Il mio sito web",
    "description": "Progetto principale",
    "domain": "https://example.com",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

PUT /api/v1/projects/{id} IMPLEMENTATO

Aggiorna un progetto esistente.

Parametri Body (JSON):
{
  "name": "Nome aggiornato",
  "description": "Descrizione aggiornata",
  "domain": "https://newdomain.com"
}
Risposta di Successo:
{
  "success": true,
  "message": "Progetto aggiornato con successo",
  "project": {
    "id": 1,
    "name": "Nome aggiornato",
    "description": "Descrizione aggiornata",
    "domain": "https://newdomain.com",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T15:45:00Z"
  }
}

DELETE /api/v1/projects/{id} IMPLEMENTATO

Elimina un progetto e tutti i dati associati.

Risposta di Successo:
{
  "success": true,
  "message": "Progetto eliminato con successo"
}

GET /api/v1/projects/{id}/overview IMPLEMENTATO

Ottiene una panoramica completa del progetto con statistiche principali.

Risposta di Successo:
{
  "success": true,
  "project": {
    "id": 1,
    "name": "Il mio sito web",
    "description": "Progetto principale"
  },
  "domain": {
    "id": 1,
    "domain": "https://example.com"
  },
  "statistics": {
    "keywords_count": 145,
    "urls_count": 23,
    "carts_count": 5,
    "editorial_plans_count": 2,
    "last_sync": "2024-01-15T10:30:00Z",
    "total_impressions": 125000,
    "total_clicks": 8500,
    "average_position": 3.2,
    "average_ctr": 6.8
  }
}

GET /api/v1/projects/{id}/statistics IMPLEMENTATO

Ottiene statistiche dettagliate del progetto con trend degli ultimi 30 giorni.

Risposta di Successo:
{
  "success": true,
  "statistics": {
    "period": {
      "from": "2024-01-01",
      "to": "2024-01-30"
    },
    "keywords": {
      "total": 145,
      "top_10": 23,
      "new_this_month": 12
    },
    "traffic": {
      "total_impressions": 125000,
      "total_clicks": 8500,
      "average_ctr": 6.8,
      "average_position": 3.2
    },
    "trends": {
      "impressions_trend": [1200, 1350, 1180, 1420, 1380, 1520, 1600],
      "clicks_trend": [82, 91, 78, 95, 87, 103, 108],
      "position_trend": [3.4, 3.2, 3.1, 3.0, 2.9, 3.1, 3.2]
    }
  }
}

GET /api/v1/projects/{id}/traffic/range IMPLEMENTATO

Ottiene dati di traffico del progetto per un range di date specifico.

Parametri Query:
  • date_from - Data inizio (formato: YYYY-MM-DD)
  • date_to - Data fine (formato: YYYY-MM-DD)
  • group_by - Raggruppamento: day, week, month (default: day)
Risposta di Successo:
{
  "success": true,
  "period": {
    "from": "2024-01-01",
    "to": "2024-01-30",
    "group_by": "day"
  },
  "data": [
    {
      "date": "2024-01-01",
      "impressions": 1200,
      "clicks": 82,
      "ctr": 6.8,
      "position": 3.2
    }
  ]
}

POST /api/v1/projects/{id}/sync/traffic IMPLEMENTATO

Sincronizza i dati di traffico da Google Search Console per il progetto.

Parametri Body (JSON):
{
  "date_from": "2024-01-01",
  "date_to": "2024-01-30"
}
Risposta di Successo:
{
  "success": true,
  "message": "Sincronizzazione traffico completata",
  "period": {
    "from": "2024-01-01",
    "to": "2024-01-30"
  },
  "synced_records": 156
}

POST /api/v1/projects/{id}/sync/keywords IMPLEMENTATO

Sincronizza le keyword da Google Search Console per il progetto.

Parametri Body (JSON):
{
  "date_from": "2024-01-01",
  "date_to": "2024-01-30"
}
Risposta di Successo:
{
  "success": true,
  "message": "Sincronizzazione keyword completata",
  "period": {
    "from": "2024-01-01",
    "to": "2024-01-30"
  },
  "synced_keywords": 89
}

POST /api/v1/projects/{id}/sync/full IMPLEMENTATO

Esegue una sincronizzazione completa (traffico + keyword) da Google Search Console.

Parametri Body (JSON):
{
  "date_from": "2024-01-01",
  "date_to": "2024-01-30"
}

GET /api/v1/projects/{id}/sync/status IMPLEMENTATO

Verifica lo stato della sincronizzazione con Google Search Console.

Risposta di Successo:
{
  "success": true,
  "sync_status": {
    "google_connected": true,
    "last_sync": "2024-01-15T10:30:00Z",
    "can_sync": true,
    "recommended_sync": false
  }
}

GET /api/v1/projects/{id}/keywords IMPLEMENTATO

Ottiene le keyword del progetto con paginazione e ordinamento.

Parametri Query:
  • page - Numero di pagina (default: 1)
  • limit - Numero di risultati per pagina (default: 50)
  • order_by - Campo di ordinamento (impressions, clicks, position)
  • order_dir - Direzione ordinamento (ASC, DESC)
  • latestOnly - Solo dati più recenti (true/false)

GET /api/v1/projects/{id}/urls IMPLEMENTATO

Ottiene gli URL più visitati del progetto.

POST /api/v1/projects/{id}/ai/suggestions IMPLEMENTATO

Genera suggerimenti AI basati sulle keyword top del progetto.

Risposta di Successo:
{
  "success": true,
  "suggestions": [
    "Come migliorare la SEO del tuo sito web",
    "Guida completa alle keyword per principianti",
    "Strategie di content marketing vincenti"
  ],
  "based_on": {
    "top_keywords": [
      {"keyword": "seo", "impressions": 15000},
      {"keyword": "marketing", "impressions": 12000}
    ],
    "domain": "https://example.com"
  }
}

POST /api/v1/projects/{id}/context-snapshot IMPLEMENTATO

Crea uno snapshot del contesto del progetto analizzando il sito web.

Risposta di Successo:
{
  "success": true,
  "snapshot_id": 123,
  "responses": {
    "mission": "Fornire strumenti SEO avanzati",
    "target_audience": "Webmaster e SEO specialist",
    "content_type": "Blog tecnico e guide SEO"
  },
  "snapshot": {
    "summary": "Sito web specializzato in strumenti SEO...",
    "recommendations": ["Aumentare contenuti tutorial", "Sviluppare case studies"]
  }
}

Traffico e Visite Progetto

GET /api/v1/projects/{id}/traffic IMPLEMENTATO

Sincronizza automaticamente e restituisce il traffico degli ultimi 7 giorni da GSC.

GET /api/v1/projects/{id}/traffic/range IMPLEMENTATO

Ottiene i dati di traffico del progetto per un intervallo di date specifico.

Parametri Query:
  • date_from – Data inizio (YYYY-MM-DD)
  • date_to – Data fine (YYYY-MM-DD)

GET /api/v1/projects/{id}/visits IMPLEMENTATO

Alias di /traffic per ottenere rapidamente i dati di visita.

Keyword Analytics

Informazioni sulle Keyword

Le keyword sono sincronizzate da Google Search Console. Assicurati che il tuo sito sia collegato e che i dati siano stati sincronizzati.

GET /api/v1/projects/{id}/keywords/top IMPLEMENTATO

Ottiene le keyword top per il progetto con dati di impression e click.

GET /api/v1/projects/{id}/keywords/overview IMPLEMENTATO

Ottiene una panoramica delle performance delle keyword nel tempo.

GET /api/v1/projects/{id}/keywords/{keyword}/details IMPLEMENTATO

Ottiene dettagli su una keyword specifica, inclusi trend e performance.

Gestione Carrelli

GET /api/v1/projects/{id}/carts IMPLEMENTATO

Ottiene la lista dei carrelli salvati per il progetto.

POST /api/v1/projects/{id}/carts IMPLEMENTATO

Salva un nuovo carrello con URL e note associate.

Parametri Body (JSON):
{
  "name": "Carrello Invernale",
  "urls": [
    "https://example.com/prodotto1",
    "https://example.com/prodotto2"
  ],
  "notes": "Prodotti in offerta per la campagna invernale"
}

DELETE /api/v1/projects/{id}/carts/{cart_id} IMPLEMENTATO

Elimina un carrello salvato.

Gestione Piani Editoriali

GET /api/v1/projects/{id}/editorial-plans IMPLEMENTATO

Ottiene la lista dei piani editoriali per il progetto.

POST /api/v1/projects/{id}/editorial-plans IMPLEMENTATO

Salva un nuovo piano editoriale con dettagli e keyword associate.

Parametri Body (JSON):
{
  "title": "Piano Editoriale Gennaio",
  "description": "Argomenti e keyword per il mese di gennaio",
  "keywords": [
    "SEO",
    "Marketing",
    "Content Strategy"
  ],
  "schedule": "2024-01-01 to 2024-01-31"
}

GET /api/v1/editorial-plans/{id} IMPLEMENTATO

Ottiene i dettagli di un piano editoriale specifico.

PUT /api/v1/editorial-plans/{id} IMPLEMENTATO

Aggiorna un piano editoriale esistente.

DELETE /api/v1/editorial-plans/{id} IMPLEMENTATO

Elimina un piano editoriale.

POST /api/v1/editorial-plans/{id}/duplicate IMPLEMENTATO

Duplica un piano editoriale esistente.

GET /api/v1/editorial-plans/{id}/export/{format} IMPLEMENTATO

Esporta un piano editoriale in vari formati (PDF, Excel, etc.).

POST /api/v1/editorial-plans/convert-from-carts IMPLEMENTATO

Converte carrelli esistenti in piani editoriali.

POST /api/v1/editorial-plans/articles IMPLEMENTATO

Aggiunge un articolo a un piano editoriale.

PUT /api/v1/editorial-articles/{id} IMPLEMENTATO

Aggiorna un articolo all'interno di un piano editoriale.

DELETE /api/v1/editorial-articles/{id} IMPLEMENTATO

Elimina un articolo da un piano editoriale.

Servizi AI

Chat AI Unificata

POST /api/ai/chat/stream IMPLEMENTATO

Chat AI streaming unificata per traffico e piani editoriali con gestione contesto.

Parametri Body (JSON):
{
  "message": "Crea un piano editoriale per il mio blog di cucina",
  "project_id": 123,
  "context_type": "editorial_plan",
  "conversation_id": "optional-uuid"
}

Piano Editoriale AI

POST /api/ai/editorial-plan/generate IMPLEMENTATO

Genera un nuovo piano editoriale tramite AI.

POST /api/ai/editorial-plan/update IMPLEMENTATO

Aggiorna un piano editoriale esistente tramite conversazione AI o dati manuali.

Modalità Conversazione AI:
{
  "plan_id": 45,
  "project_id": 37,
  "conversation_id": "uuid-conversation",
  "manual_update": false
}
Modalità Aggiornamento Manuale:
{
  "plan_id": 45,
  "project_id": 37,
  "manual_update": true,
  "plan_data": {
    "articles": [
      {
        "title": "Ricette estive facili",
        "purpose": "Attirare traffico estivo",
        "priority": 1,
        "snippet": "Raccolta di ricette fresche per l'estate"
      }
    ],
    "notes": "Piano aggiornato manualmente"
  }
}

GET /api/ai/editorial-plan/current IMPLEMENTATO

Ottiene il piano editoriale corrente per il progetto.

POST /api/ai/editorial-plan/save IMPLEMENTATO

Salva un piano editoriale generato dall'AI.

GET /api/ai/editorial-plan/list IMPLEMENTATO

Ottiene la lista dei piani editoriali per un progetto.

Parametri Query:
  • project_id - ID del progetto (richiesto)

POST /api/ai/editorial-plan/check-version IMPLEMENTATO

Verifica la versione di un piano editoriale.

DELETE /api/ai/editorial-plan/delete IMPLEMENTATO

Elimina un piano editoriale.

POST /api/ai/editorial-plan/transform IMPLEMENTATO

Trasforma un piano editoriale in un formato diverso.

POST /api/ai/editorial-plan/stream IMPLEMENTATO

Genera un piano editoriale tramite streaming AI.

GET /api/ai/editorial-plan/load/{planId} IMPLEMENTATO

Carica un piano editoriale specifico tramite ID.

Suggerimenti e Analisi AI

POST /api/ai/suggest-articles/stream IMPLEMENTATO

Suggerisce articoli tramite streaming AI.

POST /api/ai/extract-keywords/stream IMPLEMENTATO

Estrae keyword da URL tramite streaming AI.

POST /api/ai/extract-title/stream IMPLEMENTATO

Estrae titoli ottimizzati da contenuti tramite streaming AI.

Gestione Contesto

POST /api/ai/context/confirm IMPLEMENTATO

Conferma il cambio di contesto nella conversazione AI.

GET /api/ai/context/current IMPLEMENTATO

Ottiene il contesto corrente della conversazione.

POST /api/ai/intent/detect IMPLEMENTATO

Rileva l'intento dell'utente dal messaggio.

Servizi AI Legacy

POST /api/v1/ai/suggest-articles IMPLEMENTATO

Suggerisce articoli correlati (versione legacy).

POST /api/v1/ai/extract-keywords IMPLEMENTATO

Estrae keyword da contenuti (versione legacy).

POST /api/v1/assistant/chat IMPLEMENTATO

Chat assistant AI (versione legacy).

Monitoraggio e Statistiche AI

GET /api/ai/stats IMPLEMENTATO

Ottiene statistiche di utilizzo dei servizi AI.

Health Check e Status

GET /api/ai/health IMPLEMENTATO

Verifica lo stato di salute dei servizi AI (endpoint pubblico).

GET /api/ai/status IMPLEMENTATO

Ottiene lo status generale dei servizi AI (endpoint pubblico).

GET /api/ai/services IMPLEMENTATO

Lista dei servizi AI disponibili tramite arbiter.

GET /api/ai/models IMPLEMENTATO

Lista dei modelli AI disponibili.

GET /api/ai/arbiter/health IMPLEMENTATO

Health check specifico dell'AI Arbiter.

WebSocket AI (Real-time)

GET /api/websocket/health IMPLEMENTATO

Health check del server WebSocket AI.

GET /api/websocket/status IMPLEMENTATO

Status del server WebSocket AI.

POST /api/websocket/start IMPLEMENTATO

Avvia il server WebSocket (solo per testing/development).

API Legacy AI (Deprecate)

API Legacy

Queste API sono mantenute per compatibilità ma sono deprecate. Si consiglia di utilizzare le nuove API unificate.

POST /api/legacy-ai/deepseek/chat DEPRECATO

Chat con DeepSeek (versione legacy).

GET /api/legacy-ai/deepseek/stream-chat DEPRECATO

Chat streaming con DeepSeek (versione legacy).

POST /api/legacy-ai/deepseek/suggest-articles DEPRECATO

Suggerimenti articoli con DeepSeek (versione legacy).

POST /api/legacy-ai/deepseek/extract-keywords DEPRECATO

Estrazione keyword con DeepSeek (versione legacy).

POST /api/legacy-ai/openai/suggest-articles DEPRECATO

Suggerimenti articoli con OpenAI (versione legacy).

POST /api/legacy-ai/openai/extract-keywords DEPRECATO

Estrazione keyword con OpenAI (versione legacy).

POST /api/legacy-ai/openai/extract-title DEPRECATO

Estrazione titolo con OpenAI (versione legacy).

Gestione Utenti

GET /api/v1/user/profile IMPLEMENTATO

Ottiene il profilo dell'utente corrente.

Headers richiesti:
Authorization: Bearer YOUR_JWT_TOKEN
Risposta di Successo:
{
  "success": true,
  "user": {
    "id": 1,
    "email": "user@example.com",
    "first_name": "Nome",
    "last_name": "Cognome",
    "company": "Azienda",
    "phone": "+39 123 456 7890",
    "role": "user",
    "is_admin": false,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

PUT /api/v1/user/profile IMPLEMENTATO

Aggiorna il profilo dell'utente corrente.

Headers richiesti:
Authorization: Bearer YOUR_JWT_TOKEN
Parametri Body (JSON):
{
  "first_name": "Nuovo Nome",
  "last_name": "Nuovo Cognome",
  "company": "Nuova Azienda",
  "phone": "+39 987 654 3210"
}
Risposta di Successo:
{
  "success": true,
  "message": "Profilo aggiornato con successo",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "first_name": "Nuovo Nome",
    "last_name": "Nuovo Cognome",
    "company": "Nuova Azienda",
    "phone": "+39 987 654 3210",
    "role": "user",
    "is_admin": false,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T15:45:00Z"
  }
}

Keyword Analytics

GET /api/v1/keyword-analytics/search IMPLEMENTATO

Ricerca e analisi di keyword specifiche.

GET /api/v1/keyword-analytics/suggestions IMPLEMENTATO

Ottiene suggerimenti di keyword correlate.

GET /api/v1/keyword-analytics/correlations IMPLEMENTATO

Analizza le correlazioni tra keyword.

POST /api/v1/keyword-analytics/batch IMPLEMENTATO

Elaborazione batch di multiple keyword.

Analisi SEO

POST /api/v1/seo/analyze-page IMPLEMENTATO

Analizza una pagina web per ottimizzazioni SEO.

Parametri Body (JSON):
{
  "url": "https://example.com/page",
  "target_keywords": ["keyword1", "keyword2"],
  "analysis_depth": "full"
}
Risposta di Successo:
{
  "success": true,
  "seo_score": 85,
  "recommendations": [
    "Ottimizzare il title tag",
    "Aggiungere meta description",
    "Migliorare la struttura H1-H6"
  ],
  "technical_issues": [],
  "content_analysis": {
    "word_count": 1200,
    "keyword_density": 2.5,
    "readability_score": 78
  }
}

Gestione Carrelli

GET /api/v1/carts IMPLEMENTATO

Ottiene la lista dei carrelli dell'utente.

POST /api/v1/carts IMPLEMENTATO

Crea un nuovo carrello.

Parametri Body (JSON):
{
  "name": "Carrello Keyword Gennaio",
  "description": "Raccolta keyword per campagna gennaio",
  "project_id": 123
}

GET /api/v1/carts/{id} IMPLEMENTATO

Ottiene i dettagli di un carrello specifico.

PUT /api/v1/carts/{id} IMPLEMENTATO

Aggiorna un carrello esistente.

DELETE /api/v1/carts/{id} IMPLEMENTATO

Elimina un carrello.

POST /api/v1/carts/{id}/items IMPLEMENTATO

Aggiunge elementi al carrello.

DELETE /api/v1/carts/items/{item_id} IMPLEMENTATO

Rimuove un elemento dal carrello.

Sincronizzazione Dati

Sincronizzazione Progetti

POST /api/v1/projects/{id}/sync/traffic IMPLEMENTATO

Sincronizza i dati di traffico da Google Search Console per il progetto.

POST /api/v1/projects/{id}/sync/keywords IMPLEMENTATO

Sincronizza le keyword da Google Search Console per il progetto.

POST /api/v1/projects/{id}/sync/full IMPLEMENTATO

Sincronizzazione completa di tutti i dati per il progetto.

GET /api/v1/projects/{id}/sync/status IMPLEMENTATO

Verifica lo stato della sincronizzazione per il progetto.

Risposta di Successo:
{
  "project_id": 123,
  "last_sync": "2024-01-15T10:30:00Z",
  "sync_status": "completed",
  "next_sync": "2024-01-16T10:30:00Z",
  "sync_progress": {
    "traffic": "completed",
    "keywords": "in_progress",
    "urls": "pending"
  }
}

Sincronizzazione Globale

POST /api/v1/sync/all-projects IMPLEMENTATO

Sincronizza tutti i progetti dell'utente.

Google Search Console Data

GET /api/v1/gsc/top-urls IMPLEMENTATO

Ottiene le URL con maggior traffico da GSC.

GET /api/v1/gsc/url-data IMPLEMENTATO

Ottiene dati dettagliati per una URL specifica da GSC.

POST /api/v1/gsc/import-sites IMPLEMENTATO

Importa siti da Google Search Console.

Integrazione Google Search Console

GET /api/auth/google/init IMPLEMENTATO

Genera l'URL di autorizzazione OAuth 2.0 per collegare Google Search Console.

Risposta di Successo:
{
  "success": true,
  "auth_url": "https://accounts.google.com/o/oauth2/auth?client_id=..."
}
Utilizzo in React:
const connectGoogle = async () => {
  const response = await fetch('/api/auth/google/init', {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  const data = await response.json();
  if (data.success) {
    window.location.href = data.auth_url;
  }
};

GET /api/auth/google/status IMPLEMENTATO

Verifica lo stato della connessione con Google Search Console.

Risposta di Successo:
{
  "connected": true,
  "email": "user@example.com",
  "last_sync": "2024-01-15T10:30:00Z"
}

GET /api/v1/google/sites IMPLEMENTATO

Ottiene l'elenco dei siti disponibili in Google Search Console con i relativi permessi utente.

Risposta di Successo:
[
  {
    "siteUrl": "https://example.com/",
    "exists": false,
    "permissionLevel": "siteOwner",
    "permissionDescription": "Proprietario",
    "capabilities": {
      "canView": true,
      "canExport": true,
      "canManage": true,
      "canAddUsers": true,
      "canDelete": true
    }
  }
]

POST /api/v1/google/disconnect IMPLEMENTATO

Disconnette l'account Google Search Console dall'utente corrente.

Risposta di Successo:
{
  "success": true,
  "message": "Account Google disconnesso con successo"
}
Utilizzo in React:
const disconnectGoogle = async () => {
  try {
    const response = await apiClient.post('/google/disconnect');
    if (response.data.success) {
      setGoogleConnected(false);
      toast.success('Account Google disconnesso');
    }
  } catch (error) {
    toast.error('Errore durante la disconnessione');
  }
};

POST /api/v1/google/reconnect IMPLEMENTATO

Avvia il processo di ricollegamento dell'account Google con nuova autorizzazione.

Risposta di Successo:
{
  "success": true,
  "message": "Ricollegamento avviato",
  "auth_url": "https://accounts.google.com/o/oauth2/auth?client_id=...",
  "redirect_required": true
}
Utilizzo in React:
const reconnectGoogle = async () => {
  try {
    const response = await apiClient.post('/google/reconnect');
    if (response.data.success && response.data.auth_url) {
      window.location.href = response.data.auth_url;
    }
  } catch (error) {
    toast.error('Errore durante il ricollegamento');
  }
};

GET /api/v1/google/connection-status IMPLEMENTATO

Verifica se l'utente ha bisogno di ricollegarsi (token scaduto/invalido).

Risposta di Successo (Token Valido):
{
  "success": true,
  "connected": true,
  "message": "Account Google collegato e funzionante"
}
Risposta (Token Scaduto):
{
  "success": true,
  "connected": false,
  "needs_reconnection": true,
  "message": "Token scaduto, ricollegamento necessario"
}

GET /api/v1/google/connection-info IMPLEMENTATO

Ottiene informazioni dettagliate sulla connessione Google.

Risposta di Successo:
{
  "success": true,
  "connection_info": {
    "connected": true,
    "connected_at": "2024-01-15T09:30:00Z",
    "last_updated": "2024-01-15T10:30:00Z",
    "token_id": 123,
    "sites_count": 5,
    "sites": [
      {
        "url": "https://example.com",
        "permission": "siteOwner"
      }
    ]
  }
}
Componente React per Gestione Google
// components/GoogleIntegration.jsx
import { useState, useEffect } from 'react';
import apiClient from '../api/client';

const GoogleIntegration = () => {
  const [status, setStatus] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    checkGoogleStatus();
  }, []);

  const checkGoogleStatus = async () => {
    try {
      const response = await apiClient.get('/google/connection-status');
      setStatus(response.data);
    } catch (error) {
      console.error('Error checking Google status:', error);
    } finally {
      setLoading(false);
    }
  };

  const connectGoogle = async () => {
    try {
      const response = await apiClient.get('/google/init');
      if (response.data.success) {
        window.location.href = response.data.auth_url;
      }
    } catch (error) {
      console.error('Error connecting Google:', error);
    }
  };

  const disconnectGoogle = async () => {
    if (confirm('Sei sicuro di voler disconnettere Google Search Console?')) {
      try {
        await apiClient.post('/google/disconnect');
        setStatus({ connected: false });
      } catch (error) {
        console.error('Error disconnecting Google:', error);
      }
    }
  };

  const reconnectGoogle = async () => {
    try {
      const response = await apiClient.post('/google/reconnect');
      if (response.data.auth_url) {
        window.location.href = response.data.auth_url;
      }
    } catch (error) {
      console.error('Error reconnecting Google:', error);
    }
  };

  if (loading) return 
Loading...
;

  return (
    

      
Google Search Console

      
      {status?.connected ? (
        

          

            
            Account Google collegato
          

          
          {status.needs_reconnection && (
            

              
              Il token è scaduto. È necessario ricollegarsi.
              
            

          )}
          
          
        

      ) : (
        

          

            
            Collega Google Search Console per accedere ai dati SEO
          

          
          
        

      )}
    

  );
};

export default GoogleIntegration;

API Dati Google Search Console

Note Importanti
  • Tutte le API richiedono un account Google collegato
  • I dati sono disponibili con un ritardo di 1-3 giorni
  • Limiti di rate API di Google si applicano
  • Le sincronizzazioni automatiche evitano richieste ridondanti

GET /api/v1/gsc/top-urls IMPLEMENTATO

Ottiene gli URL più visitati per un progetto con sincronizzazione automatica da GSC.

Parametri Query:
  • project_id - ID del progetto (richiesto)
  • start_date - Data inizio (YYYY-MM-DD)
  • end_date - Data fine (YYYY-MM-DD)
Risposta di Successo:
{
  "success": true,
  "topUrls": [
    {
      "url": "https://example.com/article-seo",
      "clicks": 1250,
      "impressions": 18500,
      "ctr": 6.76,
      "position": 3.2
    },
    {
      "url": "https://example.com/guide-marketing",
      "clicks": 890,
      "impressions": 12400,
      "ctr": 7.18,
      "position": 2.8
    }
  ]
}

GET /api/v1/gsc/url-visits-history IMPLEMENTATO

Ottiene lo storico delle visite per un URL specifico negli ultimi 30 giorni.

Parametri Query:
  • url - URL completo da analizzare (richiesto)
Risposta di Successo:
{
  "success": true,
  "data": {
    "labels": ["01/12", "02/12", "03/12", "04/12", "05/12"],
    "visits": [45, 52, 38, 67, 59]
  }
}

GET /api/v1/gsc/all-source-data IMPLEMENTATO

Ottiene dati combinati da tutte le fonti Google (Web, Discover, News) per un dominio.

Parametri Query:
  • domain_url - URL del dominio (richiesto)
  • start_date - Data inizio (YYYY-MM-DD)
  • end_date - Data fine (YYYY-MM-DD)
Risposta di Successo:
{
  "success": true,
  "data": [
    {
      "date": "2024-01-15",
      "web": {
        "clicks": 1250,
        "impressions": 18500,
        "ctr": 6.76,
        "position": 3.2
      },
      "discover": {
        "clicks": 45,
        "impressions": 2300,
        "ctr": 1.96,
        "position": 15.2
      },
      "news": {
        "clicks": 12,
        "impressions": 890,
        "ctr": 1.35,
        "position": 8.7
      }
    }
  ]
}

POST /api/v1/gsc/sync-all-projects IMPLEMENTATO

Sincronizza i dati di tutti i progetti dell'utente da Google Search Console.

Risposta di Successo:
{
  "success": true,
  "report": {
    "https://example.com": {
      "success": true,
      "message": "Dati sincronizzati con successo",
      "synced_keywords": 156
    },
    "https://blog.example.com": {
      "success": true,
      "message": "Dati sincronizzati con successo", 
      "synced_keywords": 89
    }
  }
}

POST /api/v1/gsc/sync-project/{project_id} IMPLEMENTATO

Sincronizza solo le keyword per un progetto specifico.

Risposta di Successo:
{
  "success": true,
  "message": "Dati sincronizzati con successo",
  "synced_keywords": 156
}

POST /api/v1/gsc/full-sync/{project_id} IMPLEMENTATO

Esegue una sincronizzazione completa (keywords + URL + visite) per un progetto.

Risposta di Successo:
{
  "success": true,
  "message": "Sincronizzazione completa completata",
  "keyword_sync": {
    "success": true,
    "synced_keywords": 156
  },
  "url_sync": {
    "success": true,
    "urls_processed": 23,
    "visits_inserted": 450
  }
}

POST /api/v1/gsc/import-sites IMPLEMENTATO

Importa la lista dei siti da Google Search Console.

Risposta di Successo:
{
  "success": true,
  "sites": [
    {
      "siteUrl": "sc-domain:example.com",
      "permissionLevel": "siteOwner"
    },
    {
      "siteUrl": "https://example.com/",
      "permissionLevel": "siteFullUser"
    }
  ]
}

GET /api/v1/gsc/test-classes IMPLEMENTATO

Endpoint di debug per testare le classi Google disponibili nel sistema.

Risposta di Successo:
{
  "available_classes": [
    "Google\\Service\\SearchConsole",
    "Google\\Service\\SearchConsole\\SearchAnalyticsQueryRequest"
  ],
  "composer_packages": {
    "google/apiclient": "^2.15.0"
  }
}
Hook React per Gestione Dati GSC
// hooks/useGoogleData.js
import { useState, useEffect } from 'react';
import apiClient from '../api/client';

export const useGoogleData = (projectId) => {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  const syncProject = async (type = 'keywords') => {
    setLoading(true);
    setError(null);
    
    try {
      const endpoint = type === 'full' 
        ? `/gsc/full-sync/${projectId}`
        : `/gsc/sync-project/${projectId}`;
        
      const response = await apiClient.post(endpoint);
      return response.data;
    } catch (err) {
      setError(err.response?.data?.message || 'Errore durante la sincronizzazione');
      throw err;
    } finally {
      setLoading(false);
    }
  };

  const getTopUrls = async (startDate, endDate) => {
    setLoading(true);
    setError(null);
    
    try {
      const response = await apiClient.get('/gsc/top-urls', {
        params: { project_id: projectId, start_date: startDate, end_date: endDate }
      });
      return response.data;
    } catch (err) {
      setError(err.response?.data?.message || 'Errore nel recupero degli URL');
      throw err;
    } finally {
      setLoading(false);
    }
  };

  const getUrlHistory = async (url) => {
    setLoading(true);
    setError(null);
    
    try {
      const response = await apiClient.get('/gsc/url-visits-history', {
        params: { url }
      });
      return response.data;
    } catch (err) {
      setError(err.response?.data?.message || 'Errore nel recupero dello storico');
      throw err;
    } finally {
      setLoading(false);
    }
  };

  return {
    loading,
    error,
    syncProject,
    getTopUrls,
    getUrlHistory
  };
};

Gestione Utenti

GET /api/v1/user/profile IMPLEMENTATO

Ottiene il profilo dell'utente corrente con statistiche.

PUT /api/v1/user/profile IMPLEMENTATO

Aggiorna le informazioni del profilo (nome, azienda, telefono).

Setup CORS

Il backend supporta CORS per i domini React configurati; nelle chiamate:

OPTIONS /api/v1/... HTTP/1.1
Origin: http://localhost:5173
Access-Control-Request-Method: POST

Esempio axios config:

import axios from 'axios';
const apiClient = axios.create({
  baseURL: API_BASE_URL,
  headers: {'Content-Type': 'application/json'},
  withCredentials: false,
});

Codici di Errore

Codice HTTP Significato Descrizione Gestione in React
200 OK Richiesta completata con successo Procedi con i dati ricevuti
400 Bad Request Parametri della richiesta non validi Mostra errori di validazione all'utente
401 Unauthorized Token di autenticazione mancante o non valido Redirect al login, rimuovi token
403 Forbidden Accesso negato alla risorsa richiesta Mostra messaggio "Accesso negato"
404 Not Found Risorsa non trovata Mostra pagina "Non trovato"
500 Internal Server Error Errore interno del server Mostra messaggio generico di errore
Formato Risposta di Errore Standard:
{
  "success": false,
  "message": "Descrizione dell'errore leggibile",
  "errors": {
    "campo": "Dettaglio errore specifico per il campo"
  }
}
Gestione Errori Globale in React:
// src/utils/errorHandler.js
export const handleApiError = (error, setError) => {
  if (error.response) {
    const { status, data } = error.response;
    
    switch (status) {
      case 400:
        setError(data.message || 'Dati inseriti non validi');
        break;
      case 401:
        localStorage.removeItem('auth_token');
        window.location.href = '/login';
        break;
      case 403:
        setError('Non hai i permessi per questa operazione');
        break;
      case 404:
        setError('Risorsa non trovata');
        break;
      case 500:
        setError('Errore interno del server. Riprova più tardi.');
        break;
      default:
        setError(data.message || 'Si è verificato un errore');
    }
  } else if (error.request) {
    setError('Impossibile contattare il server. Verifica la connessione.');
  } else {
    setError('Si è verificato un errore inaspettato');
  }
};

Stato Implementazione API

API Completamente Implementate per Frontend React
✅ Funzionalità Core
  • • Autenticazione JWT completa
  • • Gestione Progetti CRUD
  • • Keyword Analytics
  • • Google Search Console Integration
  • • Disconnessione/Ricollegamento Google
  • • API Dati GSC Complete
  • • Gestione Utenti e Profili
  • • Sistema CORS configurato
🔧 Caratteristiche Tecniche
  • • Headers CORS corretti
  • • Validazione dati lato server
  • • Gestione errori strutturata
  • • Paginazione e ordinamento
  • • Logging completo
  • • Sicurezza API implementata
  • • Sincronizzazione intelligente
  • • Rate limiting gestito
API Google Search Console
🔗 Connessione
  • • OAuth 2.0 completo
  • • Gestione automatica token
  • • Disconnessione sicura
  • • Ricollegamento rapido
  • • Controllo stato real-time
📊 Dati e Sincronizzazione
  • • Sincronizzazione keyword
  • • Tracking URL e visite
  • • Dati Web, Discover, News
  • • Storico visite per URL
  • • Import automatico siti
Prossimi Sviluppi
  • Implementazione Carrelli e Piani Editoriali API
  • Servizi AI per suggerimenti automatici
  • Sistema di notifiche real-time
  • Analytics avanzate con grafici
  • Export/Import dati completo
  • Gestione team e collaboratori
Novità Implementate
  • Gestione Google migliorata: Disconnessione e ricollegamento con un click
  • API Dati GSC complete: 10+ endpoint per dati Search Console
  • Sincronizzazione intelligente: Auto-sync solo quando necessario
  • Debugging tools: Endpoint per testare configurazione Google
  • Multi-source data: Web, Discover e News in un'unica API
  • URL Analytics: Storico visite per singoli URL