Documentazione Tecnica ANGEL POSTER
Versione API: v1.0 | Ultimo aggiornamento: 17 Agosto 2025
Questa documentazione è destinata a sviluppatori, partner tecnici e per le richieste di approvazione delle API delle piattaforme social media.
1. Panoramica dell'Applicazione
Scopo
ANGEL POSTER è una piattaforma SaaS per la gestione e pubblicazione automatizzata di contenuti multimediali su multiple piattaforme social media.
Target
Content creator, agenzie di marketing, aziende e professionisti che necessitano di gestire la presenza sui social media in modo efficiente.
Piattaforme
YouTube, Facebook, Instagram, TikTok con supporto per pubblicazione programmata e gestione multi-account.
Caratteristiche Principali
- Pubblicazione Multi-Piattaforma: Caricamento simultaneo su più social network
- Programmazione Avanzata: Scheduling con fuso orario personalizzato
- Gestione Multi-Cliente: Supporto per oltre 50 clienti simultanei
- Analisi Performance: Metriche dettagliate e reporting
- Sicurezza Enterprise: Crittografia end-to-end e conformità GDPR
2. Architettura del Sistema
Architettura High-Level
Frontend (Streamlit)
API Gateway
Business Logic
Database Layer
External APIs
Stack Tecnologico
| Componente |
Tecnologia |
Versione |
Scopo |
| Frontend |
Streamlit |
1.28+ |
Interfaccia utente web |
| Backend |
Python |
3.9+ |
Logica applicativa |
| Database |
SQLite/PostgreSQL |
Latest |
Persistenza dati |
| Autenticazione |
OAuth 2.0 |
2.1 |
Sicurezza e autorizzazione |
| File Storage |
Local/Cloud Storage |
- |
Gestione file multimediali |
| Scheduling |
APScheduler |
3.10+ |
Pubblicazione programmata |
Componenti del Sistema
Frontend Layer
- Interfaccia Streamlit responsive
- Gestione sessioni utente
- Upload file multimediali
- Dashboard analytics
Business Logic
- Gestione clienti e credenziali
- Processamento contenuti
- Scheduling e automazione
- Integrazione API esterne
Data Layer
- Gestione utenti e permessi
- Metadati contenuti
- Log attività e audit
- Configurazioni sistema
3. Sicurezza e Conformità
Certificazioni di Sicurezza:
GDPR Compliant
OAuth 2.0
TLS 1.3
AES-256
ISO 27001 Ready
Misure di Sicurezza Implementate
Crittografia e Protezione Dati
- Dati in Transito: TLS 1.3 per tutte le comunicazioni
- Dati a Riposo: Crittografia AES-256 per database e file
- Token e Credenziali: Hashing sicuro con salt personalizzati
- Backup: Crittografia end-to-end per tutti i backup
Controllo Accessi
- Autenticazione Multi-Fattore: Supporto per 2FA/MFA
- Role-Based Access Control (RBAC): Permessi granulari
- Session Management: Timeout automatico e invalidazione
- API Rate Limiting: Protezione contro abusi
Monitoraggio e Audit
- Logging Completo: Tracciamento di tutte le attività
- Rilevamento Anomalie: Monitoraggio comportamenti sospetti
- Audit Trail: Registro immutabile delle operazioni
- Alerting: Notifiche in tempo reale per eventi critici
# Esempio di configurazione sicurezza
SECURITY_CONFIG = {
"encryption": {
"algorithm": "AES-256-GCM",
"key_rotation": "monthly"
},
"authentication": {
"method": "OAuth2",
"mfa_required": True,
"session_timeout": 3600
},
"api_security": {
"rate_limit": "1000/hour",
"cors_enabled": True,
"csrf_protection": True
}
}
4. Integrazione API Social Media
Piattaforme Supportate
YouTube Data API v3
- Upload video fino a 128GB
- Gestione playlist e canali
- Scheduling e privacy settings
- Analytics e metriche
Quota giornaliera: 10,000 unità
Facebook Graph API
- Pubblicazione su pagine e gruppi
- Gestione contenuti multimediali
- Programmazione post
- Insights e statistiche
Rate Limit: 200 chiamate/ora
Instagram Basic Display
- Pubblicazione foto e video
- Gestione Stories
- Hashtag e geolocalizzazione
- Metriche engagement
Rate Limit: 240 chiamate/ora
TikTok for Developers
- Upload video nativi
- Gestione profilo business
- Analytics avanzate
- Trend e hashtag
Rate Limit: 100 chiamate/ora
Flusso di Autenticazione OAuth
Richiesta Autorizzazione
Redirect Provider
Consenso Utente
Callback con Code
Exchange Token
Store Credentials
# Esempio configurazione OAuth per YouTube
YOUTUBE_OAUTH_CONFIG = {
"client_id": "your-client-id.googleusercontent.com",
"client_secret": "your-client-secret",
"redirect_uri": "https://angelposter.com/oauth/callback",
"scope": [
"https://www.googleapis.com/auth/youtube.upload",
"https://www.googleapis.com/auth/youtube.readonly"
],
"access_type": "offline",
"approval_prompt": "force"
}
5. Flusso dei Dati
Processo di Pubblicazione
Upload e Scheduling
Upload File
Validazione
Processamento
Scheduling
Queue Job
Esecuzione Pubblicazione
Trigger Scheduler
Retrieve Content
API Call
Response Handling
Update Status
Gestione Errori e Retry
| Tipo Errore |
Strategia Retry |
Max Tentativi |
Backoff |
| Rate Limit |
Exponential Backoff |
5 |
2^n secondi |
| Network Timeout |
Linear Retry |
3 |
30 secondi |
| Server Error (5xx) |
Exponential Backoff |
3 |
2^n minuti |
| Auth Error |
Token Refresh |
1 |
Immediato |
6. API Endpoints
Nota: Questi endpoint sono per uso interno dell'applicazione. L'accesso esterno richiede autenticazione e autorizzazione appropriate.
Autenticazione
POST
/api/v1/auth/login
Autenticazione utente con credenziali
{
"email": "user@example.com",
"password": "secure_password",
"remember_me": true
}
POST
/api/v1/auth/oauth/connect
Connessione account social media via OAuth
{
"platform": "youtube",
"authorization_code": "auth_code_from_provider",
"redirect_uri": "https://angelposter.com/callback"
}
Gestione Contenuti
POST
/api/v1/content/upload
Upload di file multimediali
// Multipart form data
{
"file": "video.mp4",
"title": "Titolo del video",
"description": "Descrizione del contenuto",
"tags": ["tag1", "tag2"],
"client_id": "client_123"
}
POST
/api/v1/content/schedule
Programmazione pubblicazione
{
"content_id": "content_456",
"platforms": ["youtube", "facebook"],
"scheduled_time": "2025-08-20T15:30:00Z",
"timezone": "Europe/Rome",
"publish_settings": {
"youtube": {
"privacy": "public",
"category": "22"
}
}
}
Analytics e Reporting
GET
/api/v1/analytics/performance
Metriche di performance dei contenuti
// Query parameters
?client_id=client_123&platform=youtube&date_from=2025-08-01&date_to=2025-08-31
// Response
{
"total_views": 15420,
"total_likes": 892,
"total_comments": 156,
"engagement_rate": 6.8,
"top_performing_content": [...]
}
7. Autenticazione e Autorizzazione
Modello di Sicurezza Multi-Livello
Livello Utente
- Autenticazione con email/password
- Supporto 2FA con TOTP
- Gestione sessioni sicure
- Password policy enforced
Livello Cliente
- Isolamento dati per cliente
- Credenziali separate per piattaforma
- Permessi granulari
- Audit trail completo
Livello API
- Token JWT con scadenza
- Refresh token rotation
- Rate limiting per endpoint
- IP whitelisting opzionale
Gestione Token OAuth
| Piattaforma |
Tipo Token |
Durata |
Refresh |
Scope Richiesti |
| YouTube |
OAuth 2.0 |
1 ora |
Automatico |
upload, readonly |
| Facebook |
OAuth 2.0 |
2 mesi |
Manuale |
pages_manage_posts |
| Instagram |
OAuth 2.0 |
1 ora |
Automatico |
user_profile, user_media |
| TikTok |
OAuth 2.0 |
24 ore |
Automatico |
video.upload, user.info.basic |
8. Rate Limiting e Quotas
Limiti Applicazione
| Risorsa |
Limite |
Finestra Temporale |
Comportamento Superamento |
| Upload File |
100 file |
1 ora |
Queue con delay |
| API Calls |
1000 richieste |
1 ora |
HTTP 429 + Retry-After |
| Pubblicazioni |
50 post |
1 giorno |
Scheduling automatico |
| Storage |
10 GB |
Per cliente |
Cleanup automatico |
Gestione Intelligente delle Quote
- Distribuzione Automatica: Bilanciamento delle richieste nel tempo
- Prioritizzazione: Contenuti urgenti hanno precedenza
- Fallback Strategy: Retry automatico in caso di rate limit
- Monitoring: Alerting proattivo per quota in esaurimento
9. Monitoraggio e Logging
Metriche di Sistema
Performance
- Tempo di risposta API
- Throughput pubblicazioni
- Utilizzo risorse sistema
- Latenza upload file
Errori
- Rate di errore per piattaforma
- Fallimenti autenticazione
- Timeout e retry
- Errori di validazione
Business
- Utenti attivi giornalieri
- Contenuti pubblicati
- Engagement medio
- Retention rate
Struttura Log
{
"timestamp": "2025-08-17T10:30:00Z",
"level": "INFO",
"service": "content-publisher",
"client_id": "client_123",
"user_id": "user_456",
"action": "video_upload",
"platform": "youtube",
"content_id": "content_789",
"status": "success",
"duration_ms": 2340,
"metadata": {
"file_size": "125MB",
"video_duration": "00:05:30",
"resolution": "1920x1080"
}
}
10. Conformità e Certificazioni
Conformità Normativa
GDPR (General Data Protection Regulation)
- ✅ Consenso esplicito per il trattamento dati
- ✅ Diritto all'oblio e portabilità dati
- ✅ Privacy by design e by default
- ✅ Data Protection Impact Assessment (DPIA)
- ✅ Nomina Data Protection Officer (DPO)
Conformità API delle Piattaforme
- YouTube: Compliance con YouTube API Terms of Service
- Facebook: Aderenza alle Facebook Platform Policies
- Instagram: Rispetto delle Instagram API Guidelines
- TikTok: Conformità alle TikTok Developer Terms
Certificazioni di Sicurezza
| Standard |
Status |
Scadenza |
Copertura |
| ISO 27001 |
In Preparazione |
2026-08-17 |
Information Security Management |
| SOC 2 Type II |
Pianificato |
2026-12-31 |
Security, Availability, Confidentiality |
| GDPR Compliance |
Attivo |
Permanente |
Data Protection e Privacy |
Audit e Controlli
- Audit Interni: Revisioni trimestrali dei processi di sicurezza
- Penetration Testing: Test annuali da parte di terze parti
- Code Review: Revisione del codice per ogni release
- Vulnerability Scanning: Scansioni automatiche settimanali
Questa documentazione è aggiornata alla versione 1.0 del 17 Agosto 2025.
Per la versione più recente, visitare: docs.angelposter.com