Il microservizio Creditsafe History Gateway funge da middleware di intermediazione tra i sistemi aziendali interni e i server di Creditsafe, consentendo l'ottimizzazione del plafond licenze tramite il caching automatico dello storico delle interrogazioni.
Consente di ottenere un token JWT stateless valido per 60 minuti da utilizzare per autorizzare le chiamate successive.
/api/auth/login
{
"username": "admin",
"password": "password_sicura"
}{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"user": {
"username": "admin",
"role": "admin"
}
1b. Cambio Password
Consente all'utente loggato tramite sessione JWT di aggiornare la propria password di accesso.
POST
/api/auth/change-password
Headers di Autorizzazione (Obbligatorio):
Authorization: Bearer [JWT_TOKEN]
Richiesta JSON Body:
{
"old_password": "password_attuale",
"new_password": "nuova_password_sicura"
}
Risposta JSON (HTTP 200 OK):
{
"message": "Password aggiornata con successo."
}
2. Recupero Report Aziendale
Esegue la consultazione del database storico interno. Se presente ed entro il limite di validità (CACHE_TTL_DAYS, predefinito a 365 giorni), restituisce i dati locali senza effettuare una chiamata a pagamento verso Creditsafe. In caso di cache miss, scarica automaticamente il report, aggiorna la cache e l'audit log.
GET
/api/company/report
Parametri Query:
vat_number (Obbligatorio): Partita IVA o numero di registrazione dell'azienda (caratteri alfanumerici).country (Opzionale, default: IT): Codice ISO a 2 lettere della nazione di riferimento.template (Opzionale, default: full): Tipologia di report desiderata. Valori supportati:
full (Tutte le informazioni comprese bilanci, soci, pregiudizievoli e protesti).summary (Anagrafica sintetica, score e limite di credito).financial (Dati di bilancio storici ed anagrafica).score (Solo classe di rischio, score locale e limite di credito).onboardingnoscore (Dati anagrafici e di gruppo senza indicatori di rischio).
Headers di Autorizzazione (Fornire almeno uno dei due):
Authorization: Bearer [JWT_TOKEN]
oppure:
X-Api-Key: [API_KEY]
Risposta JSON (HTTP 200 OK):
{
"source": "CACHE_HIT",
"data": {
"companySummary": {
"businessName": "ACME Anti-Gravity Technologies S.p.A.",
"vatNo": "07589380968",
...
},
"creditScore": { ... }
},
"pdf": "JVBERi0xLjQKMSAwIG9...", // Stringa Base64 del PDF del report (se disponibile)
"updated_at": "2026-07-10 14:15:30"
}
2b. Recupero Report Aziendale Sintetico
Restituisce una versione condensata e normalizzata del report societario, contenente esclusivamente le informazioni anagrafiche principali, il punteggio di rischio, una sintesi dell'ultimo bilancio disponibile e le eventuali note/commenti negativi.
GET
/api/company/report/simplified
Parametri Query:
vat_number (Obbligatorio): Partita IVA o numero di registrazione dell'azienda (caratteri alfanumerici).country (Opzionale, default: IT): Codice ISO a 2 lettere della nazione di riferimento.template (Opzionale, default: full): Tipologia di report desiderata da interrogare. Valori supportati: anag, financial, full.
Headers di Autorizzazione (Fornire almeno uno dei due):
Authorization: Bearer [JWT_TOKEN]
oppure:
X-Api-Key: [API_KEY]
Risposta JSON (HTTP 200 OK):
{
"source": "CACHE_HIT",
"data": {
"ragione_sociale": "ELETTROMECCANICA FORTIN DI FORTIN MORENO & C. S.N.C.",
"partita_iva": "01655510285",
"codice_fiscale": "01655510285",
"stato": "Active",
"indirizzo": {
"via": "VIA ELISEA 13",
"citta": "BATTAGLIA TERME",
"cap": "35041",
"provincia": "PD",
"nazione": "IT"
},
"natura_giuridica": "SOCIETA' IN NOME COLLETTIVO",
"settore_attivita": "Fabbricazione di motori, generatori e trasformatori elettrici",
"punteggio_credito": {
"valore": "1",
"classe": "D",
"descrizione": "Rischio Alto",
"limite_credito": 0,
"valuta_limite": "EUR"
},
"dati_finanziari_sintetici": {
"anno": "2025",
"fatturato": 12500000,
"utile_netto": 1800000,
"ebitda": 2400000,
"patrimonio_netto": 8500000
},
"note_commenti": [
{
"testo": "Il punteggio di rischio di questa società è diminuito da 2 a 1.",
"tipo": "Negative"
}
]
},
"updated_at": "2026-07-13 09:02:27"
}
3. Visualizzazione Audit Logs
Restituisce lo storico degli ultimi 100 accessi eseguiti tramite il gateway. Riservato agli utenti con ruolo admin.
GET
/api/admin/audit-logs
Headers di Autorizzazione (Richiesto ruolo admin):
Authorization: Bearer [ADMIN_JWT_TOKEN]
Risposta JSON (HTTP 200 OK):
{
"audit_logs": [
{
"id": 12,
"event_type": "CACHE_HIT",
"vat_number": "07589380968",
"country": "IT",
"template": "full",
"client_identity": "apikey:client_test",
"response_time_ms": 3,
"created_at": "2026-07-10 14:28:10"
},
...
]
}
3b. Consumo e Addebito Costi
Restituisce il riepilogo aggregato del numero di nuove richieste fatturabili (chiamate live a Creditsafe di tipo CACHE_MISS_LIVE) e delle richieste totali effettuate da ciascun client (identificato da API Key o da utente JWT), raggruppate per tipologia di template di report. Supporta il filtro mensile tramite parametro query.
GET
/api/admin/usage?month=YYYY-MM
Parametri Query:
month (opzionale): Il mese di riferimento in formato YYYY-MM (es. 2026-07). Se non specificato, restituisce i dati per il mese corrente.
Headers di Autorizzazione (Richiesto ruolo admin):
Authorization: Bearer [ADMIN_JWT_TOKEN]
Risposta JSON (HTTP 200 OK):
{
"month": "2026-07",
"usage": [
{
"client_identity": "apikey:client_test",
"template": "full",
"paid_requests": 3,
"total_requests": 10,
"unit_cost": 6.00,
"total_cost": 18.00
},
{
"client_identity": "username:admin",
"template": "financial",
"paid_requests": 1,
"total_requests": 1,
"unit_cost": 1.50,
"total_cost": 1.50
}
]
}
3c. Configurazione Tariffe Personalizzate
Consente di definire e visualizzare i costi unitari addebitabili per ciascun client (API Key o utente JWT) e per ogni tipologia di report (template). Riservato agli utenti con ruolo admin.
GET
/api/admin/rates
Restituisce l'elenco di tutte le tariffe personalizzate configurate a database.
Risposta JSON (HTTP 200 OK):
{
"rates": [
{
"client_identity": "apikey:client_test",
"template": "full",
"unit_cost": 6.00
}
]
}
POST
/api/admin/rates
Crea o aggiorna (upsert) la tariffa unitaria addebitabile ad un client specifico per una tipologia di report.
Richiesta JSON Body:
{
"client_identity": "apikey:client_test",
"template": "full",
"unit_cost": 8.50
}
Risposta JSON (HTTP 200 OK):
{
"message": "Tariffa configurata correttamente.",
"client_identity": "apikey:client_test",
"template": "full",
"unit_cost": 8.50
}
4. Statistiche Cache e Plafond
Restituisce il riepilogo globale delle interrogazioni (cache hit vs miss) e il conteggio aggiornato dei crediti plafond consumati per ciascun tipo di dataset rispetto ai limiti contrattuali (configurati via .env).
GET
/api/admin/stats
Headers di Autorizzazione (Richiesto utente autenticato):
Authorization: Bearer [JWT_TOKEN]
Risposta JSON (HTTP 200 OK):
{
"hits": 14,
"misses": 5,
"fallbacks": 1,
"limits": {
"anag": {
"used": 2,
"limit": 5000
},
"financial": {
"used": 1,
"limit": 200
},
"full": {
"used": 2,
"limit": 30
}
}
}
5. Generazione API Key Client
Consente agli amministratori di generare nuove API Key sicure da configurare all'interno degli applicativi client per consentire l'interrogazione automatizzata del gateway. La chiave viene memorizzata a DB tramite hashing SHA-256 e mostrata in chiaro esclusivamente in fase di creazione.
POST
/api/admin/api-keys
Richiesta JSON Body:
{
"client_name": "ERP-TeamSystem",
"role": "user"
}
Risposta JSON (HTTP 201 Created):
{
"message": "API Key generata correttamente. Salvala ora, non sarà più possibile visualizzarla.",
"client_name": "ERP-TeamSystem",
"api_key": "cs_key_8f12a9b34c0d12e...",
"role": "user"
}
5b. Gestione Utenti
Consente agli amministratori di recuperare l'elenco degli utenti o di registrare nuove credenziali d'accesso.
GET
/api/admin/users
Risposta JSON (HTTP 200 OK):
{
"users": [
{
"id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
"username": "admin",
"role": "admin",
"created_at": "2026-07-10 12:00:00"
},
{
"id": "f8e7d6c5-b4a3-2f1e-0d9c-8b7a6f5e4d3c",
"username": "mario.rossi",
"role": "user",
"created_at": "2026-07-13 18:00:00"
}
]
}
POST
/api/admin/users
Richiesta JSON Body:
{
"username": "mario.rossi",
"password": "password_sicura_123",
"role": "user"
}
Risposta JSON (HTTP 201 Created):
{
"message": "Utente creato correttamente.",
"username": "mario.rossi",
"role": "user"
}
6. Gestione degli Errori e Cache
Le risposte di errore seguono la convenzione descritta nel file di specifica:
Stato HTTP
Errore JSON
Causa
400 Bad Request{"error": "Bad Request", ...}Parametri di ricerca mancanti o non formattati correttamente (es. vat_number speciale).
401 Unauthorized{"error": "Unauthorized", ...}JWT Token o API Key mancante, non valida o scaduta.
403 Forbidden{"error": "Forbidden", ...}Chiamata ad endpoint amministrativi con privilegi non sufficienti.
404 Not Found{"error": "Not Found", ...}Azienda non censita o non trovata all'interno del DB globale Creditsafe.
502 Bad Gateway{"error": "Bad Gateway", ...}Creditsafe non è raggiungibile o ha risposto con errore, e non sono presenti dati storici per il fallback.
Algoritmo di Caching:
- Verifica se a database esiste una tupla che corrisponde a
vat_number, country e template.
- Se la differenza in giorni tra l'ultimo aggiornamento (
updated_at) e la data corrente è inferiore a CACHE_TTL_DAYS, restituisce il record memorizzato e registra l'evento CACHE_HIT (costo Creditsafe: 0).
- In caso di record scaduto o non presente:
- Interroga Creditsafe live.
- Salva/Aggiorna il report JSON nel database (la colonna `pdf_data` è stata rimossa per ridurre lo spazio occupato dal DB, ma il PDF viene comunque scaricato live e restituito in formato Base64 nella risposta corrente).
- Tutti i record a database (compresi log e chiavi API) utilizzano identificativi univoci **UUID** (`VARCHAR(36)`) autogenerati per garantire robustezza e scalabilità.
- Registra l'evento
CACHE_MISS_LIVE.
- Se Creditsafe non è raggiungibile ed esiste una copia cache scaduta a DB, il gateway restituisce quest'ultima con un avviso (
CACHE_FALLBACK_EXPIRED) per garantire la continuità aziendale.