Centre d'aide · Pour le staff de la compagnie

Intégrations : clés API, webhooks et API Operations

Les données de ta compagnie peuvent alimenter tes propres outils : un bot Discord, ton site web, un tableur. Tout se trouve dans l'onglet Intégrations de Staff → Paramètres de la compagnie → Paramètres. Il te faut la permission Paramètres de la compagnie et clé d'opérations ; le staff qui ne gère que Discord ne voit pas cet onglet.

La clé de l'API Operations

Créer la clé donne à la compagnie une clé qui peut tout lire dans l'API Operations mais ne rien modifier. Elle s'affiche une seule fois ; seule une empreinte est conservée, copie-la donc tout de suite. Si tu la perds, crées-en une nouvelle (l'ancienne cesse de fonctionner). La clé appartient au membre du staff qui l'a créée : s'il quitte la compagnie ou perd son accès staff ou ces permissions, elle cesse de fonctionner et quelqu'un qui a la permission en crée une nouvelle.

Envoie-la avec chaque requête dans l'en-tête Authorization: Bearer your-key. Ouvre /api/v1/ops sur le site pour voir toutes les adresses ; les principales sont :

/api/v1/ops/flights : les vols en l'air maintenant et ceux déposés ces dernières minutes, avec le résultat du PIREP.
/api/v1/ops/pireps : l'historique des PIREP décidés (acceptés, refusés, etc.), décision la plus ancienne d'abord, avec ligne, heures, avion, taux d'atterrissage et points.
/api/v1/ops/pilots et /api/v1/ops/pilots/FCV0002 : la liste des pilotes, et le grade, le hub, les heures et la position d'un pilote.
/api/v1/ops/routes, /api/v1/ops/fleet, /api/v1/ops/events et /api/v1/ops/ranks : le programme, la flotte (types et chaque avion), les événements à venir et l'échelle des grades, pour ton propre site web.

Chaque adresse ne fait que lire. Chaque clé peut faire jusqu'à 120 requêtes par minute.

Exemples

Ta liste de pilotes, 100 pilotes à la fois : curl -H "Authorization: Bearer your-key" "https://vaeroly.com/api/v1/ops/pilots?limit=100&offset=0"
Les 100 suivants : la même chose avec offset=100. Le next_offset de la réponse dit où commence la page suivante, et vaut null sur la dernière page ; total dit combien il y en a. Sans limit, tu obtiens toute la liste d'un coup.
Ta flotte : curl -H "Authorization: Bearer your-key" https://vaeroly.com/api/v1/ops/fleet
Les PIREP décidés depuis le 1er octobre : curl -H "Authorization: Bearer your-key" "https://vaeroly.com/api/v1/ops/pireps?since=2026-10-01&limit=200"
La page d'après : ajoute cursor= avec le next_cursor de la réponse. Garde le dernier next_cursor reçu, et ton outil peut rattraper son retard à partir de là après une pause. Un PIREP dont la décision change plus tard revient avec son nouveau statut. Une décision est listée quand elle a 2 minutes, pour qu'une page n'en saute jamais une qui était encore en cours d'enregistrement.

Ce que l'API ne montre jamais

L'API ne donne jamais d'adresses e-mail ni rien d'autre de privé. Les choix de confidentialité des pilotes comptent ici comme sur le site :

Un pilote qui masque ses vols des cartes en direct n'apparaît pas dans /flights ni /pireps.
Un pilote qui reste hors des classements est listé dans /pireps sans nom ("pilot": null), pour que ses vols ne puissent pas être classés.
Les pilotes dont le compte va être supprimé sont écartés partout.

Clés API nommées

Avec Clés API nommées activées (Fonctions optionnelles), crée une clé par outil, chacune limitée à ce dont elle a besoin : Vols, Pilotes, Programme, ou Modifications de pilotes (activer ou désactiver l'exemption d'activité d'un pilote). Vols couvre /flights et /pireps ; Programme couvre les lignes, la flotte, les événements et les grades. Une clé peut expirer à une date et être révoquée seule. Jusqu'à 10 par compagnie ; la liste montre quand chacune a servi pour la dernière fois.

Webhooks

Avec Webhooks activés, ton propre serveur reçoit un message en quelques secondes quand quelque chose se passe : un PIREP déposé ou relu, un pilote qui arrive ou part, un changement de grade, une réservation faite ou annulée, un vol qui décolle. Chaque message est signé, pour que ton serveur puisse vérifier qu'il vient de Vaeroly (l'en-tête X-Vaeroly-Signature, un HMAC de l'horodatage et du corps avec le secret du webhook).

Les webhooks suivent les choix de confidentialité des pilotes comme l'API. Un pilote qui masque ses vols des cartes en direct, ou dont le compte va être supprimé, n'envoie aucun message de réservation, de décollage ou de PIREP. Un pilote qui reste hors des classements arrive sans nom dans les messages de PIREP ("pilot": null). Les messages sur les pilotes qui arrivent, partent ou changent de grade sont envoyés pour tout le monde, comme /pilots les liste.

Vérifie encore deux choses sur ton serveur. L'en-tête X-Vaeroly-Timestamp est l'heure de signature du message, en secondes Unix : refuse un message dont l'horodatage s'écarte de plus de 5 minutes de l'horloge de ton serveur, pour qu'un message copié ne puisse pas t'être rejoué plus tard (chaque tentative est signée à neuf, donc les nouvelles tentatives passent). Et le même message peut t'arriver plus d'une fois, par exemple quand ton serveur a pris le message mais a répondu trop lentement et qu'il a été réessayé : chaque tentative d'un message porte le même numéro X-Vaeroly-Delivery, garde donc les numéros que tu as traités pendant quelques jours et ignore ceux que tu as déjà vus. Un envoi renvoyé avec Renvoyer dans le journal est un nouvel envoi avec un nouveau numéro.

Les envois qui échouent sont réessayés pendant environ 15 heures. Chaque webhook a un journal d'envois et un bouton Envoyer un test. Un webhook qui échoue depuis 3 jours est désactivé et le propriétaire reçoit un e-mail. Jusqu'à 5 par compagnie (ouvre Journal et paramètres sur un webhook pour son journal et le bouton de test). Chaque webhook peut envoyer un test, ou renvoyer un envoi, une fois toutes les 30 secondes, et une compagnie peut envoyer 20 tests et renvois par heure.