Groupe	Préfixe	Description
/tracking	GPS Tracking	Réception des positions, historique, dernière position
/push	Push	Clés VAPID, abonnements, envoi de notifications
/public	Public	Flotte publique, info réseau (auth : clé API association)
/widget	Widget	Script JS de suivi intégrable sur n'importe quel site
/overlays	Overlays	Données Open Data ferroviaires (proxy interne)
/health	Santé	État du serveur et de la base de données

Type	Header / Param	Utilisé par
api_key appareil	Header X-API-Key ou body api_key	Applications GPS (Traccar, BGeo) pour envoyer des positions
Bearer (association)	Header Authorization: Bearer CLE ou ?key=CLE	API publique — récupérer la flotte/réseau d'une association
X-Internal-Secret	Header X-Internal-Secret: SECRET	Serveur PHP uniquement (push/notify, relais internes)
Public (aucune auth)	—	Lecture des positions live/historique via le slug public

Accepte trois formats de body JSON :

Format Background Geolocation (BGeo)

{
  "device_id": "RH-XXXXXXXX",
  "api_key":   "votre_cle_api_appareil",
  "location": {
    "coords": {
      "latitude":  48.8566,
      "longitude": 2.3522,
      "speed":     13.8,    // m/s — -1 si indisponible
      "heading":   90.0,
      "altitude":  35.0,
      "accuracy":  4.2
    },
    "battery": { "level": 0.87, "is_charging": false },
    "is_moving": true,
    "odometer": 12345.6
  }
}

Format plat

{
  "device_id": "RH-XXXXXXXX",
  "api_key":   "votre_cle_api_appareil",
  "lat":       48.8566,
  "lon":       2.3522,
  "speed":     45.5,     // km/h
  "altitude":  35.0,
  "accuracy":  4.2
}

Réponse : {"ok": true} — La position est diffusée en temps réel via Socket.IO (room track:ACCESS_SLUG).

:slug est l'access_slug du véhicule ou le delegate_slug d'une délégation.

{
  "slug":       "abc123",
  "lat":        48.8566,
  "lon":        2.3522,
  "speed":      45.5,
  "heading":    90,
  "altitude":   35,
  "battery":    87,
  "accuracy":   4.2,
  "is_moving":  true,
  "is_charging": false,
  "ts":         "2026-04-29T10:30:00.000Z"
}

Paramètre	Description
limit	Nombre de points (défaut: 200, max: 1000)	optionnel
date	Filtrer sur un jour précis — format YYYY-MM-DD. Renvoie tous les points dans l'ordre chronologique (pas de LIMIT).	optionnel

Retourne un tableau JSON de positions. Sans date : ordre DESC + LIMIT. Avec date : ordre ASC, toute la journée.

Connexion et abonnement

// Script Socket.IO disponible sur l'API elle-même
const socket = io('https://api.rail-horizon.com');

// S'abonner au slug d'un véhicule
socket.emit('subscribe', 'abc123');

// Recevoir les positions en temps réel
socket.on('position', (data) => {
  console.log(data.lat, data.lon, data.speed);
  // data.slug, data.lat, data.lon, data.speed, data.heading,
  // data.altitude, data.battery, data.accuracy,
  // data.is_moving, data.is_charging, data.ts
});

// Se désabonner
socket.emit('unsubscribe', 'abc123');

Chaque véhicule émet dans la room track:ACCESS_SLUG à chaque nouvelle position reçue.

Format de l'URL à configurer dans Traccar Client :

https://api.rail-horizon.com/tracking?id={deviceId}&lat={lat}&lon={lon}&speed={speed}&bearing={heading}&altitude={altitude}&batt={battery}

Paramètre	Description
id	Identifiant unique de l'appareil (unique_id ex: RH-35DB4223) ou delegate_unique_id d'une délégation	requis
lat	Latitude décimale	requis
lon	Longitude décimale	requis
speed	Vitesse en nœuds (×1.852 = km/h)	optionnel
bearing	Cap en degrés (0–360)	optionnel
altitude	Altitude en mètres	optionnel
batt	Niveau batterie (0–100)	optionnel

Paramètres recommandés dans Traccar Client

Frequency	10–30 secondes selon la vitesse du véhicule
Distance	50–100 mètres
Accuracy	High (GPS)

Retourne la clé publique VAPID nécessaire pour créer un abonnement push côté navigateur.

{ "publicKey": "BGxxxxxx..." }

{
  "subscription": {
    "endpoint": "https://fcm.googleapis.com/...",
    "keys": { "p256dh": "...", "auth": "..." }
  }
}

Utiliser l'objet retourné par serviceWorkerRegistration.pushManager.subscribe().

{ "endpoint": "https://fcm.googleapis.com/..." }

{
  "site_id": 42,
  "title":   "Nouvelle position",
  "body":    "Le train est en gare de Lyon.",
  "url":     "https://www.rail-horizon.com/track/abc123",
  "icon":    "https://..."   // optionnel
}

Deux formes d'authentification acceptées :

// Via header
Authorization: Bearer VotreCleApiAssociation

// Via query param
GET /public/fleet?key=VotreCleApiAssociation

Réponse

[
  {
    "id":           1,
    "name":         "BB 26000",
    "vehicle_type": "locomotive",
    "access_slug":  "abc123",
    "is_online":    true,
    "last_lat":     48.8566,
    "last_lon":     2.3522,
    "last_speed":   145.0,
    "last_seen":    "2026-04-29T10:30:00.000Z"
  }
]

Retourne les infos de l'association et ses véhicules actifs. Le :slug est visible dans l'URL rail-horizon.com/reseau/:slug.

{
  "id":          1,
  "name":        "Association AAPSL",
  "description": "...",
  "logo_url":    "https://...",
  "vehicles": [
    { "name": "BB 26000", "access_slug": "abc123", "is_online": true, ... }
  ]
}

// Réponse OK (200)
{ "status": "ok", "ts": "2026-04-29T10:30:00.000Z" }

// Réponse erreur BDD (503)
{ "status": "db_error", "error": "..." }

Valeur	Description
locomotive	Locomotive (BB, CC, BB…)
automotrice	Automotrice (TGV, Intercités, Transilien…)
autorail	Autorail (X 73500, AGC…)
tram	Tramway
bus	Bus / Car
voiture	Voiture remorquée
bateau	Bateau / ferry
autre	Autre (défaut)