API-rajapinta yrityksen järjestelmiin: kolme tasoa ja niiden ylläpitovelka

Kahden järjestelmän yhdistämiselle on kolme tasoa, ja ne eroavat eniten ylläpidon hinnassa. Tässä on jokaisen taso rakennusvaiva, mikä sen rikkoo ja montako tuntia vuodessa se syö, sekä laskelma jolla päätät kannattaako se.

Julkaistu 1.9.2026 · Päivitetty 11.9.2026

Mustafa Tarabya, VectaAI:n perustaja, DT Nova Tmi. Yhteystiedot ja suora numero.

Lyhyt vastaus: Kaksi yrityksen järjestelmää saa juttelemaan keskenään kolmella tasolla: tiedostosiirrolla (CSV), toimittajan valmiilla vakioliittymällä tai räätälöidyllä API-integraatiolla. Ne eroavat rakentamisen hinnassa, mutta vielä enemmän ylläpitovelassa: jokainen rajapinta hajoaa joskus, ja joku maksaa korjauksen. Päätössääntö on yksi jakolasku: laske paljonko käsityötä kuluu vuodessa (minuutit viikossa × 52 ÷ 60), vähennä siitä integraation vuosittainen ylläpito ja katso, kuinka monessa vuodessa rakentaminen maksaa itsensä takaisin. Alle noin 20 minuutin viikkotyöhön ei kannata rakentaa omaa rajapintaa.

"Voitaisiinko me saada nämä kaksi järjestelmää puhumaan keskenään?" on kysymys, joka esitetään yleensä siinä vaiheessa, kun joku on kopioinut samoja rivejä paikasta toiseen puoli vuotta. Vastaus on melkein aina kyllä. Oikea kysymys on, millä tasolla ja mitä se maksaa — ei vain kerran, vaan joka vuosi.

Tällä sivulla käydään läpi ne kolme tasoa selkokielellä, mistä kunkin hinta muodostuu, mikä ne rikkoo ja kuinka monta tuntia vuodessa ne tyypillisesti syövät. Lopussa on päätössääntö, jonka voi laskea omilla luvuilla viidessä minuutissa.

Mikä API-rajapinta on selkokielellä?

API-rajapinta on ohjelman palvelutiski. Ihmiselle järjestelmä näyttää käyttöliittymän, jossa on nappeja ja lomakkeita. Toiselle ohjelmalle se näyttää rajapinnan, jossa on täsmälleen määritellyt pyynnöt: "anna tilaus numero 4711", "luo uusi asiakas näillä tiedoilla", "merkitse lasku maksetuksi". Rajapinta ei ole ihmisen luettavaksi tarkoitettu, joten se on nopea ja tarkka.

Suurin osa nykyisistä rajapinnoista on tyyliltään REST ja siirtää tiedon JSON-muodossa. JSON on tekstimuotoinen tapa esittää tietoa nimi–arvo-pareina, ja sen voi avata tekstieditorissa. Käytännön merkitys sinulle on tämä: jos toimittaja sanoo "meillä on REST-rajapinta ja JSON", työ on todennäköisesti suoraviivaista. Jos vastaus on jokin vanhempi tai talon oma formaatti, se ei ole este, mutta työtunteja kertyy enemmän.

Tunnistautuminen tarkoittaa sitä, miten järjestelmä tietää kuka pyynnön lähettää. Yleisin tapa on avain tai token, eli pitkä salasanaa muistuttava merkkijono. Osassa palveluista token vanhenee esimerkiksi vuoden välein, ja jos kukaan ei ole vastuussa sen uusimisesta, integraatio lakkaa toimimasta ilman varoitusta. Tämä on yksi tavallisimmista syistä siihen, että "se toimi ennen".

Webhook vastaan kysely. Kyselyssä eli pollauksessa integraatio kysyy toiselta järjestelmältä säännöllisin väliajoin, onko uutta. Webhookissa toinen järjestelmä ilmoittaa itse heti kun jotain tapahtuu. Webhook on nopeampi ja kevyempi, mutta vaatii että sinulla on osoite, johon ilmoitus voi tulla, ja että käsittelet myös epäonnistuneet toimitukset. Pollaus on tyhmempi mutta kestävämpi. Pienessä yrityksessä pollaus riittää lähes aina, jos ei tarvita sekuntien tarkkuutta.

