API-avain on tarkoitettu rajapinta integraatioihin. API-avain on yksilöllinen GUID merkkijono, jonka avulla kontrolloit ketkä ulkopuoliset pystyvät käyttämään yrityksesi tietoja rajapinnan läpi. API-avain siis lisää tietosuojaa ja antaa sinulle mahdollisuuden estää rajapinnan käyttö tarvittaessa. Jos taas itse teet integrointeja, niin API-avaimen avulla näet kenelle olet integraatioita tehnyt eli myöntänyt API-avaimen.
API-avainten hallinta on yritystiedoissa API-avaimet -välilehdellä. Yrityksen omat API-avaimet ovat niitä, jotka luot itse. Voit luoda useita API-avaimia esimerkiksi erilaisia integraatioita varten. Myönnä yritykselle -toiminnolla annat API-avaimen käyttöoikeudet oman yrityksesi lisäksi myös toiselle yritykselle. Näet myöntämäsi API-avaimen kohdasta Myönnetyt API-avaimet.
Saadut API-avaimet ovat sitten niitä, joita yrityksesi käyttää integraatiossa. Voit myös myöntää API-avaimen omalle yrityksellesi. Tarvittaessa voit kopioida avaimen leikepöydälle tai muokata avaimen selitettä kuvan toiminnoilla.
Huomaa, että myös SOAP- ja REST-rajapintojen käyttäminen vaatii käyttäjän tunnistamisen.
Luo rajapintoja varten paikallinen tili ja lisää käyttäjä myös henkilörekisteriin samalla sähköpostiosoitteella, ja anna käyttäjälle tarvittavat oikeudet.
Rajapintojen käyttäminen edellyttää IWS_LOG (Webservice-rajapinnat) -lisenssiä ja mahdollisia muitakin käyttöoikeuksia integraatiotarpeesta riippuen.
Käyttäjätiedon lisäksi rajapinta tarvitsee API-avaimen. API-avain toimii siis vain, jos se on myönnetty jollekin (myös omaan käyttöön tarvitset API-avaimen).
Käydään asia läpi esimerkin kautta. Integraattori Oy tekee kauppapaikkaintegrointeja ja heille tuli uutena asiakkaana Lemonsoft asiakas nimeltään Tukkukauppa Oy.
Integraattori perustaa oman yrityksensä käyttäjähallintaan. Integraattori ei itse käytä Lemonsoftia, joten ympäristö tietoja ei ole. Integraattori luo itselleen uuden API-avaimen ja myöntää Tukkukauppa Oy:lle käyttöoikeuden. Integraattori koodaa integroinnin Tukkukauppa Oy:n API-avaimella ja Tukkukaupan perustamalla paikallisella käyttäjällä.
API-avaimen luonti
Integraattori eli kolmas osapuoli, joka tekee integroinnin Lemonsoftin rajapinnan avulla, tarvitsee API-avaimen.
Integraattori saa API-avaimen joko pyytämällä Lemonsoftilta tai luomalla avaimen itse. Avaimen luonti tapahtuu yritystietojen API-avaimet -välilehdellä Luo uusi avain -toiminnolla. Anna avaimelle kuvaava selite, esimerkiksi ’Kauppapaikat’.
Kun olet luonut API-avaimen, myönnä sen käyttöoikeus yritykselle, jolle teet integraatiota. Voit myöntää API-avaimen usealle eri yritykselle. Tee myöntäminen toiminnolla Liitä valittu avain yritykseen. Toiminto kysyy y-tunnuksen ja yksikkötunnuksen (yksikkötunnuksen näet esimerkiksi etusivun Yritykset -listasta). Yrityksen yhteyshenkilö saa sähköpostin myönnetystä API-avaimesta.
API-avaimen poistaminen
Voit poistaa luomasi API-avaimen Poista avain -toiminnolla. Tällöin yrityksistä, joille olet myöntänyt API-avaimen käyttöoikeuden, poistuu API-avain. API-avaimen poiston jälkeen sen avulla tehdyt integroinnit eivät enää toimi. Poistosta menee sähköposti yrityksen yhteyshenkilölle.
Mikäli olet saanut API-avaimen, voit myös itse poistaa sen. Tällöin se poistuu vain yrityksesi osalta ja sillä tehty integraatio lakkaa toimimasta.
Kun poistat API-avaimen, niin tehdyt integraatiot eivät enää toimi. Vaikka myönnät uuden API-avaimen, täytyy uusi API-avain kertoa integraatiokoodiin ennenkuin rajapinta taas on käytössä.