API · Horizon Dispatch

Öffentliche API ohne Schlüssel

Am einfachsten: kein Schlüssel, kein Boost, für alle VTC. Ersetze ma-vtc durch die Kennung deiner VTC (die Adresse ihrer Seite /vtcs/ma-vtc). JSON, nur lesend, offenes CORS, 120 Anfragen / Minute / IP.

GET https://hdispatch.eu/api/vtc                       Liste der verfügbaren Endpoints
GET https://hdispatch.eu/api/vtc/ma-vtc/stats          Mitglieder, online, km (gesamt und Monat), nächstes Event, Zertifizierung
GET https://hdispatch.eu/api/vtc/ma-vtc/online         Online-Fahrer (inklusive Positionen)
GET https://hdispatch.eu/api/vtc/ma-vtc/jobs?limit=10  letzte Lieferungen (1 bis 50, standardmäßig 10)
GET https://hdispatch.eu/api/vtc/ma-vtc/events?limit=5 nächste öffentliche Events (1 bis 20, standardmäßig 5)
GET https://hdispatch.eu/api/vtc/ma-vtc/members        aktive Mitglieder nach Kilometern sortiert (1 bis 200, standardmäßig 50), sofern die VTC sie öffentlich macht
GET https://hdispatch.eu/api/vtc/ma-vtc/certification  überprüfbarer Zertifizierungsstatus

fetch('https://hdispatch.eu/api/vtc/ma-vtc/stats')
  .then((r) => r.json())
  .then((d) => console.log(d.members.online + ' en ligne · ' + d.month.km + ' km ce mois-ci'));

Berücksichtigt die Einstellungen der VTC: Namen ausgeblendet, wenn „Mitglieder anzeigen“ aus ist, keine Einnahmen, wenn diese nicht öffentlich sind, API in Einstellungen → API komplett abschaltbar. Antworten werden 5 Sekunden (online) bis 5 Minuten (Zertifizierung) zwischengespeichert. Fehler: 404 {"error":"not_found"}, wenn die VTC nicht existiert, auf der Blacklist steht oder ihre API abgeschaltet hat; 429 {"success":false,"message":…} bei Überschreiten des Limits. Für detaillierte Daten nutze die v1-API mit Schlüssel unten.

Widgets für die Website deiner VTC

Online-Mitglieder, letzte Fahrten, Kilometer des Monats, nächstes Event, Rekrutierung, komplette Karte oder Live-Minikarte. Kostenlos, in 9 Sprachen, helles oder dunkles Theme. Die Codes zum Einfügen findest du unter Dashboard → deine VTC → Widgets & Badge.

<div class="hd-widget" data-vtc="ma-vtc" data-type="online"></div>
<script src="https://hdispatch.eu/widgets/embed.js" async></script>

data-type

online · jobs · km · event · recruit · card · map

data-theme

dark · light · auto

data-lang

fr en de es it nl pl pt tr

Weitere

data-accent="ff8800" · data-limit="1..15" · data-header="0" · data-height="360" · data-game="ats" (Karte)

Ohne JavaScript funktioniert jedes Widget auch als iframe: https://hdispatch.eu/widgets/vtc/ma-vtc/online?theme=dark. Die Widgets aktualisieren sich selbst (30 s für „online“, bis zu 10 Min. für „Rekrutierung“) und zeigen einen Fehler an, wenn die VTC ihre API abgeschaltet hat. Zertifizierungs-Badge: https://hdispatch.eu/badges/vtc/ma-vtc.svg (oder .png), Optionen ?style=flat, ?theme=light, ?lang=en, überprüfbar unter https://hdispatch.eu/verify/ma-vtc.

Schnellstart

Schalte die API frei — sie gehört zur Stufe 5 Boosts (wie die VTC-Website).
Hol dir deinen öffentlichen Schlüssel unter Dashboard → Einstellungen → API. Er beginnt mit pk_ und kann gefahrlos offengelegt werden.
Rufe die API auf mit deinem Schlüssel im Header x-api-key (oder als Parameter ?key=).