Kolme tasoa: CSV, vakioliittymä, oma rajapinta

Taso 1: tiedostosiirto. Toisesta järjestelmästä otetaan CSV- tai Excel-tiedosto ja se ajetaan sisään toiseen. Käsin tehtynä tämä ei maksa mitään paitsi työaikaa. Ajastettuna — skripti hakee tiedoston, siivoaa sen ja vie sisään joka yö — se on halvin oikea automaatio, joka on olemassa. Heikkous: tiedosto kertoo vain tilanteen sillä hetkellä, virheet huomataan vasta jälkikäteen, ja jos joku muuttaa sarakejärjestystä, kaikki menee pieleen hiljaa.

Taso 2: valmis liittymä. Moni ohjelmisto myy valmiita liittymiä yleisimpiin naapurijärjestelmiin: kassa kirjanpitoon, verkkokauppa varastoon, CRM sähköpostiin. Käytännössä ostat kytkennän, jota et itse ylläpidä. Tämä on lähes aina paras vaihtoehto silloin kun sellainen on olemassa ja se tekee sen mitä tarvitset. Heikkous: se tekee juuri sen mitä toimittaja on päättänyt, ei senttiäkään enempää, ja jos toimittaja lopettaa liittymän tuen, olet ilman vaihtoehtoja.

Taso 3: oma rajapintaintegraatio. Rakennetaan koodi, joka puhuu molempien järjestelmien rajapintoja ja siirtää tiedon juuri sinun sääntöjesi mukaan. Tämä on ainoa taso, joka taipuu omaan prosessiin. Se on myös ainoa taso, jossa ylläpitovastuu on täysin sinulla — tai sillä, jonka kanssa siitä on sovittu kirjallisesti.

Ylläpitovelka: mitä integraatio maksaa rakentamisen jälkeen?

Integraation ylläpitovelka on se tuntimäärä, jonka rajapinta syö vuodessa sen jälkeen kun se on rakennettu, ja juuri sitä lukua ei kysy melkein kukaan. Rakentamisen hinta kysytään aina, mutta ylläpito ratkaisee kolmen vuoden kokonaishinnan. Suuruusluokat ovat kokemusperäisiä: ajastettu CSV-siirto vie tyypillisesti 2–6 tuntia vuodessa, valmis liittymä 1–4 tuntia ja oma API-integraatio 4–12 tuntia. Käsin tehty CSV ei vie ylläpitoa lainkaan, koska koko työ on käsityötä joka viikko. Nämä ovat suuruusluokkia, eivät lupauksia — oma lukusi riippuu siitä, kuinka usein naapurijärjestelmäsi muuttuvat ja kuinka hyvin niiden versiopolitiikka on kerrottu etukäteen. Alla kaikki kolme tasoa on samassa taulukossa yhdessä sen kanssa, mikä ne käytännössä rikkoo ja kuka korjauksesta vastaa.

Taso	Rakentaminen	Mikä sen rikkoo	Ylläpito vuodessa	Kuka vastaa
CSV käsin	0 h	Ei mikään — mutta virhe syntyy joka kerta, kun ihminen väsyy	Sama kuin käsityö: minuutit × 52	Sinä, joka viikko
CSV ajastettuna	Muutamia tunteja	Sarakkeen lisäys tai nimen muutos, muuttunut päivämäärämuoto, tiedosto ei ilmesty	2–6 h	Skriptin tekijä
Valmis liittymä	Käyttöönotto, tyypillisesti tunteja	Toimittajan versiopäivitys, hinnaston tai paketin muutos, tuen lopetus	1–4 h	Ohjelmistotoimittaja
Oma API-integraatio	Kymmeniä tunteja	Rajapinnan versiovaihto, uusi pakollinen kenttä, tokenin vanheneminen, kutsurajan ylitys	4–12 h	Se, jonka kanssa sovittu — kirjaa tämä sopimukseen

