API och integrationer

Kelomos publika gränssnitt används med API-nycklar. Organisationens nycklar hanteras under Inställningar → Integrationer → API-nycklar och appar och webhookarna på sidan Webhookar i samma grupp. Din egen personliga nyckel skapar du i dina egna inställningar på fliken Egna API-nycklar.

Två slags nycklar

• En personlig nyckel agerar med dina behörigheter och når högst lika långt som du själv. Nyckeln upphör när ditt medlemskap upphör. Varje användare kan skapa en egen.
• En tjänstenyckel är till för integrationer som ska fungera oberoende av en enskild person. Den har en namngiven Ägare – den medlem vars behörigheter nyckeln agerar med – och ägaren kan bytas senare med knappen Byt ägare; token, behörigheter och historik består. Tjänstenycklar skapas av administratören.

Skapa en nyckel

1. Tryck på Ny nyckel (egen nyckel) eller Ny tjänstenyckel (organisationen).
2. Ange Nyckelns namn och vid behov en beskrivning. För en tjänstenyckel väljs också Ägare.
3. Välj Nyckelns behörigheter. Endast de behörigheter nyckelns innehavare själv har går att välja. En personlig nyckel utan valda behörigheter når bara dina egna uppgifter; en tjänstenyckel kräver minst en behörighet.
4. Välj Giltighet (30 dagar, 90 dagar, 1 år eller utan förfall) och kryssa vid behov i Skrivskyddad.
5. Spara. Nyckelns värde börjar med kelomo_ och skickas i begäranden i huvudet Authorization: Bearer.

Värdet visas bara en gång. Kopiera det genast. Om värdet kommer bort kan du byta den egna nyckeln med Byt nyckel – den gamla gäller i 24 timmar till – eller skapa en ny nyckel.

Hantera nycklarna

Listan visar nyckelns början, skapelsedatum, senaste användning och antalet begäranden under sju dagar. Återkalla tar nyckeln ur bruk permanent. Om en nyckel närmar sig sitt förfall skickar Kelomo en avisering i förväg, så att du hinner förnya den före avbrottet.

Webhookar

På sidan Webhookar skickar Kelomo valda händelser till den adress du anger – till exempel publicerade skift, fakturahändelser och frånvarobeslut.

1. Tryck på Lägg till webhook och ange Adress. Adressen måste börja med https://.
2. Välj Meddelandetyp: JSON (signerad) för integrationer, Slack eller Microsoft Teams för färdiga meddelanden till kanalens incoming webhook-adress. För Slack och Teams väljs också Meddelandespråk.
3. Välj Händelser.
4. Spara. För JSON-typen visas signeringshemligheten (X-Kelomo-Signature) – även den bara en gång.

Radens åtgärder: Testa skickar ett testmeddelande, Inaktivera stoppar leveranserna och Aktivera återupptar dem. Byt hemlighet roterar signeringshemligheten (den gamla gäller i 24 timmar till). Typen kan inte bytas i efterhand – skapa vid behov en ny webhook.

Webhookens adress i listan öppnar dess sida med Leveranshistorik. En misslyckad leverans försöks om automatiskt; raden visar tiden för nästa försök, och leveransen kan skickas om manuellt med åtgärden Skicka igen. Om en leverans slutgiltigt inte går fram får du en avisering.

Zapier

Kelomo finns som färdig koppling i Zapier. En Zap startar från en händelse i Kelomo, till exempel ett nytt lead, en vunnen affär, ett offertbeslut, en inlämnad eller beslutad frånvaro, en godkänd arbetsdag, ett publicerat skift, ett färdigt löneunderlag, en skickad faktura, en bokförd betalning eller en ändring i en kund, ett projekt eller en uppgift. Åtgärderna Create Lead, Create Task, Create Customer och Create Intake Item skapar ett lead, en uppgift, en kund eller en arbetsbegäran i Kelomo. Registrens importåtgärder, arbetsdagar och godkännanden beskrivs längre ner.

