Référence de l'API EasyTrack

L'ensemble des endpoints que vous pouvez intégrer sur votre propre système ou application externe : authentification, trackers, positions GPS temps réel, véhicules, geofences, affectations d'agents, alertes, rapports et liens de partage.

Vue d'ensemble

L'API EasyTrack est une API REST JSON hébergée sur Cloudflare (edge, région UE). Toutes les requêtes se font en HTTPS. Les réponses sont au format application/json (sauf export CSV/PDF). Les données de suivi temps réel proviennent des trackers Teltonika / FMC et sont accessibles quelques secondes après leur réception serveur.

URL de base & formats

https://api.easytrack.ch

Chaque endpoint ci-dessous est relatif à cette base. Exemple : GET /devices → https://api.easytrack.ch/devices.

Authentification

La quasi-totalité des endpoints nécessitent un jeton Bearer. Le jeton s'obtient en deux étapes : demande d'un code OTP par email, puis vérification du code. Ajoutez ensuite le header Authorization à chaque requête :

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

Premier appel

1 · Demander un code

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

2 · Vérifier le code et récupérer le jeton

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

3 · Lister vos trackers

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

En JavaScript (fetch) :

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

Familles d'endpoints

Authentification — connexion & session

{
  "email": "vous@exemple.ch",
  "lang":  "fr"          // optionnel (fr, de, en, it…)
}

{ "success": true, "message": "Code envoyé", "expires_in": 600 }

{ "email": "vous@exemple.ch", "code": "123456" }

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

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

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

{ "email": "vous@exemple.ch" }

Authentification — 2FA & profil

Trackers (devices)

Un device est un tracker GPS identifié par son imei. Les endpoints ci-dessous ne retournent que les trackers de votre compte (et ceux partagés avec vous).

{
  "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": "Fourgon",
      "active_agent_name": null, "is_shared": false
    }
  ]
}

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

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

Positions GPS

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

Champs d'une position

Véhicules

Fiche véhicule reliée à un tracker (plaque, modèle, couleur, personne assignée).

Body (POST/PUT)

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

Geofences

Zones circulaires déclenchant des alertes à l'entrée et/ou à la sortie.

Body (POST/PUT)

{
  "name": "Dépôt Genève",
  "latitude": 46.204, "longitude": 6.143, "radius": 150,
  "type": "vehicle",            // ou "general"
  "vehicle_id": 12,             // requis si type = "vehicle"
  "color": "#ef4444",
  "alert_on_enter": true, "alert_on_exit": true,
  "description": "Zone de stationnement"
}

Affectations d'agents

Gérez vos agents (promoteurs/chauffeurs) et l'attribution des trackers à un agent pour une session.

Alertes

Règles de notification (batterie faible, survitesse, entrée/sortie de zone, etc.).

Share-links (partage public)

Créez des liens de partage temporaires permettant de suivre certains trackers sans compte.

Rapports

Rapports planifiés (PDF) et suivi de leurs exécutions.

Notifications & réglages

Partage public

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

Géocodage inverse

/geocode?latitude=46.204&longitude=6.143

{ "code": 1, "address": "…", "street": "…", "postal_code": "…", "city": "Genève", "country": "CH" }

Conventions — réponses JSON

Les réponses réussies portent généralement success: true et la ressource (ou une liste).

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

Erreurs

Les erreurs renvoient un statut HTTP adéquat et un corps { "error": "message" }.

Pagination

Les listes de positions se limitent via limit. L'export d'historique (/positions/export) est paginé par pages de 5000 points : itérez sur page tant que has_more est true.

Dates & fuseaux

• Les jetons/sessions utilisent l'ISO 8601 UTC (2026-07-11T06:12:33.000Z).
• Les horodatages de positions (server_timestamp) sont au format YYYY-MM-DD HH:MM:SS en UTC.
• Les filtres from/to acceptent le même format que le champ ciblé.