SimplBooksi API küsib autentimiseks vaid ühte päist. Ülejäänu on meie töö.
AlusLabs ehitab SimplBooksi API-liidestusi: paneme müügiarved, ostuarved, kliendid, artiklid ja laekumised liikuma SimplBooksi ja sinu teiste süsteemide vahel ning e-arved tervikliku XML-failina, ilma käsitsi tööd tegemata.
SimplBooksi API on dokumenteeritud OpenAPI-na ja autentimiseks piisab ühest päisest. Keeruline osa ei ole ligipääsu saamine. Keeruline on see, millised andmed liiguvad, millal nad liiguvad ja mis saab siis, kui teine pool ei vasta.
Kes ehitab SimplBooksi liidestuse?
AlusLabs ehitab SimplBooksi liidestusi Eesti ettevõtetele. Töö käib SimplBooksi avaliku API kaudu: dokumentatsioon asub aadressil app.simplbooks.com/api-documentation/ ja autentimiseks piisab allkirjastatud päringu asemel ühest päisest. Sinult on vaja seadetes luua API-kasutaja ning otsustada, millised andmed ja mis suunas liiguvad.
Meie avalik kood on kirjutatud Merit Aktiva, mitte SimplBooksi jaoks, ja link sellele on allpool. See näitab, kuidas me ühe Eesti raamatupidamisprogrammi API peale ehitame: kuidas on lahendatud autentimine, kui laia lõpp-punktide kaetust me kasutame ja millises seisus on dokumentatsioon.
Mida me ühendame
SimplBooksi API katab müügiarveid, ostuarveid, kliente, artikleid ja laekumisi. See määrab ära nii selle, mida tasub liidestada, kui ka selle, mida mitte.
E-pood
Tellimusest saab SimplBooksis müügiarve koos kliendi, artiklite ja käibemaksukoodiga. SimplBooksil on WooCommerce'i ja Shopify jaoks olemas ka oma sisseehitatud liidesed, seega tasub kõigepealt kontrollida, kas need katavad sinu vajadused juba ära.
E-arved
SimplBooksi API võtab tervikliku e-arve XML-i vastu, kui päis X-Input-Format kannab väärtust Raw, ja annab ka arve XML-ina tagasi. E-arve liigub ilma vahepealse käsitsi sekkumiseta.
CRM ja müük
Kliendid, pakkumised ja tellimused liiguvad CRM-i ja SimplBooksi vahel. Müügiinimene näeb, mis on arveldatud ja mis laekunud, ilma et peaks raamatupidajale kirjutama.
Laekumised
Laekumiste lõpp-punkti kaudu saab arve märkida makstuks ja lugeda sisse laekumised. Võlglaste nimekiri ei sõltu enam sellest, millal keegi viimati pangaväljavõtte avas.
Tabelid ja aruanded
Tabel, mis varem nõudis igakuist eksporti, küsib numbrid API kaudu ise: käibe, laekumata arved ja jaotuse klientide lõikes. Aruandlus ei sõltu enam sellest, kes jõudis eksportida.
Kuidas see tehniliselt töötab
SimplBooksi API asub aadressil app.simplbooks.com ja on ettevõttepõhine: ettevõtte tunnus on osa baasaadressist. Autentimine ei nõua allkirjastamist. Seadetes luuakse eraldi API-kasutaja, genereeritakse võti ja see saadetakse päises X-Simplbooks-Token. Puudub ajatempel ja kellade erinevus, mida peaks arvestama, mistõttu esimene töötav päring saabub kiiresti.
Sellel lihtsusel on kaks hinda ja mõlemat tasub ette teada. Esiteks on API-võti staatiline, ilma ajatempli ja allkirjata: lekkinud võti tähendab lekkinud ligipääsu, kuni luuakse uus võti. Seda hoitakse nagu parooli ja vahetatakse inimeste liikumisel. Teiseks avaldab SimplBooks dokumentatsioonis päringute limiidi ja märgib eraldi, et limiiti ületavad päringud lähevad samuti mahu arvestusse. Vale kordusloogika teeb seega olukorra parema asemel halvemaks.
Üks asi tuleb enne ehitamist selgeks teha: pearaamatu poolel annab API kontode nimekirjad vaid lugemiseks ja pearaamatu kande kirjutamiseks dokumenteeritud lõpp-punkti ei ole. Müügiarved, ostuarved, kliendid, artiklid ja laekumised on seevastu API kaudu saadaval nii lugemiseks kui ka kirjutamiseks. Kui sinu plaan sõltub suvaliste kannete kirjutamisest, ütleme seda kohe alguses, mitte poole töö pealt.
Avatud lähtekood
github.com/arturl95/merit-aktiva-skillsHMAC-SHA256 päringute allkirjastamine, Merit Aktiva v2 lõpp-punktide kate, MIT-litsents, dokumentatsioon eesti ja inglise keeles. Loetav ja kasutatav ka ilma meieta.
- checkAPI-võti jääb serveri poolele, mitte brauserisse ega tabelisse.
- checkPäringute tempo püsib SimplBooksi avaldatud limiitide piires ja korduskatsed ei tekita uut ummikut.
- checkKui SimplBooks ei vasta, ootab kirje järjekorras ja jääb nähtavaks, mitte ei kao vaikselt ära.
E-arved ja XML
E-arvete poolel võtab SimplBooksi API vastu tervikliku e-arve XML-i ja annab arve ka XML-ina välja. Sissetulevast e-arvest saab ostuarve ilma käsitsi sisestamiseta ja väljaminev arve liigub edasi kujul, mida saaja ootab. Vahepeal ei ole vaja eraldi konverterit ega inimest välju ümber tõstma.
Ühte asja tasub enne ehitamist kontrollida. SimplBooksi pakutavate sisemiste liideste seas on ka e-arve operaatorid ja need töötavad ilma API-moodulita. Kui sinu e-arved liiguvad juba sealtkaudu, ei ole meie tööd selles osas vaja ja me ütleme seda ka ise.
Millal tasub liidestada
Liidestus ei ole eesmärk omaette. Kui mõni neist punktidest kirjeldab sinu nädalat, tasub liidestamisele mõelda:
Sama arvet sisestatakse kaks korda
Arve sünnib ühes süsteemis ja seejärel uuesti SimplBooksis. Teine kord on puhas käsitöö koos sellest tulenevate trükivigadega.
Arveid märgitakse laekunuks käsitsi
Avatakse pangaväljavõte, otsitakse read ja märgitakse arved ükshaaval makstuks. Keegi kordab seda igal nädalal ja ei õpi sellest midagi uut.
Numbri saamiseks tuleb kellelegi kirjutada
Kui käibe või võlglaste teadasaamiseks peab keegi SimplBooksi sisse logima ja ekspordi tegema, on tegemist andmete kättesaadavuse, mitte raamatupidamise probleemiga.
Premium-pakett on olemas, kuid API seisab jõude
API-moodul sisaldub paketis ja keegi pole seda kasutusele võtnud. Kõige odavam liidestus on see, mille eest sa juba maksad.
KKK
Kas SimplBooksil on avalik API?
Jah. Dokumentatsioon on avalik aadressil app.simplbooks.com/api-documentation/ ning seda saab lugeda ilma lepingu ja kasutajakontota. Kasutamiseks on vaja Premium-paketti ja seadetes loodud API-kasutajat, kelle võti liigub päises X-Simplbooks-Token.
Kas SimplBooksi e-poe liides ei tee juba sama asja?
Osaliselt teeb ja sellisel juhul ei ole mõtet raha kulutada. SimplBooks eristab sisemisi liideseid, mis töötavad ilma API-moodulita, ja väliseid liideseid, mis nõuavad seda. Vaata kõigepealt, mida sisemine liides sinu poe puhul katab. Meid on vaja alles siis, kui midagi jääb katmata: eriline maksuloogika, kolmas süsteem vahel või voog, mida nimekirjas pole.
Kas SimplBooksi API kaudu saab kirjutada pearaamatu kandeid?
Selleks puudub dokumenteeritud lõpp-punkt. Kontode nimekirjad on API kaudu loetavad, kuid kande kirjutamist SimplBooksi avalikus dokumentatsioonis kirjeldatud ei ole. Tavaliselt ei ole see takistuseks, sest arved, laekumised ja kliendid kannavad edasi info, mille põhjal raamatupidaja kanded teeb. Kui sul on tõesti vaja suvalisi kandeid kirjutada, tuleb see lahendada mujal kui API-s.
Mis saab siis, kui SimplBooks ei vasta?
Kirje ootab järjekorras ja seda proovitakse uuesti tempos, mis jääb avaldatud päringute limiidi piiresse, sest ka limiiti ületavad päringud lähevad mahu arvestusse. Kui see ikkagi läbi ei lähe, jääb see nähtavasse nimekirja, mitte ei kao ära. Teel kaduma läinud vastust käsitletakse samamoodi: kirjet kontrollitakse kõigepealt, et vältida sama arve topelt loomist.
Kas me haldame API-võtit ise?
API-võti luuakse sinu enda SimplBooksi kontol ja see jääb sinu omaks. Kuna võti ei sisalda ajatemplit ega allkirja, on selle uuesti genereerimine ainus viis ligipääsu tühistamiseks, mis lõpetab ka meie ligipääsu samal hetkel. Seetõttu asub võti meie juures serveri poolel ja seda tasub inimeste vahetumisel uuendada.
Seotud liidestused
Merit Aktiva integratsioon ja API-liidestus
Merit Aktiva API-liidestus e-poe, CRM-i, tabelite ja sisemiste töövoogudega. AlusLabs ehitab liidestuse olemasoleva programmi peale, ilma et peaksid Merit Aktivast loobuma.
E-arve saatmine: operaatorid, formaadid ja Finbite liidestus
E-arve liigub sinu tarkvarast välja andmetena, ostjale sobivas formaadis ja kanalit pidi, mis on kirjas tema äriregistri kaardil. Sageli on selleks kanaliks e-arve operaator nagu Finbite. AlusLabs ehitab sinna vahele liidestuse, mis teeb ka registripäringu ja otsustab, kuhu iga arve saata.
Kes teeb süsteemide liidestusi Eestis? Merit Aktiva, SimplBooks ja kõik teised programmid sinu majas
Eesti majandustarkvaradel on olemas avalikud API-liidesed, kuid nendevahelist osa ei paku valmis kujul keegi. AlusLabs ehitab selle puuduva osa, annab üle ligipääsud ning dokumentatsiooni ja ütleb sulle, kui sinu juba makstud programmid katavad selle teekonna ise.
WooCommerce'i ja Merit Aktiva liidestus: tellimusest arveni
Tellimusest saab Merit Aktivas müügiarve koos õige kliendi, artikli ja käibemaksukoodiga ning tagastusest kreeditarve. AlusLabs ehitab liidestusi WooCommerce'i ja Merit Aktiva vahel.
Räägime sellest, mis peab SimplBooksi sisse ja sealt välja liikuma
Kirjuta paari lausega, millised süsteemid on kasutuses ja mis liigub praegu käsitsi. Ütleme ausalt, kas liidestust tasub ehitada ja millest alustada.