curl -H "x-api-key: pk_VOTRE_CLE" https://hdispatch.eu/api/v1/vtc

Authentifizierung & Regeln

Basis-URL

https://hdispatch.eu/api/v1

Header

x-api-key: pk_…

Methoden

GET (nur lesend)

Ratenlimit

120 Anfragen / Minute / Schlüssel

Format

JSON · CORS *

Zugang

Stufe 5 Boosts erforderlich

GET https://hdispatch.eu/api/v1 liefert die Liste der Endpoints. Fehler haben die Form {"error":"…"} (siehe unten).

⚠️ Verwechsle deinen öffentlichen Schlüssel (pk_…, lesen) nicht mit deinem Tracker-Schlüssel (geheim, schreiben): Letzterer darf niemals auf einer Webseite erscheinen. Eine VTC kann ihre API abschalten oder bestimmte Felder (Einnahmen, Mitglieder) in ihren Einstellungen ausblenden.

GET /api/v1/vtc

Infos und Gesamtwerte der VTC (Mitglieder, km, Erstellungsdatum…).

Beispielantwort

{
  "id": "6600…", "name": "Horizon Dispatch", "slug": "horizon-dispatch",
  "tag": "[HDX]", "description": "…", "game": "ets2", "color": "#cfd4dc",
  "recruitmentOpen": true, "hdPartner": false, "premium": false,
  "memberCount": 42,
  "totals": { "distanceKm": 1284000, "deliveries": 3120, "revenue": 9800000 },
  "createdAt": "2025-01-08T12:00:00.000Z"
}

GET /api/v1/members?limit=1..500

Mitglieder der VTC, nach Kilometerstand sortiert (standardmäßig 100).

Beispielantwort

{
  "count": 42,
  "members": [
    { "discordId": "1234…", "name": "Marco", "avatar": "…", "role": "driver",
      "traction": false, "joinedAt": "…",
      "stats": { "distanceKm": 84210, "deliveries": 190, "revenue": 512000 } }
  ]
}

GET /api/v1/events

Kommende Events der VTC, öffentlich wie nur für Mitglieder (max. 50).

Beispielantwort

{
  "count": 2,
  "events": [
    { "id": "…", "title": "Convoi du dimanche", "game": "ets2", "server": "Simulation 1",
      "departureCity": "Paris", "arrivalCity": "Berlin", "plannedKm": 1050,
      "meetupAt": "…", "startAt": "…", "slots": { "total": 20, "taken": 12 },
      "going": 18, "externalUrl": "" }
  ]
}

GET /api/v1/deliveries?limit=1..200

Aktuelle Lieferungen (standardmäßig 50).

Beispielantwort

{
  "count": 50,
  "deliveries": [
    { "driverDiscordId": "…", "game": "ets2", "cargo": "Ciment", "from": "Lyon",
      "to": "Milan", "distanceKm": 480, "damagePercent": 0, "truck": "Scania S",
      "at": "…", "income": 42000 }
  ]
}

GET /api/v1/live

Online-Fahrer (Präsenz < 60 s).

Beispielantwort

{
  "count": 3,
  "drivers": [
    { "discordId": "…", "name": "Marco", "avatar": "…", "game": "ETS2",
      "onJob": true, "cargo": "Bois", "from": "Oslo", "to": "Stockholm",
      "truck": "Volvo FH", "speed": 88, "distanceLeft": 120, "progressPct": 64 }
  ]
}

GET /api/v1/news?limit=1..100

Öffentliche und veröffentlichte Ankündigungen der VTC.

Beispielantwort

{
  "count": 5,
  "news": [
    { "id": "…", "title": "Recrutement ouvert !", "content": "…", "coverUrl": "…",
      "pinned": true, "authorName": "Léa", "at": "…", "updatedAt": "…" }
  ]
}

GET /api/v1/partners

Angenommene Partnerschaften (Partner-VTC).

Beispielantwort