Neljä riviä "mikä sen rikkoo" -sarakkeessa toistuvat kaikissa projekteissa. Versiovaihto: toimittaja julkaisee rajapinnasta uuden version ja lopettaa vanhan tuen määräpäivänä. Uusi kenttä: joku lisää pakollisen tiedon, ja vanha kutsu hylätään. Token vanhenee: tunnistautuminen lakkaa toimimasta päivänä, jota kukaan ei merkinnyt kalenteriin. Kutsuraja: rajapinta sallii esimerkiksi tietyn määrän kutsuja minuutissa, ja kun tapahtumia tulee piikissä enemmän, osa hylätään.

Kirjaa nämä neljä ylös ennen kuin rakennat mitään: rajapinnan versio ja toimittajan versiopolitiikka, tunnistautumisavaimen vanhenemispäivä, kutsuraja numeroina, ja kenen puhelin soi kun integraatio pysähtyy. Jos jokin näistä on auki, ylläpitovelka on tuntematon eikä sitä voi laskea.

Kannattaako integraatio? Laske päätössääntö itse viidessä minuutissa

Päätössääntö integraatiolle on yksi jakolasku, jonka teet ennen kuin pyydät keneltäkään mitään. Mittaa ensin, montako minuuttia viikossa tiedon siirtämiseen oikeasti kuluu, muuta se vuosituntteihin kaavalla minuutit × 52 ÷ 60, vähennä siitä integraation vuosittainen ylläpito ja jaa rakentamisen tuntimäärä jäljelle jäävällä nettosäästöllä. Esimerkki koko matkalta: 45 minuuttia viikossa on 39 tuntia vuodessa, josta 6 tunnin ylläpidon jälkeen jää 33 tuntia, ja jos rakentaminen on 30 tuntia, takaisinmaksu on noin 0,9 vuotta. Alle kahden vuoden takaisinmaksu on selvä kyllä. Vaiheet ovat alla numeroituna, ja viimeinen kohta näyttää saman laskun vastaesimerkkinä, jossa vastaus kääntyy ei:ksi.

Mittaa käsityöMontako minuuttia viikossa kuluu tiedon siirtämiseen järjestelmästä toiseen? Ota oikea luku, älä arvaa liian pieneksi. Laske mukaan virheiden etsiminen.
Muuta vuosituntteihinminuutit viikossa × 52 ÷ 60 = tuntia vuodessa. Esimerkki: 45 min/vko × 52 = 2340 min ÷ 60 = 39 tuntia vuodessa.
Vähennä ylläpitoAutomaatio ei vie nollaan. Oma API-integraatio syö taulukon mukaan 4–12 h vuodessa. Esimerkissä 39 h − 6 h = 33 tuntia nettosäästöä.
Jaa rakentamisen tunneillaJos rakentaminen on 30 h, takaisinmaksu on 30 ÷ 33 ≈ 0,9 vuotta. Alle kahden vuoden takaisinmaksu on selvä kyllä.
Tarkista vastaesimerkki10 min/vko on 8,7 h vuodessa. Kun siitä vähennetään 6 h ylläpitoa, nettosäästö on 2,7 h. Rakentaminen 30 h ÷ 2,7 h = yli 11 vuotta. Tätä ei rakenneta.

Sääntö tiivistyy yhteen lauseeseen: jos käsityötä on alle noin 20 minuuttia viikossa, oma rajapintaintegraatio ei maksa itseään takaisin — ylläpito syö säästön. Silloin ajastettu tiedostosiirto tai valmis liittymä on oikea taso. Työn laskutus näkyy tunteina hinnastossa, joten voit sijoittaa oman euromääräsi samaan kaavaan ilman tarjouspyyntöä.

Laskurin ulkopuolelle jää yksi asia, joka kannattaa punnita erikseen: virheiden hinta. Jos käsin siirretty tieto on esimerkiksi varastosaldo tai laskutusrivi, yksi näppäilyvirhe voi maksaa enemmän kuin koko vuoden käsityö. Silloin integraatio kannattaa myös pienemmällä minuuttimäärällä.

Mitä toimittajalta pitää vaatia kirjallisena?

