Olemassa olevan API-integraation käyttöönotto tapahtuu pääosin toisen järjestelmän puolella heidän ohjeistuksensa mukaisesti. Käyttöönotossa tulisi tehdä seuraavat toimenpiteet:
- Salli API-rajapinnan käyttö Procountor-ympäristössä.
- Valitse tai luo Procountorin käyttäjätunnus (API-käyttäjä) , johon integraatio liitetään.
- Varmista, että käyttäjälle on Prcountorissa asetettu integraatiossa tarvittavat käyttöoikeudet.
- Ota integraatio käyttöön toisessa järjestelmässä. Käyttöönotto edellyttää tunnistautumista rajapinnassa. Tunnistautuminen tapahtuu Procountoriin luodulla käyttäjätunnuksella. Jos autentikointimenetelmä vaatii API-avainta, niin se joko muodostetaan Procountorissa tai rajapinnan kautta Login-sivulta edellisessä vaiheessa perustettua käyttäjätunnusta ja salasanaa käyttäen.
1. API-rajapinnan käytön salliminen
Ennen kuin integraatio voidaan ottaa käyttöön, tulisi laskutettavien rajapintojen käyttö sallia Procountorin käyttöasetuksissa. Asetus löytyy ohjelman kohdasta Hallinta > Yrityksen tiedot > Käyttöasetukset > Integraatioasetukset > Salli laskutettavien rajapintojen käyttö.
2. API-käyttäjä
Rajapintayhteys luodaan seuraavalle yhdistelmälle: integraatio + Procountor-ympäristö + käyttäjätunnus. Integraatioon liitettävän käyttäjän tulee olla käyttäjänä siinä ympäristössä, johon integraatio otetaan käyttöön ja käyttäjällä tulee olla ympäristössä käyttöoikeudet rajapinnan kautta tehtäviin toimenpiteisiin.
Jos rajapintayhteys luodaan lähtöjärjestelmästä yrityskohtaisesti, on suositeltavaa luoda erillinen käyttäjätunnus, ns. API-käyttäjä, jotta yrityksen yhteys ei olisi yhdistettynä kenenkään henkilökohtaiseen käyttäjätunnukseen.
Käyttäjä, jolla on oikeudet yrityksen käyttäjähallintaan, voi luoda uuden käyttäjätunnuksen (ns. API-käyttäjän) seuraavasti (Hallinta > Käyttäjät ja käyttöoikeudet > Lisää uusi käyttäjä):
- Nimeä käyttäjätunnus esimerkiksi siten, että syötät etunimeksi yrityksen nimen ja sukunimeksi integroitavan ohjelmiston nimen, API tms.
- Syötä muut pakolliset tiedot (sähköpostiosoite ja puhelinnumero).
- Valitse Käyttäjätunnus ja salasana -kohdasta valinta Toimitan käyttäjälle henkilökohtaisesti.
- Aseta käyttäjälle integraatiossa tarvittavat käyttöoikeudet.
- Valitse Henkilötiedot -kohdasta Älä yhdistä käyttäjää henkilörekisteriin.
- Klikkaa Valmis ja kopioi käyttäjätunnus ja salasana talteen. Huomioithan, että käyttäjätunnusten ja salasanojen säilyttämisen ja toimittamisen suhteen tulee erityisen huolellinen.
3. Käyttöoikeuksien asettaminen
API-käyttäjälle tulisi asettaa käyttöoikeudet niihin toimintoihin, joita integraation kautta suoritetaan. API-käyttäjälle voidaan valita esimerkiksi valmis käyttäjärooli Myynti, jos integraatiossa siirretään myyntilaskuja toisesta järjestelmästä Procountoriin. Jos myyntilaskujen maksutapahtumat haetaan takaisin Procountorista toiseen järjestelmään, tulisi API-käyttäjällä olla lisäksi katseluoikeudet Maksamiseen.
Mikäli integraation kautta haetaan esimerkiksi kirjanpitoaineistoa, käyttäjärooliksi sopisi Johto/Tarkastaja, jolla on oikeudet nähdä kaikki aineisto, mutta ei oikeuksia muokkaukseen.
API-käyttäjää ei suositella pääkäyttäjäksi, koska pääkäyttäjäoikeudet ovat liian laajat.
4. Rajapinnassa tunnistautuminen: autentikointimallit
Tunnistautumisella annetaan integraattorille valtuutus luoda yhteys ympäristöön API-rajapinnan kautta. Olemassa olevan API-integraatiopalvelun käyttöönottamiseksi ja tunnistautumiseksi on olemassa useampi toimintamalli ja käytössä oleva malli riippuu integraation toteuttajasta.
- API-autentikointimalli, jossa tunnistautuminen tapahtuu toisen ohjelmiston API-kirjautumissivun kautta ja jossa käytetään refresh tokenia.
- M2M-autentikointimalli, jossa käytetään tunnisteena API-avainta (API Key). Riippuen toteutuksesta, API-avain luodaan joko itse Procountorin käyttöliittymässä tai tunnistaudutaan toisen ohjelmiston API-kirjautumissivulla, jonka jälkeen integraattori voi noutaa API-avaimen rajapinnan kautta.
Mikäli et ole varma, kuinka palvelu otetaan käyttöön ja mitä mallia siinä käytetään, olethan yhteydessä integraattoriin tarkemman ohjeistuksen saamiseksi.
API-autentikointimalli (refresh token)
API-mallissa käyttäjä ohjataan toisesta järjestelmästä Procountor API-kirjautumissivulle. Kirjautuminen tapahtuu integraatioon liitettävällä Procountorin käyttäjätunnuksella ns. API-käyttäjäjätunnuksella. Kirjautuessa avautuu lista kaikista ympäristöistä, joihin käyttäjätunnus on liitettynä. Valitse listalta se Procountor-ympäristö, johon integraatio liitetään.
Kirjautumisella annetaan integraattorille valtuutus luoda rajapintayhteys valittuun ympäristöön.
M2M-autentikointimalli: API-avain
M2M-mallissa tunnisteena käytettävä API-avain on käyttäjä- ja ympäristökohtainen tunnisteavain, jonka avulla integraattori voi luoda API-rajapinnan kautta yhteyden toisen ohjelman ja Procountorin välille. API-avaimella annetaan integraattorille valtuutus luoda yhteys rajapinnan kautta.
M2M-mallissa on kaksi tapaa, kuinka integraattori voi vastaanottaa API-avaimen.
A) Käyttäjä voi itse luoda API-avaimen Procountorin käyttöliittymässä ja toimittaa sen eteenpäin. Toisessa järjestelmässä voi esimerkiksi olla kenttä, johon API-avain tulee syöttää. Luovuttaessaan API-avaimen, käyttäjä antaa integraattorille valtuutuksen luoda yhteys.
B) Integraatiossa on voitu myös ottaa tunnistautumisessa käyttöön API-kirjautumissivu, jolloin kirjautumisella annetaan integraattorille valtuutus luoda yhteys ja noutaa API-avain rajapinnan kautta.
A) API-avaimen muodostaminen Procountorin kautta
Ympäristön käyttäjä, jolla on ympäristössä täydet oikeudet yrityksen käyttäjähallintaan voi valita, mille käyttäjätunnukselle API-avain luodaan.
API-avain luodaan valitsemalla oikean yläkulman Henkilöhahmo -kuvakkeesta API-Avaimet. Paina avautuvalla näytöllä Hakutulokset -osion Uusi API-avain-painiketta. Tässä vaiheessa sinulla tulee olla integraattorilta saatu integraation käyttämä asiakasohjelmiston tunniste, integraattorilla usein nimellä Client ID-tunniste, jolla muodostettava API-avain linkitetään yhteen ympäristöön kuuluvaan käyttäjätunnukseen, integroitavaan ohjelmaan ja Procountor-ympäristöön.
- Valitse Käyttäjä-valikosta käyttäjätunnus, johon haluat integraation liittää.
- Ympäristönä näkyy se ympäristö, johon olet integraation API-avainta muodostamassa.
- Syötä Asiakasohjelmiston tunniste-kenttään integraattorilta saamasi tunniste (eli Client ID), joka on usein sanallinen ja muotoa "xxxxxxxClient".
- Klikkaa Muodosta-painiketta.
- Klikkaa Kopioi API-avain leikepöydälle-painiketta.
- Klikkaa OK -painiketta.
- Toimita API-Avain integraattorille sopimallanne tavalla / integraattorin ohjeistuksen mukaisesti.
B) API-avaimen luominen API-kirjautumissivun kautta
- Käyttäjä ohjataan toisesta järjestelmästä Procountor API-kirjautumissivulle.
- Kirjautuminen tapahtuu integraatioon liitettävällä Procountorin käyttäjätunnuksella ns. API-käyttäjäjätunnuksella.
- Kirjautuessa avautuu lista kaikista ympäristöistä, joihin kirjautuneen käyttäjätunnus on liitettynä.
- Valitse listalta se Procountor-ympäristö, johon integraatio liitetään.
- Kirjautumisen jälkeen integraatiossa noudetaan API-avain automaattisesti rajapinnan kautta.