1. Skapa en tjänstenyckel som beskrivs ovan. Ge den behörigheten Hanterar webhookar och integrationshändelser samt behörigheten för de händelser du använder: säljhändelser kräver behörighet till säljytan, frånvaro och arbetsdagar chefens behörighet, skift skiftplaneringens och fakturor samt betalningar faktureringens behörighet. Om Zappen skapar data i Kelomo, lämna Skrivskyddad omarkerad.
2. Öppna Kelomos inbjudningslänk i Zapier, Kelomo i Zapier, och godkänn inbjudan. Därefter hittar du Kelomo i Zapiers appsökning.
3. Bygg Zappen. När du väljer Kelomo första gången ber Zapier dig ansluta kontot: klistra in nyckeln i fältet API Key. Fältet API URL har Kelomos adress som standardvärde.

Exempelhändelsen som Zapier visar hämtas bland organisationens senaste händelser, så testa Zappen först när Kelomo har minst en sådan händelse. Händelsen innehåller identifierare, status och tidpunkter. Varje Zap skapar sin egen rad i listan Webhookar, och när Zappen tas bort försvinner raden.

Recept: projekt från ett annat verktyg som uppföljningsobjekt

När projekten lever i Jira kan de bli uppföljningsobjekt i Kelomo utan projektmodulen. Skapa först en uppföljningsnivå, till exempel ”Projekt (Jira)”.

Zappen startar av en ny eller uppdaterad issue i det valda Jira-projektet. Kelomos åtgärd Create or Update Tracking Target skapar objektet eller uppdaterar det: välj nivån i listan, ange issuens nyckel som kod, rubriken som namn, en egen namnrymd som källa (till exempel jira_acme_issue) och issuens id som identifierare. När issuen når ett tillstånd som avslutar arbetet skickar du samma åtgärd med fältet Active som falskt: objektet tas ur bruk och timmarna som bokats på det finns kvar. Nästa steg i Zappen hämtar objektets uppgifter med Find Tracking Target, som söker på koden eller på källans identifierare.

Åtgärden behöver en servicenyckel vars ägare har administratörsrätt i organisationen. Samma recept fungerar för andra källor som Zapier erbjuder en händelse för.

Kunder, projekt och uppgifter på samma sätt

Samma mönster sträcker sig till de tre andra registren. Åtgärderna Create or Update Customer, Create or Update Project och Create or Update Task känner igen raden först på källans identifierare och först därefter på koden, så en andra körning på samma källpost uppdaterar raden i stället för att skapa en ny. Åtgärderna Find Customer, Find Project och Find Task söker med en enda nyckel: koden, källans identifierare eller Kelomos identifierare. En uppgift söks inom sitt projekt med källans identifierare eller med uppgiftens nummer.

Namnrymden skiljer systemet, miljön och posttypen åt (hubspot_acme_company, jira_acme_project, jira_acme_issue), så två källor kan aldrig krocka i samma organisation. Koden ges en gång och ändras inte av en senare synkronisering: löneunderlaget och bokföringens överföringar känner igen raden på den.

Går raden igenom oförändrad skrivs ingenting i Kelomo och ingen anteckning blir kvar i historiken. Avvisas raden stannar Zappen och säger varför: de vanligaste orsakerna är att koden redan tillhör en annan källa, att raden är gjord för hand och kräver valet Adopt an Existing Record by Code, eller att raden varken har kod eller identifierare.

Åt andra hållet berättar triggrarna vad som hände i Kelomo: kund skapad eller ändrad, projekt skapat, ändrat eller stängt, uppgift skapad, ändrad eller flyttad till en annan kolumn. Händelsen innehåller identifierare och tidpunkt, så nästa steg är en Find-åtgärd.

Uppgiftens status från källan

