API integratsioonid, mida Eesti ettevõttes päriselt vaja läheb

Mida integratsioon päriselt tähendab

Kui klient ütleb „meil on vaja API integratsiooni“, ei ole see nõue, vaid soov. Päris nõue kõlab nii: andmed, mis praegu liiguvad inimese käe kaudu ühest süsteemist teise, peavad liikuma ise, ja kui teine süsteem ei vasta, peab keegi sellest teada saama enne, kui number läheb valeks.

Veakäsitlus ja korduskatsed tuleb kavandada koos andmevahetusega, ka siis, kui ühenduse põhipäring on lihtne.

Siin vaatlen nelja liidestamise näidet: äriregistrit, makseid, e-arveid ja e-posti.

Neli liidestamise näidet Eesti ettevõttele

Äriregistri avaandmed ja päringud

Äriregistri andmed on avalikud ja masinloetavad. E-äriregistri avaandmete teenus pakub äriühingute, mittetulundusühingute, sihtasutuste ning riigi- ja kohaliku omavalitsuse asutuste andmeid JSON- ja XML-kujul, osa andmekomplekte ka CSV-na. Suuremas mahus reaalajas pärimiseks on avaandmete API ehk XML-teenused, mida RIK-i lehel on kirjas 16, ja nende kasutamiseks tuleb RIK-iga leping sõlmida.

Üksikasju, mis muudavad selle integratsiooni lihtsaks:

• Rekvisiitide automaattäitmise teenus on avalik, tasuta ja lepingut ei nõua. See tagastab sisestatud sümbolitele vastava kehtiva ärinime ja registrikoodi loendi. Vormi jaoks, kuhu klient kirjutab ettevõtte nime, võib sellest piisata, nii et teenust ei pea ise ehitama.
• Massfail sobib, kui vajad uuendatavat nimekirja, mitte reaalajas kontrolli. Kui sa ei vaja vastust sekundi jooksul, ei ole XML-teenust vaja.
• Registriandmed ei ole igavesti värsked. Ettevõtte põhitegevusala saab äriregistri andmetes muuta ainult majandusaasta aruande esitamisega, seega võib kood kirjeldada tegevust, mida ettevõte enam ei tee.

Pank ja maksed: oleku sidumine tellimusega

Makseintegratsiooni töömaht sõltub sellest, kuidas makse olek tellimusega seotakse ja milliseid veajuhtumeid tuleb katta. Lisaks tuleb lahendada makse oleku kontroll ja selle seostamine tellimusega.

Kolm kontrolli, mis aitavad makse olekut usaldusväärselt jälgida:

1. Ära kunagi usalda brauseri tagasitulekut

   Makseteenusest naasmine on kasutajale hea kogemus, mitte tõend. Tõend on teine kanal: veebikonks või päring teenusepakkuja poole. Kui inimene sulgeb brauseri enne tagasitulekut, on raha läinud ja tellimus võtmata.

2. Tee töötlemine idempotentseks

   Sama sündmus võib tulla kaks korda. Enne töötlemist kontrolli, kas selle sündmuse ID on juba kirjas, ja kirjuta see samas tehingus, kus muudad olekut.

3. Hoia nimekiri maksetest, mis on pooleli

   Kontrolli korrapäraselt makseid, mille olek on tundmatu, ja küsi teenusepakkujalt üle. Nii jõuab ebaselge juhtum enne kliendi päringut ülevaatusse.

Kontrolli enne töötlemist veebikonksu allkirja. Salvesta sündmuse tunnus ja muuda makse olekut sama andmebaasitehingu sees. Kui olekumuudatus ebaõnnestub, võta ka sündmuse salvestus tagasi, et teenusepakkuja korduskatse saaks töö uuesti teha. Saada vastus 200 alles pärast tehingu kinnitamist või juba edukalt töödeldud sündmuse tuvastamist. Stripe'i veebikonksude juhend selgitab allkirja kontrolli ja kordussaatmist.

Eesti klientide puhul lisandub arveldusvaluuta ja -viiside küsimus: osa ettevõtteid tahab pangalinke, osa kaarti, osa mõlemat. Kui esimene versioon katab ühe kanali, kirjuta see kokkulepitud töö ulatusse.

E-arve ja raamatupidamise liides

E-arve andmete ühendamisel tuleb kaardistada summade kõrval ka kontod, maksukoodid, dimensioonid ja viited. Väärtused peavad klappima raamatupidaja tabelitega, mitte arendaja oletusega.

Kaks realistlikku teed:

• Raamatupidamistarkvara API. Merit Aktiva API on REST- ja JSON-põhine, Eesti lokalisatsiooni teenuse aadress on https://aktiva.merit.ee/api/v1/ (ja v2), ning API on kasutatav Pro ja Premium litsentsitasemetega. Kui kliendil on see tarkvara juba olemas, on see lühem tee kui oma arvemootor.
• Operaator, kes teeb EDI-andmevahetuse. Telema vahendab tellimusi, saatelehti ja arveid süsteemide vahel ning nende lehel on kirjas üle 70 000 e-dokumendi päevas, üle 6 100 poe ja üle 1 300 tarnija. Kui äripartnerid on jaeketid, võib see olla nende kasutatav tee.

Mõlemal juhul tuleb kaardistada sinu andmemudel raamatupidamise mõistetesse. Küsi kliendilt näidisarve ja lepi kokku, milline väli läheb millisesse kontosse.

E-post: saatmine ja postkasti lugemine

