EasyTrack API-Referenz

Alle Endpoints, die Sie in Ihr eigenes System oder eine externe App integrieren können: Authentifizierung, Tracker, GPS-Positionen in Echtzeit, Fahrzeuge, Geofences, Agentenzuweisungen, Alarme, Berichte und Share-Links.

Überblick

Die EasyTrack-API ist eine JSON-REST-API, gehostet auf Cloudflare (Edge, Region EU). Alle Anfragen erfolgen über HTTPS. Antworten sind application/json (außer CSV/PDF-Exporte). Echtzeit-Trackingdaten stammen von Teltonika- / FMC-Trackern und sind wenige Sekunden nach dem Servereingang verfügbar.

Basis-URL & Formate

https://api.easytrack.ch

Jeder Endpoint unten ist relativ zu dieser Basis. Beispiel: GET /devices → https://api.easytrack.ch/devices.

Authentifizierung

Fast alle Endpoints benötigen einen Bearer-Token. Sie erhalten den Token in zwei Schritten: OTP-Code per E-Mail anfordern, dann den Code verifizieren. Fügen Sie anschließend den Authorization-Header zu jeder Anfrage hinzu:

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

Erster Aufruf

1 · Code anfordern

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

2 · Code verifizieren und Token erhalten

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

3 · Ihre Tracker auflisten

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();

Endpoint-Familien

Authentifizierung — Login & Session

{
  "email": "sie@beispiel.ch",
  "lang":  "de"          // optional (fr, de, en, it…)
}

{ "success": true, "message": "Code gesendet", "expires_in": 600 }

{ "email": "sie@beispiel.ch", "code": "123456" }

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

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

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

{ "email": "sie@beispiel.ch" }

Authentifizierung — 2FA & Profil

Tracker (Geräte)

Ein Gerät ist ein GPS-Tracker, identifiziert durch seine imei. Die folgenden Endpoints geben nur die Tracker Ihres Kontos zurück (sowie die mit Ihnen geteilten).

{
  "success": true,
  "source": "known_devices",
  "devices": [
    {
      "id": 12, "imei": "350612073912345", "name": "LKW 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": "Transporter",
      "active_agent_name": null, "is_shared": false
    }
  ]
}

{ "imei": "350612073912345", "name": "LKW 1" }   // name optional

{
  "name": "LKW 1", "is_active": true,
  "vehicle_plate": "GE 123456", "vehicle_name": "Transporter",
  "vehicle_type": "van", "vehicle_model": "Ford Transit",
  "vehicle_color": "#2563eb", "vehicle_assigned_to": "Hans"
}

GPS-Positionen

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

Positionsfelder

Fahrzeuge

Mit einem Tracker verknüpfter Fahrzeugdatensatz (Kennzeichen, Modell, Farbe, zugewiesene Person).

Body (POST/PUT)

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

Geofences

Kreisförmige Zonen, die Alarme bei Ein- und/oder Ausfahrt auslösen.

Body (POST/PUT)

{
  "name": "Depot Genf",
  "latitude": 46.204, "longitude": 6.143, "radius": 150,
  "type": "vehicle",            // oder "general"
  "vehicle_id": 12,             // erforderlich wenn type = "vehicle"
  "color": "#ef4444",
  "alert_on_enter": true, "alert_on_exit": true,
  "description": "Parkzone"
}

Agentenzuweisungen

Verwalten Sie Ihre Agenten (Promotoren/Fahrer) und die Zuteilung von Trackern an einen Agenten für eine Session.

Alarme

Benachrichtigungsregeln (niedriger Akku, Geschwindigkeitsüberschreitung, Zonen-Ein-/Ausfahrt usw.).

Share-Links (öffentliches Teilen)

Erstellen Sie temporäre Share-Links, mit denen bestimmte Tracker ohne Konto verfolgt werden können.

Berichte

Geplante Berichte (PDF) und Nachverfolgung ihrer Ausführungen.

Benachrichtigungen & Einstellungen

Öffentliches Teilen

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

Konventionen — JSON-Antworten

Erfolgreiche Antworten enthalten in der Regel success: true und die Ressource (oder eine Liste).

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

Fehler

Fehler geben einen passenden HTTP-Status und einen Body { "error": "message" } zurück.

Paginierung

Positionslisten werden über limit begrenzt. Der Verlaufs-Export (/positions/export) ist in Seiten zu 5000 Punkten paginiert: iterieren Sie über page, solange has_more true ist.

Datum & Zeitzonen

• Tokens/Sessions verwenden ISO 8601 UTC (2026-07-11T06:12:33.000Z).
• Positions-Zeitstempel (server_timestamp) verwenden das Format YYYY-MM-DD HH:MM:SS in UTC.
• Die Filter from/to akzeptieren dasselbe Format wie das Zielfeld.