Riferimento API EasyTrack

Tutti gli endpoint che puoi integrare nel tuo sistema o app esterna: autenticazione, tracker, posizioni GPS in tempo reale, veicoli, geofence, assegnazioni agenti, avvisi, report e share-link.

Panoramica

L'API EasyTrack è un'API REST JSON ospitata su Cloudflare (edge, regione UE). Tutte le richieste usano HTTPS. Le risposte sono application/json (eccetto export CSV/PDF). I dati di tracciamento in tempo reale provengono dai tracker Teltonika / FMC e sono disponibili pochi secondi dopo la ricezione da parte del server.

URL di base & formati

https://api.easytrack.ch

Ogni endpoint qui sotto è relativo a questa base. Esempio: GET /devices → https://api.easytrack.ch/devices.

Autenticazione

Quasi tutti gli endpoint richiedono un token Bearer. Il token si ottiene in due passaggi: richiesta di un codice OTP via email, poi verifica del codice. Aggiungi quindi l'header Authorization a ogni richiesta:

Authorization: Bearer <il_tuo_token>
Content-Type: application/json

Prima chiamata

1 · Richiedi un codice

curl -X POST https://api.easytrack.ch/auth/request-code \
  -H "Content-Type: application/json" \
  -d '{"email":"tu@esempio.ch","lang":"it"}'

2 · Verifica il codice e ottieni il token

curl -X POST https://api.easytrack.ch/auth/verify-code \
  -H "Content-Type: application/json" \
  -d '{"email":"tu@esempio.ch","code":"123456"}'
# => { "success": true, "token": "…", "expires_at": "…", "user": { … } }

3 · Elenca i tuoi tracker

curl https://api.easytrack.ch/devices \
  -H "Authorization: Bearer <token>"

In JavaScript (fetch):

const res = await fetch("https://api.easytrack.ch/devices", {
  headers: { Authorization: `Bearer ${token}` }
});
const { devices } = await res.json();

Famiglie di endpoint

Autenticazione — login & sessione

{
  "email": "tu@esempio.ch",
  "lang":  "it"          // opzionale (fr, de, en, it…)
}

{ "success": true, "message": "Codice inviato", "expires_in": 600 }

{ "email": "tu@esempio.ch", "code": "123456" }

{
  "success": true,
  "token": "…",
  "expires_at": "2026-08-01T10:00:00.000Z",
  "user": { "id": 42, "email": "tu@esempio.ch", "role": "client", "two_factor_enabled": false }
}

{ "success": true, "requires_2fa": true, "pending_token": "…" }

{ "pending_token": "…", "code": "654321" }

{ "email": "tu@esempio.ch" }

Autenticazione — 2FA & profilo

Tracker (dispositivi)

Un dispositivo è un tracker GPS identificato dal suo imei. Gli endpoint seguenti restituiscono solo i tracker del tuo account (e quelli condivisi con te).

{
  "success": true,
  "source": "known_devices",
  "devices": [
    {
      "id": 12, "imei": "350612073912345", "name": "Camion 1",
      "status": "online",
      "last_latitude": 46.204, "last_longitude": 6.143,
      "last_speed": 0, "last_heading": 180, "last_battery": 87,
      "last_position_at": "2026-07-11 06:12:33",
      "vehicle_plate": "GE 123456", "vehicle_name": "Furgone",
      "active_agent_name": null, "is_shared": false
    }
  ]
}

{ "imei": "350612073912345", "name": "Camion 1" }   // name opzionale

{
  "name": "Camion 1", "is_active": true,
  "vehicle_plate": "GE 123456", "vehicle_name": "Furgone",
  "vehicle_type": "van", "vehicle_model": "Ford Transit",
  "vehicle_color": "#2563eb", "vehicle_assigned_to": "Marco"
}

Posizioni GPS

{ "success": true, "imei": "…", "page": 0, "page_size": 5000,
  "count": 5000, "has_more": true, "positions": [ … ] }

Campi di una posizione

Veicoli

Scheda veicolo collegata a un tracker (targa, modello, colore, persona assegnata).

Body (POST/PUT)

{
  "plate": "GE 123456", "name": "Furgone",
  "vehicle_type": "van", "vehicle_model": "Ford Transit",
  "color": "#2563eb", "device_id": 12, "assigned_to": "Marco"
}

Geofence

Zone circolari che attivano avvisi all'entrata e/o all'uscita.

Body (POST/PUT)

{
  "name": "Deposito Ginevra",
  "latitude": 46.204, "longitude": 6.143, "radius": 150,
  "type": "vehicle",            // oppure "general"
  "vehicle_id": 12,             // obbligatorio se type = "vehicle"
  "color": "#ef4444",
  "alert_on_enter": true, "alert_on_exit": true,
  "description": "Zona di sosta"
}

Assegnazioni agenti

Gestisci i tuoi agenti (promoter/autisti) e l'attribuzione dei tracker a un agente per una sessione.

Avvisi

Regole di notifica (batteria scarica, eccesso di velocità, entrata/uscita da una zona, ecc.).

Share-link (condivisione pubblica)

Crea link di condivisione temporanei che permettono di seguire determinati tracker senza account.

Report

Report pianificati (PDF) e monitoraggio delle loro esecuzioni.

Notifiche & impostazioni

Condivisione pubblica

{ "success": true, "devices": [ … ], "imeis": ["…"], "expires_at": "…" }

Convenzioni — risposte JSON

Le risposte riuscite riportano generalmente success: true e la risorsa (o un elenco).

{ "success": true, "devices": [ … ] }

Errori

Gli errori restituiscono uno stato HTTP adeguato e un corpo { "error": "message" }.

Paginazione

Gli elenchi di posizioni si limitano tramite limit. L'export dello storico (/positions/export) è paginato in pagine da 5000 punti: itera su page finché has_more è true.

Date & fusi orari

• Token/sessioni usano ISO 8601 UTC (2026-07-11T06:12:33.000Z).
• I timestamp delle posizioni (server_timestamp) usano il formato YYYY-MM-DD HH:MM:SS in UTC.
• I filtri from/to accettano lo stesso formato del campo di destinazione.