Tekniset rajapinnat ja tiedostosiirtotoiminnot

Versio 6

    Visma Sign -palvelun voi liittää useilla tavoilla omiin ohjelmistoihin, verkkopalveluihin tai muihin teknisiin ympäristöihin. Alla kuvatut menetelmät ovat toisistaan riippumatta käytettävissä kehityksessä asiakas- ja kumppaniympäristöissä. Kumppaneille on käytettävissä kaikki Sign-asiakkaillakin käytössä olevat teknologiat sekä lisäksi Partner API, jota suorat Sign-asiakkaat eivät voi käyttää.

     

    REST-API v1

    Tämä on ensisijainen tapa liittyä palveluun. Tekninen kuvaus, käyttötapaohjeistus ja PHP-esimerkkikoodit löytyvät sivulla Visma Sign API v1.

    Sign-selainpalvelu käyttää tätä rajapintaa, ja kehitystyö kohdistuu ensisijaisesti tähän.

     

    Tällä hetkellä kehitys ja testaus tulee tehdä tuotantopalvelun rajapintaa vasten. Vuoden 2017 aikana tulee käyttöön avoin testiympäristö, johon voidaan jatkossa tehdä testaukset. Harkittavana on muihin yleisiin toteutusympäristöihin laaja koodiesimerkki tai kirjasto. Toiveet ja palautteet voi osoittaa kumppanitukeen.

     

    Rajapintaa voidaan käyttää suoraan minä tahansa organisaationa, jonka API-avaimet ovat käytettävissä. Esimerkkiksi kumppanin palvelussa on valmis integraatio Sign-alustaan, jonka asiakas itse aktivoi asettamalla Sign-tuesta pyytämänsä API-avaimet kumppanin palveluun. Tilanne vastaa allekirjoitustapahtumien osalta sitä, että asiakas on rekisteröitynyt suoraan palveluun, mutta laskutus / kumppanituloutus kulkee asiakkaan kumppaniasiakasstatuksen kautta. Tässä toteutusmallissa on erittäin tärkeää varmistaa, että asiakkaiden rekisteröityminen palveluun tapahtuu kumppanin affiliate-koodin sisältävällä linkillä tai asiakas käyttää rekisteröityessään kumppanin affiliate-koodia. Mikäli rekisteröinnissä ei käytetä affiliate-koodia, eivät asiakkaan allekirjoitustapahtumat yhdisty kumppaniin.

     

    Toinen tapa käyttää rajapintaa on asioida suoraan kunkin asiakasorganisaation Sign-alustaan kumppanin Partner API-tunnuksilla. Asiakasorganisaation Sign-alustan rajapintaa käytettäessä tulee ehdottomasti käyttää kumppanirajapinnan ohjeen using-client-organization-api-v1-endpoints kuvattua as_organization -parametria.

     

    REST Partner API v1

     

    Jälleenmyyntiroolissa toimiville kumppaneille, joilla on oman alustansa osana yrityskäyttäjien hallinta, suunnattu rajapinta Sign-käyttäjäorganisaatioita koskevien hallintatoimenpiteiden tekemiseen. Tekninen kuvaus, käyttötapaohjeistus ja PHP-esimerkkikoodi löytyvät ohjesivulta: https://www.onnistuu.fi/api/docs/v1/partners/. Kumppanirajapinta on salasanasuojattu eikä sitä saa jakaa edelleen. Pyydä salasana kumppanituesta: kumppanit.sign@visma.com.

     

    Asiakasorganisaatiota perustettaessa kumppanirajapinnan kautta on ehdottomasti käytettävä kumppanin omaa affiliate-koodia, jotta asiakkaan tekemät allekirjoitustapahtumat voidaan yhdistää kumppaniin.

     

    API v0[.20] (legacy)

     

    Syksyyn 2016 saakka käytettävissä oli edellinen versio webservice-rajapinnasta ja tätä ei tule käyttää uusissa toteutuksissa, vaan tulee käyttää korvaava ratkaisua API v1. Rajapintaa ei enää kehitetä, pois lukien mahdolliset tietoturvakorjaukset. Kuvaus löytyy osoitteesta: https://allekirjoitus.visma.fi/download/visma_sign-api.pdf.

     

    Rajapinnan poistuminen käytöstä ilmoitetaan hyvissä ajoin etukäteen.

     

    SFTP+XML API (legacy)

     

    Ympäristöissä, joista ei voida kutsua REST-rajapintoja, voidaan käyttää tiedostonsiirtorajapintaa myös allekirjoituskutsujen tekemiseen. SFTP+XML-rajapinta ei sisällä kaikkea REST-rajapinnan toiminnallisuutta, eikä sitä kehitetä kuin välittömien asiakastarpeiden perusteella. Rajapintaa tulee käyttää vain erityisesti perustelluissa tilanteissa, joissa toiminnallisuuden rajoittuminen perustapauksiin on hyväksyttävää, ja REST-rajapinnan käyttö ei ole milllään tavoin mahdollista.

     

    SFTP+XML API:n käyttöönotto vaatii Sign-operointitoimenpiteen jokaista uutta asiakastiliä kohden. Sitä varten pitää toimittaa kumppanitukeen SFTP-salaisuudet (tunnus, julkinen avain) ja palvelintiedot erikseen sovittavalla tavalla.

     

    Ohjaustiedot XML-tiedostona ja allekirjoitettava asiakirja PDF-tiedostona tallennetaan asiakkaan SFTP-palvelimelle lähtevien kansioon. Sign-palvelu noutaa tiedostot määrävälein ja toteuttaa kutsut tai muut toimenpiteet. Lopuksi Sign tallentaa valmiin asiakirjan ja päivitetyt metatiedot SFTP-palvelimelle asiakkaan noudettavaksi. Kuvaus, schemat ja esimerkit löytyvät osoitteesta Onnistuu.fi SFTP+XML API .

     

    Rajapinnan poistuminen käytöstä ilmoitetaan hyvissä ajoin etukäteen, mutta nykytoteutusten tuki säilynee vielä pitkään. Korvaavaa tiedostopohjaista ratkaisua ei ole suunnitteilla.

     

    WebDAV

     

    WebDAVia käytetään ainoastaan niissä tilanteissa, jos käytössä on Sharepoint tai muuta WebDAV.

    Toiminto otetaan käyttöön lisäämällä WebDAV-resurssin URL-osoite Sign-operointitoimenpiteenä asiakasorganisaation tietoihin Sign-alustassa. Mahdolliset pääsynhallinnan järjestelyt tulee sopia samassa yhteydessä kumppanituen kautta.

     

    Allekirjoitusten keräämistavasta (session sisäinen allekirjoitus tai allekirjoituskutsu/-t) riippumatta valmiit asiakirjat voidaan kopioida Sign-alustasta asiakkaan WebDAV-palvelimelle. Asiakkaan WebDAV-resurssissa tulee olla merkilleen samalla tavoin kirjoitetut alikansiot kuin Sign-alustan dokumenttiarkiston kansiot, jotta siirto toimii.

     

    WebDAV-hallinnan kehittämisestä ei ole päätöksiä. Tarpeet ja palautteen voi osoittaa kumppanitukeen: kumppanit.sign@visma.com.

     

    SFTP tiedostonsiirto

     

    Erikseen perustellusta syystä voidaan myös ottaa käyttöön asiakaskohtainen toiminto, jossa valmistuneet asiakirjat kopioidaan Sign-alustasta asiakkaan SFTP-palvelimelle. Ensisijainen tapa noutaa valmistuneet tiedostot on REST API, joten SFTP-siirtoa käytetään vain tilanteessa jossa API-käyttö ei ole mahdollista.

     

    Toiminto otetaan käyttöön sopimalla järjestelyt ja SFTP-salaisuudet kumppanituen tai kumppanivastaavan kanssa.

     

    Sähköpostin erityispiirteitä

     

    Allekirjoitusten valmistuttua asiakirja voidaan ohjaustiedoista riippuen jakaa sähköpostin liitteenä kutsujalle ja/tai allekirjoittajille.

     

    Asiakirjan luonteesta riippuen voi olla tarpeen suojata kutsujaorganisaation ja Sign-sähköpostipalvelimen välinen liikenne TLS-suojauksella. Sign-palvelusta lähetetään sähköpostia asiakasorganisaation nimissä, ja viestit sisältävät linkkejä sekä liitetiedostoja. Jotta mahdollisimman pieni osuus viesteistä jää erilaisiin roskapostisuodattimiin, on mahdollista käyttää SPF-asetuksia asiakasorganisaation palvelimilla.

     

    Tällä hetkellä lähettävänä osoitteena on onnistuu.fi / 185.20.137.231, joka tulee lisätä asiakasorganisaation SPF-tietueisiin.

     

    Ota yhteys kumppanit.sign@visma.com järjestelyjä varten.