Hilfecenter · Für den Airline-Staff

Integrationen: API-Schlüssel, Webhooks und die Betriebs-API

Die Daten deiner Airline können deine eigenen Werkzeuge speisen: einen Discord-Bot, deine Website, eine Tabelle. Alles hier steht auf dem Tab Integrationen unter Staff → Airline-Einstellungen → Einstellungen. Du brauchst das Recht Airline-Einstellungen und der Betriebsschlüssel; Staff, der nur Discord verwaltet, sieht diesen Tab nicht.

Der Schlüssel für die Betriebs-API

Schlüssel erstellen gibt der Airline einen Schlüssel, der alles in der Betriebs-API lesen, aber nichts ändern kann. Er wird einmal gezeigt; gespeichert wird nur ein Fingerabdruck, kopier ihn also sofort. Verlierst du ihn, erstell einen neuen (der alte funktioniert dann nicht mehr). Der Schlüssel gehört dem Staff-Mitglied, das ihn erstellt hat: Verlässt es die Airline oder verliert es den Staff-Zugang oder diese Rechte, funktioniert er nicht mehr, und jemand mit dem Recht erstellt einen neuen.

Schick ihn bei jeder Anfrage als Header Authorization: Bearer your-key mit. Öffne /api/v1/ops auf der Website, um jede Adresse zu sehen; die wichtigsten sind:

/api/v1/ops/flights: Flüge, die gerade in der Luft sind, und die, die in den letzten Minuten eingereicht wurden, mit dem Ergebnis des PIREP.
/api/v1/ops/pireps: der Verlauf entschiedener PIREPs (angenommen, abgelehnt und so weiter), die älteste Entscheidung zuerst, mit Strecke, Zeiten, Flugzeug, Landerate und Punkten.
/api/v1/ops/pilots und /api/v1/ops/pilots/FCV0002: die Pilotenliste und Rang, Hub, Stunden und Standort eines Piloten.
/api/v1/ops/routes, /api/v1/ops/fleet, /api/v1/ops/events und /api/v1/ops/ranks: der Flugplan, die Flotte (Typen und jedes Flugzeug), kommende Events und die Rangleiter, für deine eigene Website.

Jede Adresse liest nur. Jeder Schlüssel kann bis zu 120 Anfragen pro Minute stellen.

Beispiele

Deine Pilotenliste, 100 Piloten auf einmal: curl -H "Authorization: Bearer your-key" "https://vaeroly.com/api/v1/ops/pilots?limit=100&offset=0"
Die nächsten 100: dasselbe mit offset=100. Das next_offset der Antwort sagt, wo die nächste Seite beginnt, und ist auf der letzten Seite null; total sagt, wie viele es sind. Ohne limit bekommst du die ganze Liste auf einmal.
Deine Flotte: curl -H "Authorization: Bearer your-key" https://vaeroly.com/api/v1/ops/fleet
Seit dem 1. Oktober entschiedene PIREPs: curl -H "Authorization: Bearer your-key" "https://vaeroly.com/api/v1/ops/pireps?since=2026-10-01&limit=200"
Die Seite danach: Füge cursor= mit dem next_cursor der Antwort hinzu. Behalte den letzten next_cursor, den du bekommen hast, und dein Werkzeug kann nach einer Pause von dort aufholen. Ein PIREP, dessen Entscheidung sich später ändert, kommt mit seinem neuen Status noch einmal. Eine Entscheidung wird gelistet, sobald sie 2 Minuten alt ist, eine Seite überspringt also nie eine, die noch gespeichert wurde.

Was die API nie zeigt

Die API gibt nie E-Mail-Adressen oder etwas anderes Privates heraus. Die Datenschutzentscheidungen der Piloten gelten hier wie auf der Website:

Ein Pilot, der seine Flüge auf Live-Karten versteckt, erscheint nicht in /flights oder /pireps.
Ein Pilot, der nicht in Ranglisten stehen will, steht in /pireps ohne Namen ("pilot": null), seine Flüge lassen sich also nicht in eine Rangfolge bringen.
Piloten, deren Konto bald gelöscht wird, fehlen überall.

Benannte API-Schlüssel

Mit eingeschalteten Benannten API-Schlüsseln (Optionale Funktionen) erstellst du einen Schlüssel pro Werkzeug, jeder darf nur, was er braucht: Flüge, Piloten, Flugplan oder Pilotenänderungen (die Aktivitätsbefreiung eines Piloten ein- oder ausschalten). Flüge umfasst /flights und /pireps; Flugplan umfasst Strecken, Flotte, Events und Ränge. Ein Schlüssel kann an einem Datum ablaufen und einzeln widerrufen werden. Bis zu 10 pro Airline; die Liste zeigt, wann jeder zuletzt genutzt wurde.

Webhooks

Mit eingeschalteten Webhooks bekommt dein eigener Server innerhalb von Sekunden eine Nachricht, wenn etwas passiert: ein PIREP eingereicht oder geprüft, ein Pilot tritt bei oder aus, eine Rangänderung, eine Buchung erstellt oder storniert, ein Flug startet. Jede Nachricht ist signiert, dein Server kann also prüfen, dass sie von Vaeroly kommt (der Header X-Vaeroly-Signature, ein HMAC aus Zeitstempel und Inhalt mit dem Geheimnis des Webhooks).

Webhooks folgen den Datenschutzentscheidungen der Piloten wie die API. Ein Pilot, der seine Flüge auf Live-Karten versteckt oder dessen Konto bald gelöscht wird, löst keine Nachrichten zu Buchung, Start oder PIREP aus. Ein Pilot, der nicht in Ranglisten stehen will, kommt in PIREP-Nachrichten ohne Namen ("pilot": null). Nachrichten über Piloten, die beitreten, austreten oder den Rang wechseln, werden für alle gesendet, so wie /pilots sie listet.

Prüf auf deinem Server noch zwei Dinge. Der Header X-Vaeroly-Timestamp ist der Zeitpunkt, zu dem die Nachricht signiert wurde, in Unix-Sekunden: Weise eine Nachricht ab, deren Zeitstempel mehr als 5 Minuten von der Uhr deines Servers abweicht, damit eine kopierte Nachricht dir später nicht erneut vorgespielt werden kann (jeder Versuch wird neu signiert, Wiederholungen kommen also durch). Und dieselbe Nachricht kann dich mehr als einmal erreichen, zum Beispiel wenn dein Server die Nachricht angenommen, aber zu langsam geantwortet hat und sie erneut versucht wurde: Jeder Versuch einer Nachricht trägt dieselbe Nummer X-Vaeroly-Delivery, behalte also die Nummern, die du verarbeitet hast, ein paar Tage und überspring eine, die du schon gesehen hast. Eine mit Erneut senden im Protokoll noch einmal gesendete Zustellung ist eine neue Zustellung mit einer neuen Nummer.

Fehlgeschlagene Zustellungen werden etwa 15 Stunden lang wiederholt. Jeder Webhook hat ein Zustellprotokoll und einen Knopf Test senden. Ein Webhook, der 3 Tage lang fehlgeschlagen ist, wird ausgeschaltet, und der Inhaber bekommt eine E-Mail. Bis zu 5 pro Airline (öffne bei einem Webhook Protokoll & Einstellungen für sein Protokoll und den Test-Knopf). Jeder Webhook kann einmal alle 30 Sekunden einen Test senden oder eine Zustellung erneut senden, und eine Airline kann 20 Tests und erneute Zustellungen pro Stunde senden.