Integraatioprojekti kaatuu harvoin koodiin. Se kaatuu siihen, että jotain oletettiin, ja siksi toimittajalta pyydetään viisi asiaa kirjallisena ennen kuin työ alkaa: rajapinnan dokumentaatio, testitunnukset ja testiympäristö, versiopolitiikka, kutsurajat numeroina sekä omistajuus koodiin, tunnuksiin ja dokumentaatioon. Pyydä ne mielellään sähköpostilla eikä palaverissa, koska sähköposti säilyy ja palaverimuistikuva ei. Jokainen viidestä kohdasta vastaa yhteen tunnettuun tapaan, jolla integraatio myöhemmin hajoaa tai jää jumiin yhden toimittajan käsiin, joten lista ei ole muodollisuus vaan riskin siirto pois sinulta. Alla jokainen kohta on avattu erikseen.

Dokumentaatio. Linkki rajapinnan kuvaukseen, jossa näkyvät kutsut, kentät ja virheilmoitukset. Jos dokumentaatio on salainen tai olemassa vain toimittajan päässä, projektin riski nousee heti.

Testitunnukset ja testiympäristö. Sandbox eli hiekkalaatikko on kopio järjestelmästä, jossa voi kokeilla ilman että oikeat laskut lähtevät tai oikeat varastot liikkuvat. Ilman sitä ensimmäinen testi tehdään tuotannossa, ja se näkyy asiakkaille.

Versiopolitiikka. Kuinka pitkään vanha rajapintaversio pysyy tuettuna ja millä varoitusajalla muutoksista kerrotaan. Tämä on suoraan ylläpitovelkasi ennustettavuus.

Kutsurajat numeroina. Montako kutsua minuutissa tai päivässä. Jos raja on matalampi kuin tapahtumamääräsi piikissä, arkkitehtuuri pitää suunnitella toisin heti alussa eikä puolen vuoden päästä.

Omistajuus. Lähdekoodi, tunnukset ja dokumentaatio kuuluvat tilaajalle. Me luovutamme ne aina asiakkaalle, koska se on ainoa tapa varmistaa, että voit vaihtaa tekijää ilman että integraatio pitää rakentaa uudestaan. Kirjaa asia sopimukseen — sopimuksen muut kohtuulliset ehdot on käyty läpi artikkelissa mitä sopimukseen kuuluu. Itse rakennustyö kuuluu ohjelmistokehityksen puolelle, ja se tehdään täällä itse alusta loppuun.

Milloin API-integraatiota EI kannata tehdä?

API-integraatiota ei kannata tehdä neljässä tilanteessa, vaikka tekninen toteutus olisi täysin mahdollinen. Ensimmäinen on se, että käsityötä on liian vähän: alle noin 20 minuuttia viikossa ei maksa kymmenien tuntien rakennusprojektia takaisin. Toinen on se, ettei toisessa päässä ole rajapintaa lainkaan, jolloin jäljelle jää käyttöliittymän raapiminen, jonka ylläpitovelka on korkea ja arvaamaton. Kolmas on se, että toinen järjestelmä on jo päätetty korvata vuoden sisällä, jolloin integraatio rakennetaan kahdesti. Neljäs on se, että prosessi on vielä auki eikä kukaan osaa sanoa, mikä tieto siirtyy ja kumpi järjestelmä on oikeassa ristiriidassa. Alla jokainen tilanne on avattu erikseen ja kerrottu, mitä tilalle tehdään.

Käsityötä on liian vähän. Alle noin 20 minuuttia viikossa tarkoittaa alle 18 tuntia vuodessa. Kun siitä vähennetään ylläpito, jäljelle jää muutama tunti, eikä kymmenien tuntien rakennusprojekti maksa sitä takaisin missään järkevässä ajassa. Tee tiedostosiirto tai jätä käsityöksi.

Toisessa päässä ei ole rajapintaa. Jos toinen järjestelmä ei tarjoa rajapintaa lainkaan, jäljelle jää käyttöliittymän raapiminen: ohjelma, joka teeskentelee ihmistä ja klikkaa sivuja. Se toimii, kunnes toimittaja muuttaa sivun ulkoasua, ja sitten se hajoaa ilman varoitusta. Ylläpitovelka on korkea ja arvaamaton, ja monessa palvelussa se on lisäksi käyttöehtojen vastaista. Tämä on viimeinen keino, ei suunnitelma.

Järjestelmä vaihtuu vuoden sisällä. Jos toinen pää on jo päätetty korvata, integraatio rakennetaan kahdesti. Odota uutta järjestelmää ja tee siirtymäajan tiedostosiirrolla.

