API ja integraatiot

Kelomon julkista rajapintaa käytetään API-avaimilla. Organisaation avaimia hallitaan kohdassa Asetukset → Integraatiot → API-avaimet ja sovellukset ja webhookeja saman ryhmän sivulla Webhookit. Oman henkilökohtaisen avaimesi luot omissa asetuksissasi välilehdellä Omat API-avaimet.

Kaksi avainlajia

• Henkilökohtainen avain toimii sinun oikeuksillasi ja ulottuu enintään yhtä pitkälle kuin sinä itse. Avain lakkaa toimimasta, kun käyttöoikeutesi päättyy. Jokainen käyttäjä voi luoda omansa.
• Palveluavain on integraatioille, joiden pitää toimia yksittäisestä henkilöstä riippumatta. Sillä on nimetty Omistaja – käyttäjä, jonka valtuudella avain toimii – ja omistajan voi vaihtaa myöhemmin painikkeella Vaihda omistaja. Avaimen arvo, oikeudet ja historia säilyvät. Palveluavaimia luo pääkäyttäjä.

Uusi avain

1. Paina Uusi avain (oma avain) tai Uusi palveluavain (organisaatio).
2. Anna Avaimen nimi ja halutessasi kuvaus. Palveluavaimelle valitaan myös Omistaja.
3. Valitse Avaimen oikeudet. Valittavana ovat vain oikeudet, jotka avaimen haltijalla itsellään on. Henkilökohtainen avain ilman valittuja oikeuksia yltää vain omiin tietoihisi; palveluavain vaatii vähintään yhden oikeuden.
4. Valitse Voimassaolo (30 päivää, 90 päivää, 1 vuosi tai ei vanhene) ja rasti tarvittaessa Vain luku.
5. Tallenna. Avaimen arvo alkaa kelomo_, ja se lähetetään pyynnöissä otsakkeessa Authorization: Bearer.

Arvo näytetään vain kerran. Kopioi se heti talteen. Jos arvo hukkuu, oman avaimen voi vaihtaa painikkeella Vaihda avain – vanha toimii vielä 24 tuntia – tai luoda uuden avaimen.

Avainten hallinta

Listalla näkyy avaimen alkuosa, luontipäivä, viimeisin käyttö ja pyyntömäärä seitsemältä päivältä. Mitätöi poistaa avaimen käytöstä pysyvästi. Vanhenevasta avaimesta Kelomo lähettää ilmoituksen etukäteen, jotta ehdit uusia sen ennen katkoa.

Webhookit

Sivulla Webhookit Kelomo lähettää valitut tapahtumat antamaasi osoitteeseen – esimerkiksi vuorojen julkaisut, laskutapahtumat ja poissaolopäätökset.

1. Paina Lisää webhook ja anna Osoite. Osoitteen on alettava https://.
2. Valitse Viestin tyyppi: JSON (allekirjoitettu) integraatioille, Slack tai Microsoft Teams valmiiksi viesteiksi kanavan incoming webhook -osoitteeseen. Slack- ja Teams-viesteille valitaan myös Viestin kieli.
3. Valitse Tapahtumat.
4. Tallenna. JSON-tyypille näytetään allekirjoitussalaisuus (X-Kelomo-Signature) – sekin vain kerran.

Rivin toiminnot: Testaa lähettää testiviestin, Poista käytöstä pysäyttää toimitukset ja Ota käyttöön jatkaa niitä. Vaihda salaisuus vaihtaa allekirjoitussalaisuuden uuteen (vanha toimii vielä 24 tuntia). Tyyppiä ei voi vaihtaa jälkikäteen – luo tarvittaessa uusi webhook.

Webhookin osoite listalla avaa sen sivun, jolla on Toimitushistoria. Epäonnistunutta toimitusta yritetään automaattisesti uudelleen; rivillä näkyy seuraavan yrityksen aika, ja toimituksen voi lähettää käsin uudelleen toiminnolla Lähetä uudelleen. Jos toimitus ei mene perille lainkaan, siitä tulee ilmoitus.

Zapier

Kelomo on Zapierissa valmiina liittimenä. Zap käynnistyy Kelomon tapahtumasta, esimerkiksi uudesta liidistä, voitetusta kaupasta, tarjouksen päätöksestä, jätetystä tai päätetystä poissaolosta, hyväksytystä työpäivästä, julkaistusta vuorosta, valmiista palkka-aineistosta, lähetetystä laskusta, kirjatusta suorituksesta tai asiakkaan, projektin tai tehtävän muutoksesta. Toiminnot Create Lead, Create Task, Create Customer ja Create Intake Item luovat Kelomoon liidin, tehtävän, asiakkaan tai työpyynnön. Rekisterien tuontitoiminnot, työpäivät ja hyväksynnät on kuvattu alempana.

