Hvorfor integrasjoner er der prosjekter dør

Når 80% er ferdig, og resten tar 80% av tiden

Den vanligste historien vi hører fra kunder som har fått brent fingrene på et utviklingsprosjekt, lyder ofte slik:

"Selve applikasjonen ble bygget på tid. Men så skulle den integreres mot ERP-en vår, og der stoppet alt. Vi måtte vente på leverandøren, dokumentasjonen var feil, det viste seg at API-et ikke støttet det vi trodde, og prosjektet ble forsinket med 4 måneder."

Det er ikke et unntak. Det er regelen for prosjekter som krever integrasjoner. Vi har sett det mange ganger, og lært å håndtere det annerledes.

Hvorfor integrasjoner er så vanskelige

Det er ikke fordi koden er kompleks. De fleste integrasjoner er strukturelt enkle: hente data fra ett system, sende data til et annet, håndtere feil. Kompleksiteten ligger andre steder.

Dokumentasjon som ikke matcher virkeligheten. ERP-leverandøren sier API-et returnerer et bestemt format. I praksis returnerer det noe litt annet, med felter som ikke er dokumentert, og uten felter som er dokumentert som obligatoriske. Det avdekker dere først når dere kaller API-et.

Leverandører som svarer langsomt. Når dere har et spørsmål om hvordan deres ERP håndterer en bestemt transaksjon, går spørsmålet inn i en kø hos en supportperson som ikke er teknisk. Svar tar 1–3 uker, og er ofte ikke svar på det dere spurte om.

Endringer i leverandørens system underveis. ERP-en oppgraderes i månedlige releaser. Noen av dem bryter API-et på subtile måter. Dere finner det ut den dagen jobben skal kjøre.

Autentisering som krever tilgang dere ikke har. Maskinporten-tilkobling krever virksomhetssertifikat, som krever organisasjons-godkjenning, som krever et skjema på papir signert av daglig leder. Mens dere venter, kan dere ikke teste integrasjonen i produksjon.

Rate-limiting og throttling. API-et tillater 100 kall i minuttet. Når dere skal kjøre en månedlig batch som krever 50 000 kall, må dere fordele over 8 timer. Det betyr ny arkitektur, ikke bare "skriv koden".

Data som er strukturert annerledes enn dere antok. Kundekartoteket i ERP-en har én "kunde" som i virkeligheten er ti underbedrifter delt på samme organisasjonsnummer. Dere må forstå datamodellen før dere kan bruke den.

Slik håndterer vi det

Vi har sluttet å estimere integrasjoner basert på "det ser ut som en standard integrasjon". I stedet behandler vi hver integrasjon som et eget mini-prosjekt med tre faser.

Fase 1: Teknisk gjennomgang før fastpris

Før vi gir fastpris på et prosjekt med integrasjoner, gjør vi 1–2 uker teknisk gjennomgang av hver integrasjon. Det inkluderer:

• Lese gjennom hele leverandørens API-dokumentasjon, ikke bare det vi trenger
• Sette opp en sandbox eller testmiljø, hvis tilgjengelig
• Gjøre reelle API-kall mot sandbox med ekte data
• Identifisere hva som ikke matcher dokumentasjonen
• Vurdere autentiserings-prosessen og hvor lang tid den tar
• Sjekke rate limits og operasjonelle begrensninger
• Snakke med leverandørens tekniske kontakt, hvis mulig

Resultatet av denne fasen er en konkret integrasjons-spesifikasjon, ikke bare en antakelse. Vi kjenner risikoområdene før fastpris settes.

Fase 2: Bygging med innebygd robusthet

Hver integrasjon bygges med samme fire elementer som standard:

1. Idempotens. Hver melding eller transaksjon har en unik ID. Hvis vi sender den to ganger, fordi nettverket falt og vi reprøvde, opprettes den bare én gang i målsystemet. Dette fjerner de fleste "dupliserte rader"-feilene vi har sett i tradisjonelle integrasjoner.

2. Retry med exponential backoff. Når et kall feiler fordi systemet er nede, prøver vi automatisk på nytt etter 1 sekund, 2 sekunder, 4 sekunder, 8 sekunder, opp til en max. Når systemet er tilbake, fortsetter vi der vi slapp. Ingen tapte meldinger, ingen menneskelig inngripen.