{
  "count": 3,
  "partners": [
    { "id": "…", "name": "Nordic Logistics", "slug": "nordic-logistics",
      "tag": "[NL]", "logoUrl": "…", "game": "ets2", "since": "…" }
  ]
}

GET /api/v1/divisions

Transportdivisionen der VTC.

Beispielantwort

{
  "count": 4,
  "divisions": [
    { "id": "…", "name": "Frigo", "description": "…", "imageUrl": "…",
      "color": "#4ea1ff", "trucks": ["Scania S"], "trailers": ["Krone Cool"],
      "position": 0 }
  ]
}

GET /api/v1/gallery?limit=1..100

Öffentliche Fotogalerien der VTC (im Dashboard veröffentlichte Alben).

Beispielantwort

{
  "count": 6,
  "galleries": [
    { "id": "…", "title": "Convoi de Noël", "description": "…",
      "images": ["https://…/1.jpg", "https://…/2.jpg"], "photoCount": 2,
      "authorName": "Léa", "discordUrl": "https://discord.com/channels/…",
      "at": "…" }
  ]
}

GET /api/v1/hd/events?limit=1..100

Horizon-Dispatch-Events (global, alle öffentlichen VTC).

Beispielantwort

{
  "count": 10,
  "events": [
    { "id": "…", "title": "Grand convoi HD", "game": "ets2", "server": "Simulation 1",
      "departureCity": "Madrid", "arrivalCity": "Lisbonne", "plannedKm": 620,
      "meetupAt": "…", "startAt": "…",
      "vtc": { "name": "Horizon Dispatch", "slug": "horizon-dispatch", "tag": "[HDX]", "logoUrl": "…" },
      "externalUrl": "" }
  ]
}

Fehler

Code

error

Bedeutung

401

missing_api_key

Kein Schlüssel angegeben.

403

invalid_api_key

Unbekannter Schlüssel.

403

boost_required

Die VTC hat die 5-Boost-Stufe nicht.

403

api_disabled

Die VTC hat ihre öffentliche API deaktiviert.

403

members_hidden

Die VTC blendet die Mitgliederliste aus (/members).

429

rate_limited

Ratenlimit überschritten (siehe Header Retry-After).

500

server_error

Interner Fehler, versuche es später erneut.

Horizon Connect (OAuth 2)

Füge „Mit Horizon Dispatch anmelden“ zu deiner Website hinzu. Erstelle die Anwendung unter Dashboard → deine VTC → Ökosystem: Das Secret wird nur einmal angezeigt.

GET  https://hdispatch.eu/connect/authorize?client_id=…&redirect_uri=…&scope=identity%20profile%20vtc&state=…
     (PKCE: code_challenge hinzufügen, berechnet mit S256)
POST https://hdispatch.eu/connect/token      client_id, client_secret, code, redirect_uri (code_verifier si PKCE)
     → { "access_token": "…", "token_type": "Bearer", "expires_in": 2592000, "scope": "…" }
GET  https://hdispatch.eu/connect/userinfo   Authorization: Bearer <access_token>

Der Autorisierungscode ist 5 Minuten gültig und nur einmal verwendbar; das Token 30 Tage. Scopes: identity (Kennung), profile (Profil), vtc (VTC des Nutzers).

Widget zum Kopieren

Füge dies in deine Website ein und ersetze pk_VOTRE_CLE durch deinen öffentlichen Schlüssel:

<div id="hd-stats">Chargement…</div>
<script>
  fetch("https://hdispatch.eu/api/v1/vtc", { headers: { "x-api-key": "pk_VOTRE_CLE" } })
    .then(function (r) { return r.json(); })
    .then(function (v) {
      document.getElementById("hd-stats").innerHTML =
        "<b>" + v.name + "</b> — " + v.memberCount + " membres · " +
        v.totals.distanceKm.toLocaleString() + " km";
    });
</script>

Horizon-Dispatch-API

Öffentliche API ohne Schlüssel

Widgets für die Website deiner VTC

Schnellstart

Authentifizierung & Regeln

Endpoints

Fehler

Horizon Connect (OAuth 2)

Widget zum Kopieren