1. Luo palveluavain yllä kuvatulla tavalla. Anna sille oikeus Hallinnoi webhookeja ja integraatiotapahtumia sekä käytettävien tapahtumien oma oikeus: myynnin tapahtumat vaativat myynnin työtilan oikeuden, poissaolot ja työpäivät esihenkilön oikeuden, vuorot vuorosuunnittelun ja laskut sekä suoritukset laskutuksen oikeuden. Jos Zap luo tietoja Kelomoon, jätä Vain luku valitsematta.
2. Avaa Zapierissa Kelomon kutsulinkki Kelomo Zapierissa ja hyväksy kutsu. Sen jälkeen Kelomo löytyy Zapierin sovellushaulla.
3. Tee Zap. Kun valitset Kelomon ensimmäistä kertaa, Zapier pyytää yhdistämään tilin: liitä avain kenttään API Key. Kentän API URL oletusarvo on Kelomon osoite.

Zapierin näyttämä esimerkkitapahtuma haetaan organisaation viimeisimmistä tapahtumista, joten testaa Zap vasta kun Kelomossa on vähintään yksi kyseinen tapahtuma. Tapahtuma sisältää tunnisteet, tilan ja ajankohdat. Jokainen Zap luo oman rivinsä listaan Webhookit, ja Zapin poisto poistaa rivin.

Resepti: projektit ulkoisesta työkalusta seurantakohteiksi

Kun projektit elävät Jirassa, ne saa Kelomoon seurantakohteiksi ilman projektimoduulia. Tee ensin seurantataso, esimerkiksi “Projekti (Jira)”.

Zapin käynnistää valitun Jira-projektin uusi tai päivittynyt issue. Kelomon toiminto Create or Update Tracking Target luo kohteen tai päivittää sen: valitse taso alasvedosta, anna koodiksi issuen avain, nimeksi otsikko, lähteeksi oma nimiavaruus kuten jira_acme_issue ja tunnisteeksi issuen id. Kun issue siirtyy tilaan, joka päättää työn, lähetä sama toiminto kentällä Active epätotena: kohde passivoituu ja sille kirjatut tunnit säilyvät. Zapin seuraava vaihe saa kohteen tiedot toiminnolla Find Tracking Target, joka hakee koodilla tai lähteen tunnisteella.

Toiminto tarvitsee palveluavaimen, jonka omistajalla on organisaation hallintaoikeus. Sama resepti sopii muihinkin lähteisiin, joista Zapier tarjoaa tapahtuman.

Asiakkaat, projektit ja tehtävät samalla tavalla

Sama kuvio ulottuu kolmeen muuhun rekisteriin. Toiminnot Create or Update Customer, Create or Update Project ja Create or Update Task tunnistavat rivin ensin lähteen tunnisteesta ja vasta sitten koodista, joten saman lähdetietueen toinen ajo päivittää rivin eikä luo uutta. Toiminnot Find Customer, Find Project ja Find Task hakevat yhdellä avaimella: koodilla, lähteen tunnisteella tai Kelomon tunnisteella. Tehtävä haetaan projektin sisältä lähteen tunnisteella tai tehtävän numerolla.

Nimiavaruus erottaa järjestelmän, ympäristön ja tietuelajin (hubspot_acme_company, jira_acme_project, jira_acme_issue), jolloin kaksi lähdettä ei voi törmätä samassa organisaatiossa. Koodi annetaan kerran eikä synkka muuta sitä: palkka-aineiston ja kirjanpidon viennit tunnistavat rivin sillä.

Jos rivi menee läpi muuttumattomana, Kelomoon ei kirjoiteta mitään eikä historiaan jää merkintää. Jos rivi hylätään, Zap pysähtyy ja kertoo syyn: tavallisimmat ovat koodi jo toisen lähteen hallussa, käsin tehty rivi joka vaatii valinnan Adopt an Existing Record by Code, tai rivi jolla ei ole koodia eikä tunnistetta.

Toiseen suuntaan triggerit kertovat, mitä Kelomossa tapahtui: asiakas luotu tai muuttunut, projekti luotu, muuttunut tai suljettu, tehtävä luotu, muuttunut tai siirtynyt sarakkeesta toiseen. Tapahtuma sisältää tunnisteet ja ajankohdan, joten seuraava vaihe on Find-toiminto.

Tehtävän tila lähteestä

