Att mata in en uppgift en gång i stället för tre

En kund lägger en order i webbutiken. Någon skriver in kunden i kundregistret. Någon skriver in samma order i bokföringen. Samma uppgifter, tre gånger, av samma person en fredagseftermiddag.

Det är sällan det tar tid som är problemet. Det är att de tre versionerna glider isär. Adressen är rätt på ett ställe och gammal på ett annat, och ingen vet längre vilken som gäller.

Att koppla ihop systemen löser det, men bara om kopplingen byggs för att gå sönder på ett begripligt sätt. Nedan står vad ett API är, vilka tre vägar som finns, vad kostnaden består av och vad som faktiskt händer när leverantören uppdaterar.

Vad ett API är, utan facktermer

Ett API är en lista över frågor ett system svarar på och kommandon det tar emot, plus exakt hur de ska formuleras.

Fortnox API har till exempel egna adresser för kunder, artiklar, ordrar och fakturor. Ert system skickar en begäran dit och får ett svar tillbaka. Ni behöver aldrig veta hur Fortnox fungerar inuti, bara vilka fält som ska med och i vilket format.

Standardorganet bakom OpenAPI, den vanligaste formen för att beskriva sådana gränssnitt, formulerar poängen väl: beskrivningen ska göra att både människor och datorer kan förstå vad en tjänst kan göra, utan tillgång till källkoden och utan att behöva avlyssna trafiken.

Två saker följer av det. Ett API är ett löfte om ett gränssnitt, inte om en funktion. Och gränssnittet ägs av leverantören, vilket betyder att de får ändra i det. Mer om det längre ned.

Inloggningen är inte ett lösenord

En koppling loggar inte in som en människa. Den använder OAuth 2.0, en standard som IETF beskrev i RFC 6749 redan 2012 och som i dag används av i stort sett alla molntjänster.

Principen är att ni ger en app begränsad åtkomst till ert konto utan att lämna ifrån er lösenordet. Hos Fortnox ser det ut så här enligt deras egen dokumentation: en användare godkänner kopplingen och en authorization-code skapas som gäller i tio minuter. Den byts mot en access-token som gäller i en timme, och en refresh-token som gäller i 45 dagar.

Den sista siffran är den viktiga. Ligger integrationen stilla längre än 45 dagar blir refresh-token ogiltig, och Fortnox skriver att kopplingen då måste aktiveras om av en användare på Fortnox-kontot. En integration som bara används i bokslutet är alltså trasig varje gång ni behöver den.

Behörigheterna avgränsas med scopes. Fortnox skriver att varje scope ger både läs- och skrivrättigheter till sina adresser, och att det inte går att få enbart läsrättigheter genom deras API. Det är värt att veta innan någon påstår att kopplingen “bara läser”. De skriver också att företaget måste ha licens för resursen i fråga, och att ett anrop mot ett konto utan API-licens ger felkoden 2001103.

Tre vägar, i den ordning ni ska pröva dem

Färdig koppling

Leta först. Fortnox egen lista över kopplingar rymmer flera hundra poster i kategorin e-handel och ett femtiotal under CRM, plus egna kategorier för butikssystem, bokningssystem och tid- och projektredovisning.

Har ni ett vanligt system i andra änden finns kopplingen sannolikt redan. Den kostar en avgift, den är underhållen av någon annan, och när Fortnox ändrar något är det leverantörens problem att rätta.

Nackdelen är att den gör det den gör. Vill ni att artikelnumret ska översättas enligt er egen tabell, eller att en order ska vänta på godkännande innan den faktureras, hjälper inte en kryssruta.

Integrationsplattform

Nästa steg är ett verktyg där ni bygger flödet själva utan att skriva kod. Zapier, Make och Power Automate är de vanligaste. Microsoft beskriver Power Automate som en tjänst för att bygga automatiserade flöden mellan appar och tjänster.

Betalningsmodellen är värd att förstå innan ni väljer. Zapier säljer paket per antal körda tasks i månaden. Make räknar operations, vilket enligt deras dokumentation är en modulkörning som behandlar eller kontrollerar data. En order som passerar sex steg kostar alltså sex gånger så mycket som en som passerar ett. Ett flöde som körs varje minut för att titta efter nya rader blir dyrt fort, även när det inte hittar något.

Plattformarna passar bra för flöden med få steg och måttlig volym, och för att prova en idé innan någon bygger den på riktigt. De passar sämre när logiken blir grenig eller när ni behöver kunna felsöka en enskild order tre månader senare.

Egen utveckling

Det tredje alternativet är att bygga kopplingen själva, eller låta någon göra det åt er. Det är rätt val när flödet är ert eget: när begreppen inte matchar, när det finns regler som bara gäller hos er, eller när flera system ska hållas i takt samtidigt.

Egen utveckling ger också kontroll över det tråkiga, och det tråkiga är det som avgör om kopplingen håller. Vad som loggas. Vad som händer vid ett fel. Hur man kör om en order utan att skapa en dubblett. Sådant beskriver vi under skräddarsydda system.

Priset är att någon äger den. Kod utan underhåll blir sämre av att stå still.

Vad kostnaden faktiskt består av

Vi sätter inga belopp här, eftersom spannet är för brett för att en siffra ska betyda något. Men de fyra delarna är alltid desamma.

Antal parter. Två system som pratar är en koppling. Tre system är tre kopplingar om alla ska prata med alla. Rita det innan ni beställer.