E-post võib olla vajalik nii teavituste saatmiseks kui ka postkasti lugemiseks, kuid need on eri töövood ja neid tuleb eraldi testida. Saadetud kirjade kohaletoimetamist ei saa eeldada ainult sellest, et SMTP-ühendus töötab.

• Saatmine. Teavitused, arved ja meeldetuletused. Siin on põhiküsimus kohaletoimetamine: SPF, DKIM ja DMARC peavad domeenil korras olema, muidu läheb kiri rämpsu või ei lähe üldse. Protokoll ise on vana ja lihtne, vt RFC 5321.
• Vastuvõtt ja lugemine. Google'i või Microsofti postkasti lugemiseks tuleb arvestada OAuthi ja postkasti õigustega. Kasutada saab Gmail API-t või Microsoft Graphi; kui teenuse ja konto seadistus seda lubab, on võimalik ka OAuthiga autenditud IMAP, nagu kirjeldab Google'i XOAUTH2 juhend. See on saatmisest eraldi töö ja vajab oma kokkulepet.

Kui toode loeb postkasti, määra ligipääsu ulatus ja säilitusaeg. Postkasti lugemine annab ligipääsu kliendi kirjadele, seega lepi vajalikud õigused kliendiga eraldi kokku.

Mida mitte ehitada

• Veebilehe lugemine automaatselt selleks, et saada andmeid, mille jaoks on olemas API või massfail. Laguneb vaikselt ja keegi ei märka enne, kui number on vale.
• Oma arvemootor, kui raamatupidamine on juba olemas. Kahekordne tõde toob kahekordse töö.
• CRM-i ja raamatupidamise kahesuunaline sünkroonimine enne, kui kumbki pool on ühesuunaliselt töötanud. Kahesuunaline sünk on konfliktide lahendamise projekt.
• Integratsioon ilma logita. Kui keegi ei näe, millal päring ebaõnnestus, ei saa seda ka parandada.

Millised tööd tuleb enne ulatust kokku leppida

Integratsiooni töömaht sõltub dokumentatsiooni kvaliteedist, olemasolevast testkeskkonnast, ligipääsudest ja andmete kvaliteedist. Enne hinnangut pane kirja nii eeldatav töövoog kui ka see, kuidas taastad andmed või parandad oleku pärast tõrget.

Juurdepääsude saamine kliendi IT-osakonnalt ja teise poole testkeskkonna olemasolu võivad töö ulatust muuta. Lepi need eeldused ning nende mõju hinnale ja ajakavale enne alustamist kirjalikult kokku.

Testimiskava: mida kontrollida enne, kui integratsioon loetakse valmis

Integratsioon, mis töötab siis, kui kõik läheb hästi, ei ole valmis. Valmis on see, mis käitub ettearvatavalt ka siis, kui teine pool käitub halvasti. See tabel on miinimum, mida ma iga liidese juures käin läbi.

Logi päringu tunnus, aeg, tulemus ja vea lahendamiseks vajalik kontekst. Ära salvesta autentimistunnuseid ega terviklikke isikuandmetega päringuid ja vastuseid, kui selleks puudub vajadus. Määra logidele ligipääs ja säilitusaeg ning vaata vead korrapäraselt üle.

Kuidas otsustada: ise, osta või loobuda

Enne kui valid tehnilise tee, vasta neljale küsimusele, mis aitavad võrrelda ehitamist, ostmist ja käsitsi tööd; sama otsustusviis sobib tarkvaraarenduse kaardistusele.

1. Kui sageli see töö toimub?

   Kord kuus tehtavat käsitsi tööd ei ole mõtet automatiseerida, kui see võtab kümme minutit. Kord päevas tehtav pool tundi on juba teine number.

2. Mis on vea hind?

   Kui vale number läheb raamatupidamisse või kliendile, on kontroll kohustuslik. Kui viga on lihtsalt ebamugavus, piisab logist.

3. Kas API või muu liides on olemas ja kelle oma see on?

   Kui API-d ei ole, kontrolli dokumenteeritud failivahetuse võimalust ja seda, kas vajalik andmevoog on piisavalt töökindel.

4. Kes hakkab seda haldama?

   Iga integratsioon laguneb kunagi, kui teine pool muudab. Kui omanik puudub, ei ole mõtet alustada.

Kui vastused on olemas, on otsus tavaliselt ilmne: standardne liides ja suur maht tähendavad ehitamist, väike maht tähendab käsitsi tööd, ja tundlik raamatupidamisandmevahetus tähendab olemasoleva tarkvara kasutamist.

Kuidas integratsiooni ulatust hinnata

Integratsiooni hinnang algab kolmest asjast: näidis andmetest, mis välja lähevad; nimekiri süsteemidest, millega need peavad rääkima; ja üks lause selle kohta, mida tehakse siis, kui andmeid ei tule.

• Üks näidis failist või API vastusest, millega teine pool juba töötab.
• Kes on teise süsteemi omanik ja kes annab ligipääsu.
• Kas liides on testkeskkonnas olemas või tuleb testida tootmisandmetega.
• Mis on lubatud viivitus: sekund, minut või järgmine päev.

Nende vastustega saab hinnata, kas tegu on väikese liidese või eraldi projektiga. Kaardistus on tasuta. Kui integratsioon kuulub esimese versiooni juurde, vaata ka artiklit MVP arendus: mida kolme nädalaga päriselt valmis saab ning tarkvaraarenduse lehte, kus kirjeldatakse fikseeritud töö ulatust ja kirjalikku hinda.