API Reference
Integra FideliAI nel tuo software
API disponibile nel piano Business
Le API REST di FideliAI ti permettono di integrare la piattaforma loyalty e CRM direttamente nel tuo software gestionale, e-commerce o app personalizzata. Tutte le chiamate utilizzano il formato JSON e richiedono autenticazione tramite API key.
Autenticazione
Tutte le richieste API devono includere la tua API key nell'header Authorization:
Authorization: Bearer YOUR_API_KEY
Puoi generare la tua API key dalla dashboard, nella sezione Impostazioni > Integrazioni.
Base URL
https://api.fideliai.app/v1
Endpoint principali
Elenco clienti
GET /customers
{
"data": [
{
"id": "cust_abc123",
"name": "Marco Rossi",
"email": "marco.rossi@email.com",
"points": 350,
"tier": "gold",
"created_at": "2026-01-15T10:30:00Z"
}
],
"total": 142,
"page": 1,
"per_page": 20
}
Restituisce l'elenco paginato dei tuoi clienti con i rispettivi punti e livello fedeltà.
Registra transazione
POST /transactions
{
"customer_id": "cust_abc123",
"amount": 25.50,
"description": "Acquisto in negozio"
}
{
"id": "txn_xyz789",
"customer_id": "cust_abc123",
"amount": 25.50,
"points_earned": 25,
"total_points": 375,
"created_at": "2026-04-12T14:22:00Z"
}
Registra una nuova transazione e assegna automaticamente i punti fedeltà al cliente in base alle regole configurate.
Elenco premi
GET /rewards
{
"data": [
{
"id": "rew_def456",
"name": "Caffè omaggio",
"points_required": 100,
"active": true,
"redeemed_count": 87
}
],
"total": 5
}
Restituisce l'elenco dei premi configurati con le relative statistiche di riscatto.
Rate limiting
Le API sono soggette a limiti di utilizzo per garantire la stabilità del servizio:
- Piano Business: 1.000 richieste/minuto
- Le risposte includono gli header
X-RateLimit-Remaining e X-RateLimit-Reset
Codici di errore
- 400 — Richiesta non valida. Verifica i parametri inviati.
- 401 — Autenticazione fallita. Controlla la tua API key.
- 403 — Accesso negato. La tua API key non ha i permessi necessari.
- 404 — Risorsa non trovata.
- 429 — Troppe richieste. Hai superato il rate limit.
- 500 — Errore interno del server. Riprova più tardi.
Prossimamente
Coming soon
Stiamo lavorando all'espansione delle nostre API. Le prossime funzionalità includeranno:
- Webhook per eventi in tempo reale (nuova transazione, premio riscattato, nuovo cliente)
- Endpoint per la gestione delle campagne
- SDK ufficiali per JavaScript, Python e PHP
- Ambiente sandbox per i test
Per richiedere l'accesso anticipato alle API o per domande, contattaci a supporto@fidelai.it.