POST -pyyntö, jonka Aniva lähettää palvelimellesi, kun jokin muuttuu. Sinun ei
tarvitse kysellä muutoksia toistuvasti.
Tapahtumat ovat kevyitä. Ne sisältävät kohteen tunnisteen, uuden tilan, version ja luettavan url-osoitteen. Ne
eivät koskaan sisällä laboratorioarvoja tai henkilötietoja. Hae tiedot lukemalla url API-avaimellasi.
Pikakäyttöönotto
- Rakenna HTTPS-päätepiste, joka ottaa vastaan
POST-pyyntöjä ja vastaa2xx-koodilla 15 sekunnin kuluessa. - Rekisteröi se toiminnolla Luo webhook.
Tallenna vastauksen
secret. Aniva näyttää sen vain kerran. - Tarkista allekirjoitus jokaisesta pyynnöstä.
- Lähetä testitapahtuma. Tarkista tulos kohdasta Listaa toimitukset.
webhooks_manage-käyttöoikeuden. Pyydä Anivaa lisäämään se. Webhook kuuluu sen
luoneelle API-avaimelle, ja yhdellä avaimella voi olla enintään 5 webhookia.
Tapahtumat
Saat tapahtuman vain objekteista, joita API-avaimesi voi lukea vastaavallaGET-päätepisteellä.
Valitse tyypit enabled_events-kentällä. Lähetä ["*"], niin saat kaikki tyypit, myös myöhemmin lisätyt.
- Tilatapahtuma lähetetään jokaisesta siirtymästä kyseiseen tilaan, myös paluusta takaisin. Esimerkiksi
kotitestipakkaus, joka palaa tilasta
dispatchedtilaanpending, lähettää tapahtumanhome_kit_order.pending. - Yksi muutos voi lähettää kaksi tapahtumaa samalla
status_revision-arvolla, esimerkiksiappointment.confirmedjaappointment.rescheduled. results.updatedlähetetään jokaisesta tulosten muutoksesta: uudesta arvosta, korjauksesta, virheestä, uudesta tai korvatusta dokumentista tai näytteestä, joka poistuu objektista. Se saapuu muutaman minuutin kuluessa viimeisimmästä muutoksesta.results.completedjaresults.faulttulevat aina yhdessäresults.updated-tapahtuman kanssa, jolla on samaresults_revision. Tulokset voidaan avata uudelleen ja merkitä jälleen valmiiksi, joten voit saada toisenresults.completed-tapahtuman.
results.updated, jos haluat näyttää osittaiset tulokset, tai results.completed, jos haluat reagoida vain
lopullisiin tuloksiin.
results.completed seuraa tulosarvoja, ei PDF-tiedostoa. Raportin PDF voi saapua ennen arvoja tai
niiden jälkeen. Jotkin laboratoriot lähettävät ensin alustavan PDF-tiedoston ja korvaavat sen myöhemmin lopullisella
samalla dokumentin id-tunnuksella. Korvaaminen lähettää tapahtuman results.updated. Erota nämä kaksi toisistaan
lukemalla documents[].original_file_name: Labor Quade päättää alustavan raportin (Vorbefund) merkintään _V
ja lopullisen raportin (Endbefund) merkintään _E, esimerkiksi
7642100312_B0012_FA_E.pdf.
Toimipiste-, profiili- ja lähetystapahtumat saapuvat muutaman minuutin kuluessa. Aniva odottaa, kunnes objekti ei
ole muuttunut 2 minuuttiin, joten sarja muokkauksia lähettää yhden tapahtuman. Myös nämä säännöt pätevät:
- Anonyymit profiilit eivät lähetä tapahtumia.
- Lähetys ei lähetä tapahtumaa, kun menetät pääsyn siihen.
- Lähetyksen tilan muutos lähettää tapahtuman
shipment.updatedja tapahtumanshipment.<status>samallarevision-arvolla.
Tietosisältö
Tilatapahtuman tiedot
appointment.confirmed
Tulostapahtuman tiedot
home_kit_order.results.completed
Dokumentin poistotapahtuman tiedot
document.deleted sisältää kentät object (document), id, previous_results_status ja
results_revision. Siinä ei ole url-kenttää, koska mitään luettavaa ei ole jäljellä.
document.deleted
Toimipiste-, profiili- ja lähetystapahtuman tiedot
shipment.in_transit
ping sisältää kentän data.object arvolla webhook ja kentän data.id, joka on webhookin tunnus.
Vahvista allekirjoitus
Tapahtumat eivät sisällä dataa, mutta jokainen niistä kannattaa silti vahvistaa. Kelvollinen allekirjoitus todistaa, että tapahtuma tuli Anivalta. Jokainen pyyntö sisältää otsakkeetwebhook-id, webhook-timestamp (Unix-
sekunteina) ja webhook-signature.
- Ota pyynnön raakarunko. Vahvista se ennen JSON:n jäsentämistä.
- Muodosta allekirjoitettava sisältö
{webhook-id}.{webhook-timestamp}.{raw body}. - Dekoodaa salaisuutesi
whsec_-etuliitteen jälkeinen osa base64-muodosta. Käytä sitä avaimena. - Laske allekirjoitettavan sisällön HMAC-SHA256 ja koodaa se base64-muotoon.
- Vertaa sitä vakioajassa jokaiseen
webhook-signature-otsakkeenv1,<signature>-merkintään. Merkinnät erotetaan välilyönneillä. Yksi osuma riittää. - Hylkää pyyntö, jos
webhook-timestamperoaa kellostasi yli 5 minuuttia.
Node.js
Kierrätä salaisuus
Kutsu Vaihda salaisuus -päätepistettä saadaksesi uuden salaisuuden. Aniva allekirjoittaa 24 tunnin ajan sekä vanhalla että uudella salaisuudella, joten ota uusi käyttöön sen aikana. Vuodon jälkeen lähetärevoke_current_secret_now: true poistaaksesi vanhan salaisuuden käytöstä heti.
Toimitus
- Vastaa
2xx-koodilla 15 sekunnin kuluessa. Tallenna tapahtuma tai lisää se jonoon ja käsittele se myöhemmin. - Käytä julkisen palvelimen
https-URL-osoitetta portissa 443. Aniva ei seuraa uudelleenohjauksia:3xxlasketaan virheeksi. - Toimitus tapahtuu vähintään kerran ilman taattua järjestystä. Hylkää kaksoiskappaleet
webhook-id-tunnisteen avulla. Ohita vanhempi tapahtuma revisioiden avulla. - Vastaa
410 Gonelopettaaksesi tapahtumat. Aniva poistaa webhookin käytöstä heti. - Aniva säilyttää toimitukset 30 päivää. Sen jälkeen et voi listata tai lähettää niitä uudelleen.
Uudelleenyritykset
Muu kuin2xx-vastaus, aikakatkaisu tai verkkovirhe käynnistää uudelleenyrityksen. Kutakin tapahtumaa yritetään enintään 10 kertaa
noin kolmen päivän aikana:
Yrityksen 10 jälkeen toimituksen tila on
failed. Lähetä se uudelleen
Lähetä toimitus uudelleen -päätepisteellä. Sen webhook-id pysyy samana.
Virheilmoitukset
Aniva lähettää sähköpostia webhookinalert_emails-osoitteisiin, kun yksikään toimitus ei ole onnistunut 24 tuntiin, kun tapahtuman tila on
failed ja kun webhook poistetaan käytöstä. Kun 5 päivää on kulunut ilman onnistunutta toimitusta, Aniva
poistaa webhookin käytöstä. Käytöstä poistettu webhook ei saa uusia tapahtumia, ja sen odottavat toimitukset
perutaan.
Aloita uudelleen korjaamalla päätepisteesi ja lähettämällä
status: "enabled"
Päivitä webhook -päätepisteellä. Väliin jääneitä tapahtumia ei lähetetä
uudelleen automaattisesti. Lähetä ne uudelleen tai lue nykytila GET-päätepisteistä.
Toistuvat haut
Aniva tallentaa joidenkinGET-päätepisteiden vastauksen lyhyeksi ajaksi. Kun API-avaimesi lähettää saman
pyynnön uudelleen tämän ajan kuluessa, saat tallennetun vastauksen. Et saa virhettä, ja vastauksen runko on
samassa muodossa.
- Yksi tietue (lähetys, kotitestipakkaustilaus, ajanvaraus ja kahden viimeksi mainitun tulokset): Aniva tarkistaa jokaisella kutsulla, ettei tietue ole muuttunut. Jos se on muuttunut, saat tuoreen vastauksen.
- Lista voi olla vanhempi kuin sen tietueet, enintään 5 minuuttia.
- Sama pyyntö tarkoittaa samaa API-avainta, samaa päätepistettä ja samoja kyselyparametreja. Listan toinen sivu on eri pyyntö ja saa oman vastauksensa.
- Aniva tallentaa vain
200-vastauksen. Virhettä ei tallenneta koskaan. - Aika alkaa, kun Aniva tallentaa vastauksen. Myöhempi kutsu ei pidennä sitä.
- Kun API-avaimesi luo, päivittää, aktivoi tai peruu jotakin, seuraava hakusi on tuore. Myös toisella API-avaimellasi tehty seuraava haku kyseisestä tietueesta on tuore.
- Tallennetussa lähetysvastauksessa kentät
synced_atjaupdated_atvoivat olla vanhempia kuin tuoreessa vastauksessa. Tila, seuranta ja osoitteet ovat ajantasaisia. - Tallennetussa tulosvastauksessa biomarkkerin nimi, yksikkö tai muunnettu arvo voi olla enintään 60 minuuttia vanha sen jälkeen, kun Aniva muuttaa luetteloaan. Mitatut arvot ovat ajantasaisia.
- Kun Aniva luo webhook-tapahtuman webhookillesi, seuraava kyseisen tietueen, sen tulosten ja sen listojen haku on tuore. Näin tapahtumaa seuraava haku näyttää aina muutoksen.
Vastausotsakkeet
Jokaisessa näiden päätepisteiden vastauksessa kelvolliselle API-avaimelle on nämä otsakkeet:Parhaat käytännöt
- Hylkää kaksoiskappaleet. Ohita tapahtuma, jonka
webhook-id-tunnisteen olet jo käsitellyt. - Käytä revisioita. Tallenna suurin
status_revision,results_revisionjarevisionkohdekohtaisesti. Ohita tapahtuma, jossa arvo on pienempi. - Hae
url. Tapahtuma kertoo, että jokin muuttui.GET-päätepiste kertoo, mikä muuttui. - Vastaa nopeasti. Lisää tapahtuma jonoon ja vastaa
2xx-koodilla ennen sen käsittelyä. - Täsmäytä. Aja säännöllinen tehtävä, joka lukee avoimet kohteet
GET-päätepisteistä. Kysely pysyy kelvollisena vararatkaisuna. Toistuva haku voi saada tallennetun vastauksen, katso Toistuvat haut. - Testaa jokaisen julkaisun jälkeen. Käytä Lähetä testitapahtuma -päätepistettä.