⚙️

SalesSentry

Manuale Admin — Guida API Completa

VERSIONE 9.0 · MARZO 2026 · SOLO ADMIN

📑 Indice

Introduzione
Autenticazione API
Gestione Licenze
Gestione Account
Campagne Email
AI & Generazione Contenuti
Lead Management
Integrazioni (Gmail/CRM)
Analytics & Report
Password Manager
Troubleshooting

1️⃣ Introduzione

🎯 A chi è rivolto questo manuale
Questo manuale è destinato agli amministratori di sistema che devono gestire SalesSentry via API. Include tutti gli endpoint disponibili con esempi pratici di utilizzo.

Base URL

https://salessentry.app/api/v1

Format Risposta

Tutte le API ritornano JSON:

{
  "status": "success",
  "data": { ... },
  "message": "Operation completed"
}

Codici HTTP

Codice	Significato	Descrizione
200	OK	Richiesta completata con successo
201	Created	Risorsa creata con successo
400	Bad Request	Parametri mancanti o non validi
401	Unauthorized	API key mancante o non valida
403	Forbidden	Permessi insufficienti
404	Not Found	Risorsa non trovata
429	Too Many Requests	Rate limit superato
500	Internal Server Error	Errore server

2️⃣ Autenticazione API

Tutte le chiamate API richiedono autenticazione tramite API Key nell'header.

⚠️ Attenzione
La tua API key è ADMIN_API_KEY e ha accesso completo al sistema. Non condividerla mai e ruotala regolarmente.

Dove trovare l'API Key:

Dashboard Admin → Settings → API
Oppure file .env sul server: ADMIN_API_KEY

Uso dell'API Key

curl -X GET https://salessentry.app/api/v1/licenses/list \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY"

✅ Best Practice
• Salva API key in variabile ambiente
• Usa HTTPS sempre (mai HTTP)
• Ruota API key ogni 90 giorni
• Log tutti gli accessi API
• Limita IP autorizzati (se possibile)

3️⃣ Gestione Licenze

Le licenze controllano l'accesso dei clienti a SalesSentry. Ogni agenzia/cliente ha una licenza univoca.

POST /licenses/create

Descrizione:

Crea nuova licenza per un cliente.

Body Request:

{
  "company_name": "Digital Agency SRL",
  "email": "admin@digitalagency.it",
  "tier": "PRO",  // PRO o ENTERPRISE
  "max_emails": 10000,
  "max_campaigns": 50,
  "features": {
    "sentiment_analysis": true,
    "genetic_algorithm": true,
    "market_intelligence": true,
    "api_access": true
  },
  "expiry_days": 365
}

Response:

{
  "license_key": "SS-PRO-2026-ABC123",
  "tier": "PRO",
  "status": "active",
  "expires_at": "2027-03-05"
}

GET /licenses/list

Query Parameters:

Parametro	Tipo	Descrizione
status	string	active, expired, suspended
tier	string	PRO, ENTERPRISE
limit	integer	Numero risultati (default: 50)

curl -X GET "https://salessentry.app/api/v1/licenses/list?status=active&tier=PRO" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /licenses/verify/{license_key}

Response:

{
  "valid": true,
  "company_name": "Digital Agency SRL",
  "tier": "PRO",
  "expires_at": "2027-03-05",
  "usage": {
    "emails_sent": 3542,
    "emails_remaining": 6458
  }
}

POST /licenses/{license_key}/suspend

Body:

{ "reason": "Mancato pagamento" }

⚠️ Nota Importante
Quando sospendi una licenza, il cliente NON può più inviare email. Tutti i dati rimangono salvati e accessibili dopo riattivazione.

4️⃣ Gestione Account

Ogni licenza può avere più account utente (admin, manager, user).

POST /accounts/create

Body:

{
  "email": "mario@digitalagency.it",
  "password": "SecurePass123!",
  "name": "Mario Rossi",
  "role": "admin",  // admin, manager, user
  "license_key": "SS-PRO-2026-ABC123",
  "send_welcome_email": true
}

Permessi per Ruolo:

Ruolo	Permessi
admin	Accesso completo, gestione utenti, billing
manager	Gestione campagne, visualizza report, no billing
user	Solo visualizzazione campagne assegnate

POST /accounts/{email}/reset-password

Response:

{
  "message": "Reset email sent",
  "expires_at": "2026-03-05T11:00:00Z"
}

5️⃣ Campagne Email

POST /campaigns/create

Body Completo:

{
  "name": "Q1 2026 - Lancio Prodotto",
  "type": "cold_outreach",  // cold_outreach, nurture, promotional
  "target_audience": {
    "filters": {
      "industry": ["Technology", "Marketing"],
      "company_size": {"min": 10, "max": 500},
      "job_title": ["CEO", "CMO", "Marketing Manager"]
    }
  },
  "schedule": {
    "start_date": "2026-03-10",
    "send_time": "09:00",
    "timezone": "Europe/Rome",
    "frequency": "daily",
    "max_per_day": 100
  },
  "ab_test": {
    "enabled": true,
    "variants": 3,
    "duration_hours": 24
  }
}

GET /campaigns/{campaign_id}/stats

Response:

