Guida rapida ControlOne API

Questa guida spiega come autenticarsi e chiamare le API REST di ControlOne, nello stesso stile dei portali documentazione come Frotcom API.

1. URL base

Ambiente	Base URL
Produzione	`https://ctrlone.i4m.it/api`
Documentazione	`https://api.controllone.com`
Locale	`http://localhost:8000/api`

2. Autenticazione (Sanctum Bearer Token)

La maggior parte degli endpoint richiede un token ottenuto con il login.

Login

POST /api/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password",
  "language": "it"
}

Risposta (estratto):

{
  "status": true,
  "token": "1|xxxxxxxxxxxxxxxx",
  "user": { "id": 1, "name": "...", "email": "..." },
  "permissions": { "fleet_view": true, "geofence_view": true, ... }
}

Chiamate autenticate

GET /api/fleet/vehicles
Authorization: Bearer 1|xxxxxxxxxxxxxxxx
Accept: application/json

3. Esempi per area funzionale

Fleet — posizione live

GET /api/fleet/vehicles

Fleet — cronologia giornaliera

POST /api/fleet/vehicles/history
Content-Type: application/json

{
  "imei": "352094123456789",
  "date": "09-06-2026"
}

Geofence — creazione

POST /api/geofences
Content-Type: application/json

{
  "name": "Magazzino",
  "location": "Via Roma 1, Milano",
  "geofence_data": {
    "type": "circle",
    "radius": 500,
    "geofence": { "lat": 45.46, "lng": 9.19 }
  },
  "is_active": true
}

Report — generazione

POST /api/reports/generate

{
  "vehicle_id": 12,
  "report_type": "fuel_consumption",
  "period_type": "daily",
  "start_date": "2026-06-01",
  "end_date": "2026-06-01"
}

4. Endpoint senza autenticazione

Questi endpoint sono usati dal parser Python / dispositivi Teltonika:

POST /api/update-route
POST /api/complete-route
POST /api/log-device-event
POST /api/log-geofence-event
POST /api/save-command-response

Nota: in produzione conviene limitare questi endpoint per IP (solo server parser).

5. Codici di risposta

HTTP	Significato
200 / 201	Operazione riuscita
400	Richiesta non valida
401	Token mancante o non valido
422	Errore di validazione campi
500	Errore interno server

6. Testare dalla documentazione interattiva

Apri API Reference
Vai su Account → Account_Login
Clicca Try it out, inserisci credenziali, esegui
Copia il token dalla risposta
Clicca Authorize in alto e incolla: Bearer {token}
Prova gli altri endpoint protetti

7. Rate limit

Le API Laravel applicano il rate limiting standard (60 req/min per utente autenticato). Per integrazioni ad alto volume contattare l'amministratore.