Lähteen tila on lähteen oma sana (“In Progress”, “Klaar”, “3”). Se annetaan kentässä External Status, ja Kelomo kääntää sen kohdassa Asetukset → Projektit → Tilavastaavuudet: lähde, ulkoinen tila ja Kelomon tilalaji. Sana, jota taulukossa ei ole, pysäyttää Zapin – Kelomo ei arvaa saraketta. Täytä vastaavuudet ennen ensimmäistä ajoa.

Resepti: Jira-projekti ja sen tehtävät Kelomoon

1. Zapin käynnistää Jira Software Cloud → New Issue valitulla taululla.
2. Create or Update Customer vie asiakkaan: nimi Jiran organisaatiokentästä, lähde jira_acme_org, tunniste organisaation id. Ohita vaihe, jos asiakkaat jo ovat Kelomossa.
3. Create or Update Project vie projektin: nimi epicin otsikosta, Customer Code edellisen vaiheen koodi, lähde jira_acme_project, tunniste Jiran projektin id ja Status Jiran tilasta (Done → closed).
4. Create or Update Task vie tehtävän: Project Code edellisen vaiheen koodi, otsikko issuen otsikosta, lähde jira_acme_issue, tunniste issuen id, External Status Jiran tilan nimi ja Assignee Email vastuuhenkilön osoite.
5. Tee toinen Zap tapahtumasta Updated Issue samoilla kolmella toiminnolla.

Reseptiä ei ole ajettu oikeaa Jira-tiliä vasten – se on kirjoitettu toimintojen ja rajapinnan perusteella. Kelomon puoli on todennettu ajamalla toiminnot kehityspalvelinta vasten.

Työpäivät, hyväksynnät ja henkilöt

Add Work Entries lisää työpäivälle rivin: alku ja loppu tai kesto minuutteina, kirjauslaji ja projekti alasvedosta sekä muistiinpano. Päivän muut rivit säilyvät, ja päivä jää luonnokseksi, jonka työntekijä vahvistaa itse. Valinnalla Replace the Day’s Entries rivistä tulee päivän ainoa. Jos päivää on muokattu samaan aikaan Kelomossa tai se on jo vahvistettu, Zap pysähtyy ja kertoo syyn eikä kirjoita mitään. Kun kenttä Member jätetään tyhjäksi, rivi kirjataan avaimen omistajan omalle päivälle; toisen henkilön päivä vaatii esihenkilön oikeuden ja organisaation asetuksen, jolla esihenkilö saa kirjata toisen puolesta. Samasta lähdetietueesta toistettu ajo ei kirjoita riviä kahdesti, kun kenttään Source Record ID viedään lähdetietueen tunniste.

Hyväksyntä tehdään aina omalla toiminnollaan: Approve Work Day ja Return Work Day käsittelevät vahvistetun työpäivän, Approve Absence ja Reject Absence poissaolopyynnön. Palautus ja hylkäys vaativat perustelun, jonka työntekijä näkee. Invite Member lisää henkilön organisaatioon ja lähettää hänelle kutsun sähköpostiin.

Haut Find Member (sähköpostiosoitteella), Find Invoice (laskun numerolla), Find Lead (nimen, yrityksen tai otsikon osalla) ja Find Work Day (henkilö ja päivä) lukevat tiedot, joihin tapahtuma viittaa. Uudet tapahtumat kertovat muun muassa vahvistetusta, palautetusta ja korjatusta työpäivästä, perutusta poissaolosta, maksetusta ja erääntyneestä laskusta, henkilön lisäämisestä, muutoksesta, passivoinnista ja työsuhteen päättymisestä sekä kaupan, liidin ja kenttätyön muutoksista.

Power Automate

Microsoft 365 -talossa Kelomo yhdistetään mukautetulla liittimellä. Valmis liitin on ladattavissa kehittäjäportaalista Power Automate -liitin: se sisältää samat rekisterien tuontitoiminnot ja haut, työpäivät ja hyväksynnät sekä tapahtumakäynnistimen.

1. Lataa liitinmääritys portaalin sivulta.
2. Valitse Power Automatessa Data → Custom connectors → New custom connector → Import an OpenAPI file.
3. Luo yhteys ja liitä avain kokonaisuudessaan muodossa Bearer kelomo_….
4. Kokeile yhteyttä toiminnolla Check the connection.

Kirjoittavat toiminnot vaativat palveluavaimen, jonka omistajalla on organisaation hallintaoikeus.

Vuon poistaminen purkaa myös käynnistimen tilauksen: Kelomon vastaus kertoo tilauksen osoitteen, jota Power Automate kutsuu vuota poistettaessa. Yksittäisen tilauksen voi poistaa myös kohdasta Asetukset → Integraatiot → Webhookit tai liittimen toiminnolla Delete an event subscription.

