Ohjekeskus · Lentoyhtiön henkilökunnalle

Integraatiot: API-avaimet, webhookit ja Operations API

Lentoyhtiösi tiedot voivat syöttää omia työkalujasi: Discord-bottia, verkkosivuasi, taulukkoa. Kaikki tässä on välilehdellä Integraatiot kohdassa Staff → Lentoyhtiön asetukset → Asetukset. Tarvitset oikeuden Lentoyhtiön asetukset ja operations-avain; henkilökunta, joka hoitaa vain Discordia, ei näe tätä välilehteä.

Operations API -avain

Luo avain antaa lentoyhtiölle yhden avaimen, joka voi lukea kaiken Operations API:ssa mutta ei muuttaa mitään. Se näytetään kerran; vain sormenjälki säilytetään, joten kopioi se heti. Jos kadotat sen, tee uusi (vanha lakkaa toimimasta). Avain kuuluu sen tehneelle henkilökunnan jäsenelle: jos hän poistuu lentoyhtiöstä tai menettää henkilökunta-oikeutensa tai nämä oikeudet, avain lakkaa toimimasta, ja joku, jolla on oikeus, tekee uuden.

Lähetä se jokaisen pyynnön mukana otsakkeena Authorization: Bearer your-key. Avaa sivustolla /api/v1/ops nähdäksesi kaikki osoitteet; tärkeimmät ovat:

/api/v1/ops/flights: ilmassa olevat lennot ja viime minuutteina lähetetyt lennot PIREPin tuloksineen.
/api/v1/ops/pireps: ratkaistujen PIREP-raporttien historia (hyväksytyt, hylätyt ja niin edelleen), vanhin päätös ensin, reitin, aikojen, koneen, laskeutumisnopeuden ja pisteiden kanssa.
/api/v1/ops/pilots ja /api/v1/ops/pilots/FCV0002: lentäjälista sekä yhden lentäjän arvo, hubi, tunnit ja sijainti.
/api/v1/ops/routes, /api/v1/ops/fleet, /api/v1/ops/events ja /api/v1/ops/ranks: aikataulu, laivasto (tyypit ja jokainen kone), tulevat tapahtumat ja arvoportaat omalle verkkosivullesi.

Jokainen osoite vain lukee. Kukin avain voi tehdä enintään 120 pyyntöä minuutissa.

Esimerkkejä

Lentäjälistasi, 100 lentäjää kerrallaan: curl -H "Authorization: Bearer your-key" "https://vaeroly.com/api/v1/ops/pilots?limit=100&offset=0"
Seuraavat 100: sama offset=100:lla. Vastauksen next_offset kertoo, mistä seuraava sivu alkaa, ja on null viimeisellä sivulla; total kertoo, kuinka monta niitä on. Ilman limit-parametria saat koko listan kerralla.
Laivastosi: curl -H "Authorization: Bearer your-key" https://vaeroly.com/api/v1/ops/fleet
1. lokakuuta jälkeen ratkaistut PIREP-raportit: curl -H "Authorization: Bearer your-key" "https://vaeroly.com/api/v1/ops/pireps?since=2026-10-01&limit=200"
Sen jälkeinen sivu: lisää cursor= ja vastauksen next_cursor. Säilytä viimeisin saamasi next_cursor, niin työkalusi voi ottaa kiinni siitä kohdasta tauon jälkeen. PIREP, jonka päätös muuttuu myöhemmin, tulee uudelleen uudella tilallaan. Päätös listataan, kun se on 2 minuuttia vanha, joten sivu ei koskaan ohita päätöstä, jota vielä tallennettiin.

Mitä API ei koskaan näytä

API ei koskaan anna sähköpostiosoitteita tai muuta yksityistä. Lentäjien yksityisyysvalinnat pätevät täällä kuten sivustolla:

Lentäjä, joka piilottaa lentonsa live-kartoilta, ei näy kohdissa /flights tai /pireps.
Lentäjä, joka pysyy poissa tulostauluista, listataan kohdassa /pireps ilman nimeä ("pilot": null), joten hänen lentojaan ei voi asettaa järjestykseen.
Lentäjät, joiden tili on poistumassa, jätetään pois kaikkialta.

Nimetyt API-avaimet

Kun Nimetyt API-avaimet on päällä (Valinnaiset ominaisuudet), tee yksi avain kullekin työkalulle, ja jokaiselle vain tarvittavat oikeudet: Lennot, Lentäjät, Aikataulu tai Lentäjämuutokset (lentäjän aktiivisuusvapautuksen kytkeminen päälle tai pois). Lennot kattaa kohdat /flights ja /pireps; Aikataulu kattaa reitit, laivaston, tapahtumat ja arvot. Avain voi vanhentua tiettynä päivänä ja sen voi perua erikseen. Enintään 10 avainta lentoyhtiötä kohden; lista näyttää, milloin kutakin on viimeksi käytetty.

Webhookit

Kun Webhookit on päällä, oma palvelimesi saa viestin sekunneissa, kun jotain tapahtuu: PIREP lähetetään tai tarkastetaan, lentäjä liittyy tai lähtee, arvo muuttuu, varaus tehdään tai perutaan, lento nousee ilmaan. Jokainen viesti on allekirjoitettu, joten palvelimesi voi tarkistaa, että se tuli Vaerolysta (otsake X-Vaeroly-Signature, aikaleiman ja sisällön HMAC webhookin secretillä).

Webhookit noudattavat lentäjien yksityisyysvalintoja kuten API. Lentäjä, joka piilottaa lentonsa live-kartoilta tai jonka tili on poistumassa, ei lähetä varaus-, lentoonlähtö- tai PIREP-viestejä. Lentäjä, joka pysyy poissa tulostauluista, tulee PIREP-viesteissä ilman nimeä ("pilot": null). Viestit lentäjien liittymisestä, lähtemisestä tai arvon muutoksesta lähetetään kaikista, kuten /pilots listaa heidät.

Tarkista palvelimellasi vielä kaksi asiaa. Otsake X-Vaeroly-Timestamp on aika, jolloin viesti allekirjoitettiin, Unix-sekunteina: hylkää viesti, jonka aikaleima poikkeaa palvelimesi kellosta yli 5 minuuttia, jotta kopioitua viestiä ei voi toistaa sinulle myöhemmin (jokainen yritys allekirjoitetaan uudelleen, joten uudelleenyritykset menevät läpi). Ja sama viesti voi saapua sinulle useammin kuin kerran, esimerkiksi kun palvelimesi otti viestin vastaan mutta vastasi liian hitaasti ja sitä yritettiin uudelleen: jokaisen viestin jokainen yritys sisältää saman X-Vaeroly-Delivery-numeron, joten säilytä käsittelemäsi numerot muutaman päivän ajan ja ohita jo nähty. Lokista Lähetä uudelleen -painikkeella uudelleen lähetetty toimitus on uusi toimitus uudella numerolla.

Epäonnistuneita toimituksia yritetään uudelleen noin 15 tuntia. Jokaisella webhookilla on toimituslokinsa ja Lähetä testi -painike. Webhook, joka on epäonnistunut 3 päivää, kytketään pois ja omistaja saa sähköpostia. Enintään 5 webhookia lentoyhtiötä kohden (avaa webhookin kohta Loki & asetukset nähdäksesi sen lokin ja testipainikkeen). Jokainen webhook voi lähettää testin tai lähettää toimituksen uudelleen kerran 30 sekunnissa, ja lentoyhtiö voi lähettää 20 testiä ja uudelleenlähetystä tunnissa.