Källans status är källans eget ord (“In Progress”, “Klaar”, “3”). Det anges i fältet External Status, och Kelomo översätter det under Inställningar → Projekt → Statusmotsvarigheter: källa, extern status och Kelomos statustyp. Ett ord som saknas i tabellen stoppar Zappen – Kelomo gissar ingen kolumn. Fyll i motsvarigheterna före den första körningen.

Recept: ett Jira-projekt och dess uppgifter till Kelomo

1. Zappen startar med Jira Software Cloud → New Issue på den valda tavlan.
2. Create or Update Customer för in kunden: namnet från Jiras organisationsfält, källa jira_acme_org, identifierare organisationens id. Hoppa över steget om kunderna redan finns i Kelomo.
3. Create or Update Project för in projektet: namnet från epicens rubrik, Customer Code koden från föregående steg, källa jira_acme_project, identifierare Jira-projektets id och Status från Jiras status (Done → closed).
4. Create or Update Task för in uppgiften: Project Code koden från föregående steg, rubriken från issuets rubrik, källa jira_acme_issue, identifierare issuets id, External Status namnet på Jiras status och Assignee Email den ansvarigas adress.
5. Gör en andra Zap på händelsen Updated Issue med samma tre åtgärder.

Receptet har inte körts mot ett riktigt Jira-konto – det är skrivet utifrån åtgärderna och gränssnittet. Kelomos del är verifierad genom att köra åtgärderna mot en utvecklingsserver.

Arbetsdagar, godkännanden och personer

Add Work Entries lägger till en rad på en arbetsdag: start och slut eller längd i minuter, tidtyp och projekt ur listan samt en anteckning. Dagens övriga rader finns kvar, och dagen förblir ett utkast som den anställda själv bekräftar. Med valet Replace the Day’s Entries blir raden dagens enda. Om dagen har ändrats i Kelomo samtidigt eller redan är bekräftad, stannar Zappen och anger orsaken utan att skriva något. När fältet Member lämnas tomt registreras raden på nyckelägarens egen dag; en annan persons dag kräver chefens behörighet och organisationens inställning som låter chefen registrera för någon annans räkning. En upprepad körning från samma källpost skriver inte raden två gånger när fältet Source Record ID får källpostens id.

Ett godkännande görs alltid med en egen åtgärd: Approve Work Day och Return Work Day hanterar en bekräftad arbetsdag, Approve Absence och Reject Absence en frånvaroansökan. Återsändning och avslag kräver en motivering som den anställda ser. Invite Member lägger till en person i organisationen och skickar en inbjudan per e-post.

Sökningarna Find Member (med e-postadress), Find Invoice (med fakturanummer), Find Lead (med en del av namnet, företaget eller rubriken) och Find Work Day (person och dag) läser uppgifterna som en händelse hänvisar till. De nya händelserna gäller bland annat bekräftade, återsända och korrigerade arbetsdagar, avbokad frånvaro, betalda och förfallna fakturor, tillagda, ändrade och inaktiverade personer, avslutade anställningar samt ändringar i affärer, leads och fältarbete.

Power Automate

I ett Microsoft 365-hus ansluts Kelomo med en anpassad koppling. En färdig koppling finns att hämta i utvecklarportalen Power Automate-koppling: den innehåller samma importåtgärder för registren och deras sökningar, arbetsdagar och godkännanden samt en händelsetrigger.

1. Hämta kopplingsdefinitionen från portalens sida.
2. Välj i Power Automate Data → Custom connectors → New custom connector → Import an OpenAPI file.
3. Skapa en anslutning och klistra in nyckeln i sin helhet i formen Bearer kelomo_….
4. Pröva anslutningen med åtgärden Check the connection.

Skrivande åtgärder kräver en servicenyckel vars ägare har administratörsrätt i organisationen.