Yhdistetyt sovellukset

Tekoälyavustajat ja muut valmiit sovellukset yhdistetään kirjautumalla, ei avainta kopioimalla: sovelluksessa valitaan Kelomo, käyttäjä kirjautuu, valitsee organisaation ja hyväksyy pyydetyt oikeudet. Sovellus toimii hyväksyjän oikeuksilla eikä koskaan saa enempää kuin mitä hänellä itsellään on — jos sovellus pyytää laajempia oikeuksia, hyväksyntänäyttö kertoo sen etukäteen.

Yhteydet näkyvät kohdassa Asetukset → Integraatiot → API-avaimet ja sovellukset osiossa Yhdistetyt sovellukset: mikä sovellus, kenen oikeuksilla ja milloin viimeksi käytetty. Omat yhteytesi näet omissa asetuksissasi välilehdellä Tekoälyassistentti, jossa on myös yhdistämisen ohjeet (katso Yhdistä tekoälyassistentti). Katkaise yhteys purkaa sen heti — sovelluksen seuraava kutsu ei enää mene läpi. Salasanan vaihto tai palautus katkaisee kaikki tilisi yhdistetyt sovellukset.

Yhdistetylle sovellukselle ei koskaan anneta oikeutta hallita organisaation asetuksia, laskutusta tai API-avaimia. Jos integraation on tehtävä sellaista, se tarvitsee palveluavaimen, jonka ihminen luo itse.

API-dokumentaatio ja MCP

Kehittäjädokumentaatio on osoitteessa kelomo.fi/developers: autentikointi, tapahtumat, virhekoodit, käyttörajat ja OpenAPI-kuvaus. Samasta paikasta löytyy MCP-ohje ja OAuth-ohje. MCP-yhteys toimii kummallakin tavalla: asiakas kirjautuu (suositus) tai käyttää kelomo_-avainta. Kummassakin tapauksessa tekoälysovellus toimii tunnisteen oikeuksien rajoissa.

Netvisor- ja Lemonsoft-yhteys

Yhteys luodaan kohdassa Asetukset → Integraatiot → Yhteydet. Sama yhteys palvelee palkka-, laskutus- ja matka-aineiston siirtoa.

Tee nämä ensin Netvisorissa:

1. Luo rajapintatunnukset: Yritysvalikko → Ohjelmistorajapintatunnukset → Luo uusi rajapintatunnus. Avain näytetään vain kerran. Tunnus on käyttäjäkohtainen, joten siirto lakkaa toimimasta, jos käyttäjä poistetaan.
2. Salli rajapintaresurssit: Yritysvalikko → Rajapintaresurssien käyttöoikeudet. Tarvittavat resurssit ovat workday.nv, getrecordtypelist.nv, getemployees.nv ja salesinvoice.nv sekä customerlist.nv ja purchaseinvoicelist.nv, jos asiakasluonti tai ostolaskujen tuonti on käytössä.
3. Anna kirjauslajeille numerot Netvisorissa. Ne ovat oletuksena tyhjiä, ja numero kohdistaa tunnit oikealle lajille.
4. Tarkista tuotekoodit ja asiakasnumerot Netvisorin rekistereistä. Ne täytetään vientikohteen vastaavuuksiin.

Netvisorin kentät: käyttäjätunnus (Customer ID) ja avain tulevat rajapintatunnuksesta, ja Y-tunnus on sen yrityksen, jonka Netvisoriin tiedot viedään.

Lemonsoftin kentät: rajapintakäyttäjä (ei henkilökohtainen tunnus), Lemonsoftin myöntämä avain ja tietokanta (Asetukset → Tiedot Lemonsoftissa). Osoite täytetään vain, jos Lemonsoft on antanut oman osoitteen.

Jos jokin menee pieleen

Avaimen arvo ei ole enää tallessa. Arvoa ei näytetä uudelleen. Vaihda oma avain tai luo uusi avain ja mitätöi vanha.

Palveluavain vastaa virheellä 401. Jos avaimen omistaja on passivoitu, avain lakkaa toimimasta. Osoita avain toiselle jäsenelle painikkeella Vaihda omistaja.

Pyyntö vastaa virheellä 403. Avaimen oikeudet eivät riitä, tai avain on Vain luku. Luo uusi avain tarvittavilla oikeuksilla.

Webhook-toimitus ei mene perille. Kun toimitushistoriassa lukee Pysyvästi epäonnistunut, tarkista vastaanottavan palvelun osoite ja vastaus, korjaa vastaanottaja ja valitse Lähetä uudelleen.