Yhteydenottotapa
Netvisorin tarjoama Web Service -ohjelmistorajapinta on REST–mallin mukainen. Kommunikointi asiakasohjelman ja palvelimen välillä tapahtuu HTTP-pyynnöillä. Rajapinta on kaksisuuntainen ja tapahtumapohjainen.
Tuotaessa tietoa lähettävä järjestelmä muodostaa aineistoa kuvaavan XML-sanoman ja lähettää sen HTTP-pyynnön päällä Netvisoriin. Valittu resurssi määrittelee integraatiotapahtuman tyypin. Osassa tapahtumista käyttäjä saa tunnistetietoa lisätystä aineistosta myöhempää käyttöä varten.
Vietäessä aineistoa poispäin Netvisorista pyynnössä ei tarvitse lähettää XML-sanomaa. Pyyntö osoitetaan haluttuun resurssiin ja rajataan tarvittaessa kyseisen resurssin mahdollistamilla parametreilla. Vastauksessa pyydetty tapahtuma esitetään käyttäjälle XML-muodossa.
Kaikki rajapinnan lähettämät vastaukset ovat XML-muodossa ja sisältävät aina ResponseStatus –elementin, josta voidaan tulkita pyynnön onnistuminen. Virhetilanteessa välitetään myös virheselite ja virheen tyyppi. Onnistuneessa vastauksessa on vakiona "OK" Status-elementin sisällä ja vastaavasti virheellisessä vakiona "FAILED". Virhetilanteita varten katso erillinen virhetilanteiden hallintaohje.
Esimerkkivastaus onnistuneesta pyynnöstä:
<Root>
<ResponseStatus>
<Status>OK</Status>
<TimeStamp>01.01.2018 12:00:00</TimeStamp>
</ResponseStatus>
<Replies>
<InsertedDataIdentifier>1802</InsertedDataIdentifier>
</Replies>
</Root>
Tietoturva ja tunnistautuminen
Tarkemman dokumentaation rajapintatunnistautumiseen saat Netvisorin kumppanituelta testiympäristön toimituksen yhteydessä. Tämän sivun ohjeistus on tarkoitettu sen tueksi, mutta ei yksinään selitä tunnistautumisen logiikkaa. Tutustu siis ensin kohtaan: Uusille integraatiototeutuksen tekijöille
Huomioittehan, että asiakkaan tulee aina toimittaa integraation toteuttajalle ohjelmistorajapintatunnukset ja sallia rajapintaresurssit Netvisorissa, että tunnistautuminen ja aineiston siirto onnistuu.
Ohjelmistorajapinnan tietoturva on toteutettu kahdella eri tavalla:
1. Salattu yhteys
Kommunikointi integraatiopalvelun tuotanto- ja testiympäristöön tehdään salattuja yhteyksiä käyttäen (HTTPS).
2. Tunnistautumistietojen yksisuuntainen salaus
Integraatiopalveluun lähetettävät tunnistautumistiedot salataan luomalla niistä tarkistussumma, josta alkuperäisiä tunnuksia ei voida muodostaa takaisinpäin.
Tunnistautuminen
Rajapinta tunnistaa integraatiopyynnön HTTP-otsikoissa olevien otsikkotietojen ja niistä lasketun MAC-koodin perusteella. Asiakasohjelman tulee kirjoittaa kaikki otsikot jokaiseen lähettämäänsä HTTP-pyyntöön. Jos kaikkia tarvittavia otsikoita ei ole annettu, rajapinta palauttaa virheen tunnistautumisen epäonnistumisesta selitteineen. Tunnistautumisessa tapahtuneet virheet erottaa AUTHENTICATION_FAILED–vakiosta ennen virheselitettä.
Rajapintaresurssien tulee olla sallittu kohdeyrityksessä, jotta sille tulevat pyynnöt sallitaan.
PHP-esimerkki MAC-koodin ja HTTP-otsikoiden muodostukseen.
MAC -laskenta:
public function getMAC() { $parameters = array( $this->url, $this->sender, $this->customerId, $this->timestamp, $this->language, $this->organisationId, $this->transactionId, $this->customerKey, $this->partnerKey ); $parameters = array_map("strval", $parameters); return hash("sha256", implode("", $parameters)); }
Lähetettävät HTTP-otsikot:
public function getAuthenticationHeaders() { $headers = array( "X-Netvisor-Authentication-Sender:" . $this->sender, "X-Netvisor-Authentication-CustomerId:" . $this->customerId, "X-Netvisor-Authentication-PartnerId:" . $this->partnerId, "X-Netvisor-Authentication-Timestamp:" . $this->timestamp, "X-Netvisor-Authentication-TransactionId:" . $this->transactionId, "X-Netvisor-Interface-Language:" . $this->language, "X-Netvisor-Organisation-ID:" . $this->organisationId, "X-Netvisor-Authentication-MAC:" . $this->mac, "X-Netvisor-Authentication-MACHashCalculationAlgorithm: SHA256", ); return $headers ; }
Python esimerkki MAC-koodin ja HTTP-otsikoiden muodostukseen
MAC -laskenta, SHA256 laskentaa käyttäen:
#Url, where the request is sent url = "https://isvapi.netvisor.fi/customerlist.nv" #Give variables sender = "ClientName" customerId = "XXX" partnerId = "XXX" transactionId = "TRANSID"+"%0.12d" % random.randint(0,99999999) #Generate random TransactionId, type string timestamp = time.strftime("%Y-%m-%d %H:%M:%S", time.gmtime()) language="FI" organisationId="0123456-7" #Netvisor environment's organisation id / business id customerKey = "XXX" partnerKey = "XXX" #MAC calculation sha256string = url+"&"+sender+"&"+customerId+"&"+timestamp+"&"+language+"&"+organisationId+"&"+transactionId+"&"+customerKey+"&"+partnerKey h_mac = hashlib.sha256(sha256string.encode('ISO-8859-15')).hexdigest()
Lähetettävät HTTP-otsikot, huomaa annettu MACHashCalculationAlgorithm-otsikko ja sille arvoksi annettu "SHA256" merkkijonona, joka vaaditaan, että SHA256 MAC-laskenta hyväksytään:
headers = { "Content-Type": "text/plain", "X-Netvisor-Authentication-Sender": sender, "X-Netvisor-Authentication-CustomerId": customerId, "X-Netvisor-Authentication-PartnerId": partnerId, "X-Netvisor-Authentication-Timestamp": timestamp, "X-Netvisor-Authentication-TransactionId": transactionId, "X-Netvisor-Interface-Language": language, "X-Netvisor-Organisation-Id": organisationId, "X-Netvisor-Authentication-MAC": h_mac, "X-Netvisor-Authentication-MACHashCalculationAlgorithm": "SHA256" }
Oliko tästä vastauksesta apua? Kyllä Ei
Send feedback