3. Køsystem. Alle integrasjons-meldinger går gjennom en kø (typisk Convex scheduler, eller dedikert message queue). Hvis den ene siden er treig eller nede, bygger køen seg opp, ikke produksjonsprosessen som genererer meldingene.

4. Audit-logg på alt. Hver eneste integrasjons-kall logges: når ble det sendt, hva ble sendt, hva ble svart, hvor lang tid tok det. Vi kan rekonstruere nøyaktig hva som skjedde for 12 måneder siden, hvis kunden spør.

Disse fire er ikke ekstra-kost. De er standardpakken. Forskjellen er at vi ikke trenger å fikse "tap av meldinger" som hendelse senere.

Fase 3: Overvåking i produksjon

Vi setter opp varsling på:

• Køer som vokser uvanlig fort (tegn på at noe har stoppet)
• Feilrate som plutselig stiger (tegn på at API-et har endret seg)
• Latens som plutselig øker (tegn på problemer hos leverandøren)
• Manglende meldinger fra et tredjeparts-system som normalt sender hver time

Dette betyr at vi oppdager problemer før kunden gjør det. Ofte ringer vi dem før de har sett det selv, og forklarer hva som skjer.

De mest krevende integrasjonene

Ulike kategorier systemer har ulike fallgruver. Her er hovedmønstrene vi forholder oss til:

ERP- og regnskapssystemer. De etablerte har som regel god dokumentasjon og fungerende API-er. Noen har flere API-versjoner samtidig, så å velge rett er viktig, og autentiserings-flyten varierer i kompleksitet.

CRM-systemer. Stort sett veldokumenterte og stabile. Flere av dem krever mer konfigurasjons-arbeid hos kunden enn man tror i utgangspunktet.

BankID og ID-porten. Stabile, men autentiserings-flyt krever forarbeid. Test grundig på testmiljø før produksjon.

Altinn og Maskinporten. Modne tjenester med tydelig dokumentasjon, men prosessen for å få virksomhets-sertifikat og scope-godkjenning tar tid. Vi starter det parallelt med utvikling.

Fagsystemer i helsesektoren. Ofte kompliserte. Krever som regel direkte dialog med leverandøren, ikke bare API-kall. Standardisering varierer mellom systemene, så vi reserverer god tid.

Eldre kommunale fagsystemer. Den mest krevende kategorien. Ofte gammel SOAP, ofte med autentisering basert på IP-whitelist, og dokumentasjon spredt i gamle Word-dokumenter. Vi forplikter oss ikke på fastpris uten betalt teknisk gjennomgang først.

Hva dere kan gjøre selv før prosjektstart

Hvis dere vurderer et prosjekt med integrasjoner, gjør disse tre tingene før utviklingen begynner:

1. Verifiser at dere har tilgang til testmiljøer. Mange integrasjons-prosjekter forsinkes med uker fordi sandbox-tilgang ikke er på plass. Be om det nå.

2. Innhent oppdatert API-dokumentasjon. Ikke det dere fant på leverandørens nettside, men det de gir til reelle integrasjons-partnere. Det inneholder ofte felter og krav som ikke er offentlig dokumentert.

3. Identifiser en teknisk kontakt hos leverandøren. Ikke supportskjema-veien, men en reell person dere kan ringe når noe er uklart. Det forkorter feilsøking fra uker til timer.

Disse tre tingene tar 1–2 uker hvis dere starter nå, og sparer ofte uker eller måneder senere.

Vår tilnærming

Vi har lært dette på den harde måten over mange prosjekter: integrasjoner er ikke der dere skal spare tid eller penger. Det er der dere skal investere ekstra i forberedelse og robusthet. Gevinsten er at systemene fungerer i produksjon, ikke bare i testmiljø.

Når dere snakker med en potensiell utviklingspartner, spør konkret: hvordan håndterer dere integrasjons-prosjekter? Hvis svaret er "vi følger best practices", er det vagt. Hvis svaret er "vi gjør teknisk gjennomgang før fastpris, bygger med idempotens og retry, og setter opp overvåking fra start", har dere noen som har gjort det før.

Snakk med oss om integrasjons-prosjektet dere vurderer, eller les om vår tilnærming til integrasjoner og systemutvikling.