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ä. Tämä onnistuu ohjelman kohdassa Hallinta > Yrityksen tiedot > Käyttöasetukset lisäämällä valinnan kohtaan Salli laskutettavien rajapintojen käyttö.
- 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. Henkilökohtaisiin käyttäjätunnuksiin saattaa olla liitettynä turhan kattavat käyttöoikeudet. Lisäksi jos käytetään henkilökohtaista tunnusta ja käyttäjä vaihtaa salasanaansa tai työpaikkaa ja poistuu yrityksen Procountor-ympäristöstä, lakkaa integraatio toimimasta.
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.
Ostolaskujen käsitteleminen
Ostolaskut voidaan hakea toiseen järjestelmään ostolaskujen projekteille kohdistamista varten.
Jotta ostolaskuja voidaan käsitellä (asiatarkastaa) rajapinnan kautta, tarvitaan seuraavat oikeudet:
- Ostot > Uusi ostolasku > Katselu oikeudet
- Ostot > Hae laskut > Kaikki oikeudet
- Ostot > Asiatarkastaminen > Kaikki oikeudet
- Ostot > Toimittajarekisteri > Kaikki oikeudet
Laskujen projekteille kohdistamista varten tarvitaan seuraavat oikeudet:
- Hallinta > Kirjanpidon perustiedot > Kaikki oikeudet
Jos ostolaskut hyväksytään toisessa järjestelmässä tarvitaan myös seuraavat oikeudet:
- Maksuliikenne > Hyväksyminen > Kaikki oikeudet
Ostolaskujen maksaminen
Ostolaskujen maksaminen tapahtuu Procountorissa. Ostolaskut palautetaan Procountoriin maksamista varten, sen jälkeen kun ne on kohdistettu projekteille. Henkilö, joka maksaa ostolaskuja, maksaa ostolaskut omilla henkilökohtaisilla käyttäjätunnuksilla, jotta käyttäjäleiman auditoinnista nähdään kuka ostolaskun on maksanut. Maksaminen tehdään omilla henkilökohtaisilla tunnuksilla käyttäen henkilökohtaista Procountor Avainta. Maksaja tarvitsee seuraavat maksamisen oikeudet:
- Ostot > Uusi ostolasku > Katselu oikeudet
- Ostot > Hae laskut > Kaikki oikeudet
- Maksuliikenne > Maksaminen > Kaikki oikeudet
- Maksuliikenne > Maksettu muualla > Kaikki oikeudet
Salli vain M2M-kirjautuminen APIin
M2M autentikointimallissa on mahdollista rajoittaa API-käyttäjän Procountor käyttöliittymän käyttöä vain integraation kautta:
- Rajoitukset käyttäjäoikeuksiin > Salli vain M2M-kirjautuminen Apiin > Käytössä.
Suosittelemme kyseisen rajoituksen käyttöönottamista M2M autentikointimallissa. Huom! jos suosituksista huolimatta käytät integraation käyttämisessä käyttäjätunnuksena henkilökohtaista käyttäjätunnusta, älä koskaan laita tätä rajoituista päälle, koska muuten et pääse kirjautumaan Procountor käyttöliittymään.
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.
- 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.
- API-autentikointimalli, jossa tunnistautuminen tapahtuu toisen ohjelmiston API-kirjautumissivun kautta ja jossa käytetään refresh tokenia.
Mikäli et ole varma, kuinka palvelu otetaan käyttöön ja mitä mallia siinä käytetään, olethan yhteydessä integraattoriin tarkemman ohjeistuksen saamiseksi.
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.
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.
Tässä mallissa on käytössä "refresh token", jolla haetaan uusia access tokeneita. Se on aina voimassa 180 päivää, eli autentikointi on sen vuoksi uusittava tietyin väliajoin. Uudelleenkirjautuminen tehdään integraattorin ohjeiden mukaisesti.
Api-avaimet ja aktiiviset integraatiot ympäristössä
Procountorin API-avaimet -näkymällä, jonne päästään oikean yläkulman Henkilöhahmo -kuvakkeesta, nähdään API-client avaimet, jotka on luotu joko M2M-autentikoinnilla tai Procountor käyttöliittymässä. API-avain ei vanhene, se voidaan toki poistaa käyttöliittymän kautta.
Jos API-client avain on jo luotu käyttäjän ympäristöön, se palauttaa saman avaimen jos käyttäjä yrittää luoda uutta avainta samalle API-clientille samassa Procountor-ympäristössä.
API-Client istunnot nähdään valitsemalla oikean yläkulman Henkilöhahmo -kuvakkeesta API client istunnot. Procountor-käyttäjä voi nähdä kaikkien muiden käyttäjien luomat API-avaimet ja istunnot samaan ympäristöön, jos käyttäjällä on pääkäyttäjä oikeudet ympäristöön. Näkymät näyttävät ainoastaan sillä hetkellä aktiiviset integraatiot. Takautuvasti ei saa tietoa, mikäli jokin integraatio on ollut tai on satunnaisessa käytössä. Client istunnto voidaan keskeyttää painamalla Keskeytä istunto painiketta mikäli clientin käytölle ei ole tarvetta.