{
  "campaign_id": "camp_abc123",
  "status": "active",
  "stats": {
    "sent": 487, "delivered": 485,
    "opened": 218, "clicked": 58
  },
  "metrics": {
    "open_rate": 44.9, "click_rate": 11.9
  },
  "leads": { "hot": 8, "warm": 15, "cold": 35 }
}

6️⃣ AI & Generazione Contenuti

POST /ai/generate-email

Descrizione:

Genera email personalizzata con GPT-4.

Body:

{
  "context": {
    "product": "SaaS CRM Cloud",
    "target_audience": "Marketing Managers PMI",
    "value_proposition": "Aumenta conversioni 40%",
    "cta": "Prenota demo gratuita"
  },
  "recipient": { "name": "Mario Rossi", "company": "Tech Solutions SRL" },
  "tone": "professionale_amichevole",
  "length": "medio",  // corto, medio, lungo
  "language": "it"
}

Response:

{
  "subject": "Mario, 3 modi per raddoppiare le conversioni",
  "body": "Ciao Mario,\n\nHo notato che Tech Solutions...",
  "predicted_performance": { "open_rate": 45, "click_rate": 12 }
}

POST /ai/sentiment-analysis

Body:

{ "text": "Grazie per la proposta, molto interessante! Possiamo organizzare una call?" }

Response:

{
  "sentiment": "positive",
  "score": 0.89,
  "intent": "meeting_request",
  "recommended_action": "call_within_24h"
}

7️⃣ Lead Management

GET /leads/{email}/score

Response:

{
  "lead_score": 85,
  "category": "HOT",  // HOT, WARM, COLD
  "factors": { "email_opens": 5, "email_clicks": 3 },
  "recommended_action": "call_immediately",
  "confidence": 0.92
}

GET /leads/hot

Query Parameters:

Parametro	Descrizione
campaign_id	Filtra per campagna specifica
min_score	Score minimo (default: 80)
limit	Numero risultati (default: 50)

Response:

{
  "total": 8,
  "leads": [
    {
      "email": "mario.rossi@techsolutions.it",
      "name": "Mario Rossi",
      "company": "Tech Solutions SRL",
      "score": 92,
      "recommended_action": "call_now"
    }
  ]
}

💡 Best Practice Lead Management
• Controlla lead HOT ogni mattina alle 9:00
• Chiama entro 2 ore dalla notifica
• Aggiorna CRM dopo ogni contatto
• Usa sentiment analysis per priorità

8️⃣ Integrazioni

Gmail Integration

POST /integrations/gmail/setup

Body:

{
  "client_id": "123456.apps.googleusercontent.com",
  "client_secret": "GOCSPX-xxxxxxxxxxxx",
  "redirect_uri": "https://salessentry.app/oauth/gmail"
}

HubSpot Integration

POST /integrations/hubspot/setup

Body:

{
  "api_key": "hubspot_api_key_here",
  "sync_contacts": true,
  "sync_deals": true
}

9️⃣ Analytics & Report

GET /analytics/dashboard

Query Parameters:

Parametro	Descrizione
period	today, week, month, year
license_key	Filtra per cliente

Response:

{
  "period": "month",
  "emails_sent": 45789,
  "open_rate": 42.3,
  "click_rate": 11.8,
  "hot_leads_generated": 234,
  "revenue_generated": 125000
}

POST /analytics/export

Body:

{
  "format": "pdf",  // pdf, csv, excel
  "period": { "from": "2026-03-01", "to": "2026-03-31" },
  "sections": ["overview", "campaigns", "leads", "roi"]
}

🔐 Password Manager

ℹ️ Novità HV9.0
Sistema completo gestione password con 2FA, alert email, blocco IP e reset via email.

POST /password/verify

Body:

{
  "password": "admin2026",
  "role": "admin"  // admin, investor, agency
}

Response (se 2FA attivo):

{
  "valid": true,
  "requires_2fa": true,
  "phone_last_digits": "8663",
  "message": "SMS code sent"
}

GET /password/settings

Response:

{
  "twofa_admin_enabled": false,
  "twofa_admin_phone": "+393463778663",
  "alert_enabled": true,
  "max_failed_attempts": 3,
  "lockout_duration_minutes": 30
}

GET /password/logs

Descrizione:

Visualizza log accessi (ultimi 100).

Response:

[
  {
    "timestamp": "2026-03-05T10:15:23Z",
    "role": "admin",
    "ip_address": "192.168.1.100",
    "success": true,
    "twofa_verified": false
  }
]

🔧 Troubleshooting

Errore 401 - Unauthorized

Problema: API key non valida o mancante

Soluzione:
• Verifica header: Authorization: Bearer YOUR_KEY
• Controlla API key in .env
• Verifica scadenza API key

Errore 429 - Rate Limit

Problema: Troppe richieste in poco tempo

Soluzione:
• Limite: 100 req/min per endpoint
• Usa exponential backoff
• Batch requests quando possibile

Email finiscono in SPAM

Soluzioni:
• Verifica SPF/DKIM/DMARC del dominio
• Warm-up: inizia con 10-20 email/giorno
• Evita spam trigger words
• Personalizza ogni email
• Chiedi whitelist a contatti chiave

Basso Open Rate (<30%)

Soluzioni:
• A/B test subject lines
• Ottimizza timing (9-11 AM migliore)
• Pulizia lista (rimuovi inattivi 90gg)
• Segmentazione più precisa
• Usa personalizzazione nome/azienda nel subject