Integraatioprojektin speksi: mitä dokumentoida ennen toteutusta

Miksi speksi on tärkeä?

• Yhteinen ymmärrys: Kaikki tietävät mitä ollaan tekemässä
• Tarkkempi arvio: Kehittäjä voi arvioida työmäärän realistisesti
• Vähemmän yllätyksiä: Ongelmat löytyvät paperilla, ei tuotannossa
• Dokumentaatio: Myöhemmin tiedetään miten integraatio toimii

Speksin sisältö

1. Yleiskuvaus

• Mikä on integraation tarkoitus? (yksi lause)
• Mitkä järjestelmät yhdistetään? (nimet ja versiot)
• Kuka on vastuuhenkilö molemmissa päissä?

2. Datavirta

• Mistä data tulee ja minne se menee? (suunta)
• Onko yksi- vai kaksisuuntainen?
• Mitä kenttiä siirretään? (kenttäkohtainen listaus)
• Miten kentät mappautuvat toisiinsa?

3. Laukaisijat (triggers)

• Milloin integraatio laukeaa? (esim. uusi tilaus, päivitetty asiakas)
• Reaaliaikainen (webhook) vai ajastettu (cron)?
• Kuinka usein dataa siirretään?

4. Autentikointi ja turvallisuus

• Miten tunnistaudutaan? (API key, OAuth, Basic Auth)
• Missä avaimet säilytetään?
• Onko IP-rajoituksia?

5. Virheenkäsittely

• Mitä tapahtuu kun yhteys ei toimi?
• Miten retry toimii?
• Kuka saa ilmoituksen virheistä?
• Miten manuaalinen uudelleenajo tehdään?

6. Testaus ja käyttöönotto

• Onko testiympäristö käytettävissä?
• Miten testataan ennen tuotantoa?
• Kuka hyväksyy käyttöönoton?

Esimerkki: Verkkokauppa → CRM -integraatio

Järjestelmät	WooCommerce → Pipedrive
Tarkoitus	Uudet tilaukset luovat diilin Pipedriveen
Suunta	Yksisuuntainen: WooCommerce → Pipedrive
Trigger	Webhook: uusi tilaus (status: processing)
Kentät	order_id → deal.title customer_email → person.email customer_name → person.name total → deal.value products → deal.notes
Autentikointi	WooCommerce: webhook secret, Pipedrive: API token
Virheenkäsittely	3x retry, sähköposti-ilmoitus epäonnistumisesta

Speksin checklist

• ☐ Järjestelmät ja versiot dokumentoitu
• ☐ API-dokumentaatio saatavilla molemmista päistä
• ☐ Datavirta ja suunta määritelty
• ☐ Kenttämappaus tehty
• ☐ Laukaisijat/aikataulu sovittu
• ☐ Autentikointitapa selvillä
• ☐ Testiympäristö ja -tunnukset käytettävissä
• ☐ Virheenkäsittely suunniteltu
• ☐ Vastuuhenkilöt nimetty
• ☐ Hyväksymiskriteerit sovittu

Yleiset virheet speksauksessa

1. Liian yleinen: "Yhdistetään verkkokauppa ja CRM" – ei riitä, tarvitaan yksityiskohtia.
2. Oletetaan liikaa: "Kehittäjä kyllä tietää" – ei tiedä, kirjoita ylös.
3. Unohdetaan virhetilanteet: Happy path ei riitä.
4. Ei testata etukäteen: API-dokumentaatio lupaa, mutta todellisuus on toinen.
5. Ei versioida: Speksi muuttuu, mutta kukaan ei tiedä mikä on voimassa.

Usein kysytyt kysymykset

Kuinka tarkka speksin pitää olla?

Tarpeeksi tarkka, että kehittäjä voi antaa työmääräarvion ja aloittaa työn ilman jatkuvia kysymyksiä. Käytännössä: kenttätason mappaus ja virheenkäsittely.

Kuka kirjoittaa speksin?

Yhteistyössä: asiakas kertoo liiketoimintatarpeen, kehittäjä täydentää tekniset yksityiskohdat. Voimme auttaa speksin kirjoittamisessa.

Paljonko speksaus maksaa?

Tyypillisesti 2–8 tuntia riippuen monimutkaisuudesta. Tuntihinta 70 €/h. Säästää moninkertaisesti toteutusvaiheessa.

Lue myös

• Webhookit käytännössä
• CRM → laskutus automaatio
• Integraatioiden riskit ja hallinta
• Integraatiot ja automaatio palveluna →