Netvisorin rajapinnan tietoturva on varmistettu sekä ohjelmistorajapintatunnuksien että jokaisen pyynnön yksilöivän tunnisteen avulla.
Jotta tietoa saadaan siirrettyä Netvisorin rajapinnan yli, tarvitaan:
- Käyttäjän ohjelmistorajapintatunnukset
- Ohjelmistokumppanin rajapintatunnukset
Kun Netvisorin rajapintaan lähetetään pyyntöjä, tulee jokaisessa pyynnössä olla määrätyt http-otsikot, joista tarkempi listaus alla. Http-otsikot näkyvät myös alla olevassa kuvassa oikealla puolella:
Pyynnön oikeellisuus varmistetaan rajapinnassa SHA256-laskennalla muodostettavalla MAC-tunnisteella. Otsikossa X-Netvisor-Authentication-MAC annettava SHA256-arvo lasketaan käyttäen kaikkia kuvassa vasemmalla lueteltuja tietoja. Rajapintaan lähetettävien pyyntöjen otsakkeissa ei ole mukana ohjelmistokumppanin ja käyttäjän yksilöiviä avaimia, nämä tarvitaan kuitenkin SHA256-laskentaa varten. MAC-tunniste lasketaan erikseen jokaiselle rajapintaan lähetettävälle pyynnölle. Jos rajapintaan on lähetetty aiemmin pyyntö samalla transaktiotunnisteella, rajapinta antaa virheen.
Python esimerkki MAC-koodin ja HTTP-otsikoiden muodostukseen
MAC -laskenta, SHA256 laskentaa käyttäen tässä linkissä.
Tunnistautumisen HTTP-otsikot selitteineen:
X-Netvisor-Authentication-Sender
Integraation vapaamuotoinen nimi. Mikäli kumppanilla on useampia järjestelmiä liitettynä Netvisoriin, jokainen integraatio tulee nimetä yksiselitteisesti. Tämä tieto helpottaa Netvisorin tukea ja tekniikkaa selvitystilanteissa.
X-Netvisor-Authentication-CustomerId
Asiakasyrityksen käyttäjän ohjelmistorajapintatunnukset. Tämä on käyttäjäkohtainen tunnus.
Testiympäristössä ohjelmistorajapintatunnuksen luo ohjelmistokumppanin työntekijä
Tuotannossa tunnuksen luo integraation käyttöönsä ottavan yrityksen Netvisor-käyttäjä. Hän toimittaa luodun rajapintatunnuksen ja integraatiokäyttäjän yksilöivän avaimen integraation toteuttajalle tai lisää itse tunnukset integraation asetuksiin.
Ohjeet ohjelmistorajapintatunnusten luomiseen tästä linkistä.
X-Netvisor-Authentication-PartnerId
Kumppanitunnus. Netvisorin tuki luo kumppanille tunnuksen ja avaimen integraatiokohtaisesti. Tunnukset toimitetaan kumppanille sähköpostitse. Mikäli kumppanilla on useampia järjestelmiä liitettynä Netvisoriin, jokaiselle integraatiolle luodaan omat kumppanitunnukset
X-Netvisor-Authentication-Timestamp
Integraatiopyynnön aikaleima ansi-muodossa kellonajan kanssa, GMT+0. Esim. 2023-05-04 12:00:00.000
X-Netvisor-Interface-Language
Kielitieto rajapinnalle. Vastaussanomien kielituki, joka vaikuttaa lähinnä virheviesteihin. Tiedon tulee olla ISO-3166 –muodossa. Mahdolliset kielet ovat FI/SE/EN.
X-Netvisor-Organisation-ID
Kohdeyrityksen y-tunnus. Y-tunnus määrää yrityksen, johon pyynnöt kirjautuvat tai jonka tietoja haetaan. Yrityksen Netvisor-käyttäjällä, jonka ohjelmistorajapintatunnuksia käytetään integraatiossa, tulee olla oikeus tähän yritykseen.
X-Netvisor-Authentication-TransactionId
Pyynnön yksilöivä tunniste. Arvon tulee olla jokaisessa pyynnössä eri. Mikäli kumppani on lähettänyt aikaisemmin aineistoa käyttäen tätä tunnistetta, pyyntö hylätään ja palautetaan REQUEST_NOT_UNIQUE –virhe. Tunniste tarkistetaan kumppanitunnustasolla eli samaa tunnistetta ei voi käyttää eri asiakkailla.
X-Netvisor-Authentication-MACHashCalculationAlgorithm
Jotta rajapinta ottaa vastaan SHA-256 tiivisteen, tulee tieto antaa otsikoissa. Arvoksi annetaan SHA256.
X-Netvisor-Authentication-UseHTTPResponseStatusCodes
X-Netvisor-Authentication-UseHTTPResponseStatusCodes. Suosittelemme kaikille kumppaneillemme lisäämään sen integraatiototeutuksen kaikkiin pyyntöihin jo nyt mikäli rajapintatoteutus sen sallii. Headerin voi aktivoida asettamalla arvon 1 headerille X-Netvisor-Authentication-UseHTTPResponseStatusCodes. Tämä mahdollistaa oikeiden statuskoodien, kuten 400, 401, 403, 500, ja 200, käytön rajapinnan vastauksissa:
200 = OK
400 = Virheellinen data
401 = Autentikointi epäonnistui
403 = Palvelun käyttövirhe
500 = Sisäinen palvelinvirhe
X-Netvisor-Authentication-MAC
MAC-koodilla tarkistetaan pyynnön lähettäjä. Koodin laskennassa käytetään kaikkia yllämainittuja HTTP-otsikoita sekä integraatiokumppanille toimitettua yksilöivää avainta ja käyttäjän ohjelmistorajapintatunnuksen yksilöivää avainta. Tunnusten avaimia ei kuitenkaan toimiteta HTTP-otsikoissa. Niitä käytetään pelkästään MAC-koodin laskentaan ja tarkastukseen. MAC-koodi muodostetaan yhdistämällä alla olevan taulukon tiedot yhdeksi merkkijonoksi, josta lasketaan SHA256-tarkistesumma. Tietoja yhdistettäessä tietojen välissä käytetään &-merkkiä; URI-osuus pitää olla sama minne pyyntö lähetetään mukaan lukien isot ja pienet kirjaimet.
Laskenta onnistuu yhdistämällä taulukon tiedot seuraavasti
Tiedoista muodostettu merkkijono:
https://isvapi.netvisor.fi/accounting.nv&ClientName&Integraatiokayttajan tunnus&2023-05-04 12:00:00.000&FI&1967543-8&123456 &7cd680e89e880553358bc07cd28b0ee2&07f94228d149a96b2f25e3edad55096e
Laskemalla merkkijonosta SHA256-tarkistesumma, saadaan MAC-koodiksi:
67fec485ef881ee00ffe4b926f8d9aebaee973ba0c8f2cadec51528026827edb
HUOM! Jos käyttämäsi URI sisältää erikoisemerkkejä tai ääkkösiä, se tulee enkoodata ISO-8859-1 -merkistöllä, jotta MAC lasketaan oikein ja rajapinta tunnistaa sen.Oliko tästä vastauksesta apua? Kyllä Ei
Send feedback