Att radera flödet säger också upp triggerns prenumeration: Kelomos svar anger prenumerationens adress, som Power Automate anropar när flödet raderas. En enskild prenumeration kan också tas bort under Inställningar → Integrationer → Webhookar eller med kopplingens åtgärd Delete an event subscription.

Anslutna appar

AI-assistenter och andra färdiga appar ansluts genom inloggning, inte genom att kopiera en nyckel: i appen väljer man Kelomo, användaren loggar in, väljer organisation och godkänner de begärda rättigheterna. Appen arbetar med godkännarens rättigheter och får aldrig mer än hen själv har — om appen begär mer omfattande rättigheter säger godkännandeskärmen det i förväg.

Anslutningarna visas under Inställningar → Integrationer → API-nycklar och appar i avsnittet Anslutna appar: vilken app, med vems rättigheter och när den senast användes. Dina egna anslutningar ser du i dina egna inställningar på fliken AI-assistent, som också har anvisningarna för anslutningen (se Anslut en AI-assistent). Avsluta anslutning bryter den omedelbart — appens nästa anrop går inte igenom. Ett lösenordsbyte eller en lösenordsåterställning avslutar alla anslutna appar på ditt konto.

En ansluten app får aldrig rätt att hantera organisationens inställningar, fakturering eller API-nycklar. Om en integration behöver göra sådant krävs en tjänstenyckel som en människa skapar själv.

API-dokumentation och MCP

Utvecklardokumentationen finns på kelomo.fi/developers: autentisering, händelser, felkoder, användningsgränser och OpenAPI-beskrivningen. Där finns också MCP-guiden och OAuth-guiden. MCP-anslutningen fungerar på båda sätten: klienten loggar in (rekommenderas) eller använder en kelomo_-nyckel. I båda fallen agerar AI-klienten inom referensens behörigheter.

Netvisor- och Lemonsoft-anslutning

Anslutningen skapas under Inställningar → Integrationer → Anslutningar. Samma anslutning används för löne-, fakturerings- och reseunderlaget.

Gör det här först i Netvisor:

1. Skapa gränssnittskoder: Företagsmenyn → Programgränssnittskoder → skapa en ny kod. Nyckeln visas bara en gång. Koden är användarspecifik, så överföringen slutar fungera om användaren tas bort.
2. Tillåt gränssnittsresurser: Företagsmenyn → Gränssnittsresursers rättigheter. Resurser som behövs är workday.nv, getrecordtypelist.nv, getemployees.nv och salesinvoice.nv samt customerlist.nv och purchaseinvoicelist.nv om kundskapande eller import av inköpsfakturor används.
3. Ge registreringstyperna nummer i Netvisor. De är tomma som standard, och numret styr timmarna till rätt slag.
4. Kontrollera produktkoder och kundnummer i Netvisors register. De anges i exportmålets motsvarigheter.

Netvisors fält: användar-id (Customer ID) och nyckel kommer från gränssnittskoden, och FO-numret är det företags vars Netvisor uppgifterna förs till.

Lemonsofts fält: gränssnittsanvändaren (inte en personlig inloggning), nyckeln som Lemonsoft utfärdar och databasen (Inställningar → Uppgifter i Lemonsoft). Adressen fylls i bara om Lemonsoft har uppgett en egen adress.

Om något går fel

Nyckelns värde finns inte längre kvar. Värdet visas inte på nytt. Byt den egna nyckeln eller skapa en ny nyckel och återkalla den gamla.

Tjänstenyckeln svarar med fel 401. Om nyckelns ägare har inaktiverats slutar nyckeln fungera. Tilldela nyckeln en annan medlem med knappen Byt ägare.

Begäran svarar med fel 403. Nyckelns behörigheter räcker inte, eller så är nyckeln Skrivskyddad. Skapa en ny nyckel med de behörigheter som behövs.

En webhookleverans går inte fram. När leveranshistoriken visar Permanent misslyckad, kontrollera mottagarens adress och svar, åtgärda mottagaren och välj Skicka igen.