Hur väl begreppen matchar. Det här är den post som oftast underskattas. Är er “kund” samma sak som deras “kund”? Har ni artikelnummer som stämmer på båda ställena? Vad händer med en rabattrad, en frakt, eller en order med blandade momssatser? Merparten av arbetet i ett integrationsprojekt går åt till att svara på sådana frågor, inte till att skicka data.

Riktning. Envägs är enkelt. Tvåvägs kräver att ni bestämmer vilket system som vinner när samma uppgift ändrats på båda ställena samma dag, och att kopplingen inte skickar tillbaka sin egen ändring i en rundgång.

Det löpande. Någon ska titta till kön, läsa leverantörens ändringsmeddelanden och laga när något går sönder. Räknar ni inte med den posten kommer den ändå.

Går flödet hela vägen till fakturan hänger det ihop med hur ni skickar den. Kraven på elektroniska fakturor har vi skrivit om i e-faktura och Peppol, och den löpande hanteringen beskriver vi under fakturering och betalningar.

Vad som går sönder vid uppdateringar

Fortnox är ovanligt tydliga med sin ändringspolicy, och den är läsvärd även om ni använder ett annat system. De delar in släpp i fyra sorter.

• Felrättningar aviseras en vecka i förväg.
• Mindre uppdateringar med nya funktioner aviseras en månad i förväg.
• Större uppdateringar aviseras tre månader i förväg, och Fortnox skriver att de kan sakna bakåtkompatibilitet med tidigare versioner.
• Akuta rättningar går ut utan förvarning.

Allt annonseras på deras utvecklarblogg. Det betyder att någon ska läsa den, och att ni bör veta vem redan när kopplingen byggs. En integration utan en namngiven ansvarig är en integration som lagas först när någon klagar.

Den andra vanliga orsaken till att något slutar fungera är volym. Fortnox anger gränsen till 300 anrop per minut per client-id och konto, mätt i ett glidande fönster om fem sekunder, vilket i praktiken blir 25 anrop per fem sekunder. Överskrids den svarar API:et med HTTP 429. En koppling som hämtar tusen artiklar en och en vid varje körning slår i taket, medan samma koppling som hämtar ändringar sedan i går aldrig märker av den.

Bygg så att det går att laga

Fem saker skiljer en koppling som håller från en som blir ett supportärende.

1. Loggning per post. Varje order, faktura eller kund som passerar ska gå att slå upp: vad skickades, vad svarade mottagaren, när. Utan det är felsökning gissning.
2. Kö och omförsök. Går ett anrop fel ska posten hamna i en kö och försökas igen, med ökande väntetid. Ett tillfälligt avbrott hos leverantören ska inte kräva en människa.
3. Idempotens. Kopplingen ska kunna köra om samma order utan att skapa en andra faktura. I praktiken betyder det att varje post har en identitet som mottagaren känner igen.
4. Larm som når någon. Ett fel som bara syns i en logg ingen läser är inte upptäckt. Larmet ska gå till en person, inte till en delad brevlåda.
5. En avstängning. Det ska gå att stoppa flödet utan att stänga av hemsidan.

Punkt tre är den som oftast saknas. Symptomet är två identiska fakturor med olika nummer, och det märks först när kunden ringer.

Vad ni ska ha ordning på innan ni börjar

Innan någon skriver en rad kod ska fyra saker vara bestämda.

Vilket system som är sanningskälla för varje uppgift. Kundens adress bor på ett ställe, och de andra läser därifrån. Bestäms inte det i förväg bestäms det av vem som råkade skriva sist.

Vad som ska hända manuellt. Allt ska inte automatiseras. En order över ett visst belopp kan gärna passera en människa, och det är ett medvetet val, inte ett misslyckande.

Hur ni testar. De flesta leverantörer erbjuder ett testkonto. Använd det, och kör aldrig första gången mot skarp bokföring.

Vem som är personuppgiftsbiträde. Flyttar kopplingen kunduppgifter mellan system är den som driver tjänsten biträde åt er. IMY skriver att det då ska finnas ett skriftligt personuppgiftsbiträdesavtal. Samma sak gäller en integrationsplattform: era kunders namn och adresser passerar deras servrar.

Till det kommer bokföringslagens krav. Räkenskapsinformation ska bevaras fram till och med det sjunde året efter utgången av det kalenderår då räkenskapsåret avslutades, och elektroniska handlingar ska bevaras i det format och med det innehåll de hade. En integration som skriver om historiken i efterhand är alltså inte bara olämplig, den strider mot lagen.

Samma resonemang, andra system

Fortnox används här för att deras utvecklardokumentation är öppen och konkret. Mönstret är detsamma hos Visma, Björn Lundén, Shopify och de flesta bokningssystem: ett HTTP-API, inloggning enligt OAuth 2.0, behörigheter per område och en gräns för antalet anrop.

Detaljerna skiljer sig, och det är därför ni alltid ska läsa just den leverantörens dokumentation innan någon lovar något. Men frågorna är samma fyra: vad finns färdigt, vad äger vi själva, vad händer när de ändrar, och vem lagar det.

Hur kundregistret hänger ihop med resten har vi skrivit om i vad ett CRM-system är, och vad vi själva sätter upp står under CRM och kontakthantering.

Nästa steg

Ta en av era vanligaste uppgifter, till exempel en ny order, och skriv ned varje ställe den skrivs in på i dag och av vem. Listan blir oftast längre än väntat, och den är underlaget för allt annat.

Vill ni ha hjälp att rita den kan ni beställa en gratis analys. Vi går igenom vilka system ni har, var samma uppgift skrivs in flera gånger och vad som går att koppla ihop med något som redan finns.