Lemonsoftin web service -rajapinnat

Lemonsoftissa on käytettävissä kolme erilaista web service -rajapintaa:

Käyttäjälähtöinen SOAP

Käyttäjälähtöinen SOAP API-avaimella

REST-rajapinta API-avaimella

Ennen versiota 2021.5 integraatiot on tyypillisesti toteutettu käyttäjälähtöisellä SOAP-rajapinnalla. Vanha datalähtöinen SOAP-rajapinta on jäänyt jo aiemmin pois käytöstä. Myös SOAP-rajapinnan tuki on loppunut 31.12.2023 ja uudet toteutukset on tehtävä REST-rajapinnalla.

REST-rajapinta

REST-tyyppinen web service -rajapinta on uusi ja aktiivisessa kehityksessä oleva Lemonsoftin integraatiorajapinta, joka laajenee asiakkaittemme tarpeiden mukaan myös tulevaisuudessa. Pyrimme kehittämään REST-rajapintaa nimenomaan integraatiotarpeiden näkökulmasta, eikä niinkään perinteisellä tavalla ERP-järjestelmän näkökulmasta. Tämä tuo joustavuutta integraatioiden toteuttamiseen ja parantaa integraation käytön tuottavuutta.

Rajapintojen elinkaaret

Tuemme rajapintoja seuraavasti:

Rajapinta	Huomioita	Tuen päättyminen
Datalähtöinen SOAP	Ei enää tueta.	31.12.2020
Käyttäjälähtöinen SOAP	Ei enää tueta.	31.12.2021
Käyttäjälähtöinen SOAP API-avaimella	Ei kehitetä uutta.	31.12.2023
REST-rajapinta API-avaimella	Aktiivisen kehityksen kohde. Suositellaan uusiin projekteihin ja olemassa olevien integraatioiden uudistuksiin.

Lisenssit ja API-avain

Lisenssi IWS_LOG avaa SOAP-tyyppisen rajapinnan kaikki toiminnot. Asiakkaamme ovat esittäneet meille toiveita rajapinnan käyttöoikeuksien tarkemmasta rajaamisesta, jonka takia olemme lisänneet REST-rajapinnan käyttöoikeuksiin mukaan ohjelmalisenssin, joka rajaa käyttöoikeuden ko. ohjelman käyttämiin tietoihin. REST-rajapinnan käyttöoikeus vaatii IWS_LOG-lisenssin.

Huomaa, että myös prosessikäyttäjällä tulee olla IWS_LOG-lisenssi. SOAP- ja REST-rajapintoihin lisätty API-avain yksilöi Lemonsoftin rajapintaan integroidun sovelluksen. Tämä parantaa tietojen siirron jäljitettävyyttä ja parantaa tietoturvaa. API-avaimesta voit lukea tarkemmin https://lemondoc.atlassian.net/wiki/spaces/KYTTJHALLI/pages/318570497

Muutokset olemassa oleviin integraatioihin

Olemassa olevaan SOAP-rajapintaa käyttävään integraatioon tulee tehdä muutoksia. Viestin rakenne on muuttunut ja lisäksi tarvitset API-avaimen rajapinnan käyttämistä varten. Myös sanomaliikenne on jatkossa pakotetusti suojattua.

SOAP Autentikointi
login-kutsussa tarvitaan API-avain, jonka annat ApiKey-parametriksi. Perusperiaate on ennallaan.
Autentikointi tapahtuu rekisteröimälläsi sähköpostitunnuksella ja sen salasanalla.
Palveluun on ensin muodostettava yhteys, jolloin saadaan Session ID, jota ohjelma käyttää jatkossa tunnistautumiseen.
Muilta osin rajapinnan käyttö tapahtuu kuten aiemmin. Rajapinnan vaatima käyttäjä on käyttäjähallinnassa perustamasi paikallinen käyttäjä. Muut tunnistautumistavat eivät ole mahdollisia, koska rajapinnan täytyy tietää käyttäjän salasana.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:tem="http://tempuri.org/" 
xmlns:lem="http://schemas.datacontract.org/2004/07/Lemonsoft.LemonsoftServiceLibrary.User">
<soapenv:Header/>
<soapenv:Body>
<tem:LogIn>
<!--Optional:-->
<tem:oLogInInfo>
<!--Optional:-->
<lem:ApiKey>Api-avain</lem:ApiKey>
<!--Optional:-->
<lem:CompanyDatabase>LemonDBx</lem:CompanyDatabase>
<!--Optional:-->
<lem:Password>PASSWORD</lem:Password>
<!--Optional:-->
<lem:UserName>example@example.com</lem:UserName>
</tem:oLogInInfo>
</tem:LogIn>
</soapenv:Body>
</soapenv:Envelope>

SOAP Viestin rakenne

Soap-sanoman rakenne säilyy ennallaan. Parametreistä tulee huomioida, että ovat alkuperäisessä järjestyksessä. Rajapinnan julkaiseman WSDL-dokumentaation avulla saat muodostettua rakenteet.

<soapenv:Envelope 
xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/ 
xmlns:tem=http://tempuri.org/ 
xmlns:lem=http://schemas.datacontract.org/2004/07/Lemonsoft.LemonsoftServiceLibrary.Proxy>
<soapenv:Header/>
<soapenv:Body>
<tem:SaveCustomer>
<tem:strSessionID> SESSION_ID </tem:strSessionID>
<tem:oCustomerProxy><lem:Customer_name1>Testinimi</lem:Customer_name1>
<lem:Customer_number>10</lem:Customer_number>
</tem:oCustomerProxy>
</tem:SaveCustomer>
</soapenv:Body>
</soapenv:Envelope>

API-avain

Löydät lähdekoodiesimerkkejä API-avaimen käyttämisestä tästä (https://lemondoc.atlassian.net/wiki/spaces/KYTTJHALLI/pages/392790033)

TLS salausprotokollan käyttö

Lemonsoftin Alustapalvelussa on aina käytetty suojattuja yhteyksiä. Uuden version myötä pakotamme asetuksen myös paikallisasennuksiin. Mikäli et jostain syystä voi käyttää HTTPS-protokollaa, saat asiakaspalvelustamme ohjeen, jolla voit kytkeä salauksen pois päältä.

Muutokset koskevat web.config -tiedostoa. Integraation toteutukseen tämä muutos ei siis vaikuta.

ServiceMetadata:

Vanha:

<serviceMetadata httpGetEnabled="True" />

Uusi:

BasicHttpBindingConfiguration

Vanha:

Uusi:

Rajapintojen tukeminen

Jos tarvitset konsultointia rajapintaan tehtävien muutosten osalta, voit olla yhteydessä sähköpostitse asiakaspalveluumme suoraan rajapintakonsultille: Markus Litmanen (markus.litmanen@lemonsoft.fi).