Prosessi on vielä auki. Jos kukaan ei osaa sanoa täsmälleen, mikä tieto siirtyy, milloin ja kumpi järjestelmä on oikeassa ristiriitatilanteessa, integraatio ei ole vielä tekninen ongelma vaan sopimisen ongelma. Ratkaise se ensin paperilla — se on halvempaa kuin ratkaista se koodissa.

Usein kysyttyä

Mitä API-rajapinta maksaa?

Hinta muodostuu tunneista, ja tunnit muodostuvat kolmesta asiasta: montako eri tietotyyppiä siirretään, kuinka hyvin molempien päiden rajapinnat on dokumentoitu ja tarvitaanko virheiden käsittelyä ja hälytyksiä. Yksisuuntainen yhden tietotyypin siirto hyvin dokumentoitujen rajapintojen välillä on pieni työ, kaksisuuntainen synkronointi ristiriitojen ratkaisulla on moninkertainen. Tuntihinta lukee hinnastossa.

Onko webhook parempi kuin pollaus?

Nopeampi kyllä, parempi ei aina. Webhook vaatii julkisen osoitteen, uudelleenyritysten käsittelyn ja lokin siitä mitä tuli perille. Pollaus muutaman minuutin välein on yksinkertaisempi ja kestää katkoja paremmin. Valitse webhook vasta kun viive oikeasti haittaa liiketoimintaa.

Kuka omistaa integraation koodin?

Meillä tilaaja. Lähdekoodi, tunnukset ja dokumentaatio luovutetaan asiakkaalle, eikä toimittajalukkoa synny. Kysy tämä jokaiselta toimittajalta ennen sopimusta — jos koodia ei luovuteta, integraation ylläpito on lopullisesti yhden yrityksen käsissä.

Miten huomaan, jos integraatio on hajonnut?

Vain jos joku on rakentanut hälytyksen. Hiljainen pysähtyminen on tavallisin vikatila: mitään ei siirry, mutta mikään ei myöskään huuda. Pyydä integraatioon vähintään virheloki ja sähköposti- tai viestihälytys epäonnistuneesta ajosta. Se on pieni lisätyö ja säästää sen viikon, jona tiedot olivat vanhoja eikä kukaan tiennyt.

Voiko integraation tehdä ilman ohjelmointia?

Osittain. Valmiit automaatiopalvelut kytkevät yleisiä järjestelmiä toisiinsa ilman koodia, ja pienessä tarpeessa se on täysin järkevä taso. Rajat tulevat vastaan, kun tarvitaan omaa logiikkaa, isoja tietomääriä tai tarkkaa virheenkäsittelyä — ja palvelun kuukausimaksu kannattaa laskea samaan takaisinmaksulaskelmaan.

Yhteenveto

Yhteenveto API-integraatiosta on lyhyt: valitse aina matalin taso, joka riittää. Kokeile ensin, ratkaiseeko ajastettu tiedostosiirto ongelman, koska se on halvin oikea automaatio joka on olemassa. Katso sitten, onko toimittajalla valmis liittymä juuri siihen naapurijärjestelmään — silloin ostat kytkennän, jota et itse ylläpidä. Rakenna oma rajapintaintegraatio vasta, kun kumpikaan ei riitä ja laskelma näyttää takaisinmaksua alle kahdessa vuodessa. Järjestys on tämä siksi, että jokainen askel ylöspäin lisää sekä rakentamisen tunteja että ylläpitovelkaa, ja ylläpitovelka on se osa, joka pysyy laskussa vuodesta toiseen.

Ja kysy ylläpidosta ennen kuin kysyt hinnasta. Rajapinta, jonka rakentaminen maksaa vähän mutta joka hajoaa neljästi vuodessa, on kalliimpi kuin huolellisesti tehty, jota ei tarvitse koskea. Ylläpitovelka on se luku, joka ratkaisee kolmen vuoden kokonaishinnan.

Lue seuraavaksi

Lue myös: Logon suunnittelu yritykselle · Sähköpostin perillemenon korjaus · Uutiskirjepalvelu pienyritykselle · kanta-asiakassovellus yritykselle · QR-koodi generaattori · yhteystiedot · blogi · hinnasto