Centro assistenza · Per lo staff delle compagnie

Integrazioni: chiavi API, webhook e Operations API

I dati della tua compagnia possono alimentare i tuoi strumenti: un bot Discord, il tuo sito, un foglio di calcolo. Tutto quello che trovi qui è nella scheda Integrazioni di Staff → Impostazioni della compagnia → Impostazioni. Ti serve il permesso Impostazioni della compagnia e chiave operativa; lo staff che gestisce solo Discord non vede questa scheda.

La chiave della Operations API

Crea chiave dà alla compagnia una chiave che può leggere tutto nella Operations API ma non cambia niente. Viene mostrata una volta sola; si tiene solo un'impronta, quindi copiala subito. Se la perdi, creane una nuova (quella vecchia smette di funzionare). La chiave appartiene al membro dello staff che l'ha creata: se lascia la compagnia o perde l'accesso staff o questi permessi, smette di funzionare e qualcuno con il permesso ne crea una nuova.

Mandala con ogni richiesta nell'header Authorization: Bearer your-key. Apri /api/v1/ops sul sito per vedere tutti gli indirizzi; i principali sono:

/api/v1/ops/flights: i voli in aria adesso e quelli inviati negli ultimi minuti, con l'esito del PIREP.
/api/v1/ops/pireps: lo storico dei PIREP decisi (accettati, rifiutati e così via), dalla decisione più vecchia, con rotta, orari, aereo, rateo di atterraggio e punti.
/api/v1/ops/pilots e /api/v1/ops/pilots/FCV0002: l'elenco piloti, e grado, hub, ore e posizione di un pilota.
/api/v1/ops/routes, /api/v1/ops/fleet, /api/v1/ops/events e /api/v1/ops/ranks: l'operativo voli, la flotta (tipi e ogni aereo), i prossimi eventi e la scala dei gradi, per il tuo sito.

Ogni indirizzo è in sola lettura. Ogni chiave può fare fino a 120 richieste al minuto.

Esempi

L'elenco piloti, 100 alla volta: curl -H "Authorization: Bearer your-key" "https://vaeroly.com/api/v1/ops/pilots?limit=100&offset=0"
I 100 successivi: lo stesso con offset=100. Il campo next_offset della risposta dice dove inizia la pagina successiva, ed è null sull'ultima pagina; total dice quanti sono in tutto. Senza limit ricevi tutto l'elenco in una volta.
La tua flotta: curl -H "Authorization: Bearer your-key" https://vaeroly.com/api/v1/ops/fleet
I PIREP decisi dal 1° ottobre: curl -H "Authorization: Bearer your-key" "https://vaeroly.com/api/v1/ops/pireps?since=2026-10-01&limit=200"
La pagina dopo: aggiungi cursor= con il next_cursor della risposta. Tieni l'ultimo next_cursor ricevuto, e il tuo strumento può riprendere da lì dopo una pausa. Un PIREP la cui decisione cambia dopo torna di nuovo con il nuovo stato. Una decisione viene elencata quando ha 2 minuti, così una pagina non ne salta mai una che si stava ancora salvando.

Cosa la API non mostra mai

La API non dà mai indirizzi email né altri dati privati. Le scelte di privacy dei piloti valgono qui come sul sito:

Un pilota che nasconde i suoi voli dalle mappe live non compare in /flights né in /pireps.
Un pilota che resta fuori dalle classifiche è elencato in /pireps senza nome ("pilot": null), così i suoi voli non si possono mettere in classifica.
I piloti il cui account sta per essere eliminato sono esclusi ovunque.

Chiavi API con nome

Con Chiavi API con nome attive (Funzioni opzionali), crea una chiave per ogni strumento, ognuna con solo quello che le serve: Voli, Piloti, Operativo voli o Modifiche ai piloti (attivare o togliere l'esenzione dall'attività di un pilota). Voli copre /flights e /pireps; Operativo voli copre rotte, flotta, eventi e gradi. Una chiave può scadere in una data e può essere revocata da sola. Fino a 10 per compagnia; l'elenco mostra quando ognuna è stata usata l'ultima volta.

Webhook

Con Webhook attivi, il tuo server riceve un messaggio entro pochi secondi quando succede qualcosa: un PIREP inviato o revisionato, un pilota che entra o esce, un cambio di grado, una prenotazione fatta o cancellata, un volo che decolla. Ogni messaggio è firmato, così il tuo server può controllare che arrivi da Vaeroly (l'header X-Vaeroly-Signature, un HMAC del timestamp e del corpo con il segreto del webhook).

I webhook seguono le scelte di privacy dei piloti come la API. Un pilota che nasconde i suoi voli dalle mappe live, o il cui account sta per essere eliminato, non genera messaggi di prenotazione, decollo o PIREP. Un pilota che resta fuori dalle classifiche arriva senza nome nei messaggi PIREP ("pilot": null). I messaggi su piloti che entrano, escono o cambiano grado vengono mandati per tutti, come li elenca /pilots.

Controlla altre due cose sul tuo server. L'header X-Vaeroly-Timestamp è l'ora in cui il messaggio è stato firmato, in secondi Unix: rifiuta un messaggio il cui timestamp si discosta di più di 5 minuti dall'orologio del tuo server, così un messaggio copiato non può esserti rimandato più tardi (ogni tentativo viene firmato di nuovo, quindi i nuovi tentativi passano). E lo stesso messaggio può arrivarti più di una volta, per esempio quando il tuo server l'ha ricevuto ma ha risposto troppo lentamente e c'è stato un nuovo tentativo: ogni tentativo di un messaggio porta lo stesso numero X-Vaeroly-Delivery, quindi tieni per qualche giorno i numeri già gestiti e salta quelli che hai già visto. Una consegna rimandata con Invia di nuovo nel registro è una nuova consegna con un nuovo numero.

Le consegne fallite vengono ritentate per circa 15 ore. Ogni webhook ha un registro delle consegne e un pulsante Invia una prova. Un webhook che fallisce da 3 giorni viene spento e il proprietario riceve un'email. Fino a 5 per compagnia (apri Registro e impostazioni su un webhook per il registro e il pulsante di prova). Ogni webhook può mandare una prova, o rimandare una consegna, una volta ogni 30 secondi, e una compagnia può mandare 20 prove e reinvii all'ora.