Finago / 24SevenOffice integrasjon mot Shopify Plus

En Finago / 24SevenOffice integration mot Shopify består av tre operasjoner: opprett kunde, opprett faktura, registrer betaling. Det høres trivielt ut. Det er det ikke — fordi betalingsregistreringen kun finnes i Finago sitt legacy SOAP-API, mens resten av flyten kjører på den moderne REST-en. Du må håndtere to autentiseringssystemer, en sesjonsovergang midt i scenariet, og en kundemodell som ikke har et naturlig oppslagspunkt.

Denne posten beskriver mønsteret vi bruker i produksjon, hva som faktisk er vanskelig, og hva du må passe på hvis du bygger dette selv.

Når Finago er riktig valg

24SevenOffice — som heter Finago i enkelte markeder, samme produkt — er et norsk regnskaps- og ERP-system. Vi kobler Shopify mot Finago når en merchant vil ha faktura per ordre, automatisk opprettet og umiddelbart markert som betalt med riktig betalingsmetode.

Sammenlignet med Tripletex sin fakturaflyt er Finago en streng utvidelse: i tillegg til å opprette kunde, ordre og faktura, registrerer vi også betalingen mot fakturaen i samme flyt. Bøkene lukkes i én operasjon.

Hvis merchanten ikke trenger per-kunde-fakturering, og bokholderen heller vil ha aggregerte bilagsføringer per uke, er PowerOffice GO et bedre valg. Det er en annen integrasjonsklasse, ikke en variant av samme.

Arkitekturen i grove trekk

Vi bygger denne integrasjonen i Make.com. Make passer her fordi flyten er forgrenet — kunde-finnes-router, gateway-basert kontovalg, REST-til-SOAP-overgang — og fordi merchant-teamet trenger å kunne inspisere kjøringer visuelt når noe feiler.

Hovedflyten ser slik ut:

1. Bulk-hent ordrer fra Shopify via GraphQL innenfor et datointervall.
2. Filtrer på fulfilled + financial_status paid, og hopp over ordrer flagget som «Faktura».
3. Slå opp kunden i en Make.com Data Store (Shopify-epost → Finago-kunde-ID).
4. Hent OAuth-token mot Finago REST.
5. Opprett salgsordre i draft-status, inline kunde-objekt hvis kunden er ny.
6. Slå opp fraktproduktet i Finago, legg til fraktlinje.
7. Iterer linje-elementer, hopp over refunderte, slå opp produkt på SKU, opprett linje.
8. PATCH salgsordren til status Invoice.
9. Velg bankkonto basert på betalingsgateway (Vipps, kort, gavekort).
10. SOAP Login, GetIdentity, og RegisterInvoicePayment — fakturaen markeres som betalt.

To autentiseringssystemer i samme scenario

REST: OAuth 2.0 client credentials

REST-delen autentiseres mot login.24sevenoffice.com/oauth/token med grant_type=client_credentials. Body-parameterne inkluderer client_id, client_secret, audience (https://api.24sevenoffice.com) og login_organization. Det siste er kjekt å vite: Finago er multi-tenant, og uten login_organization vet token-tjenesten ikke hvilken bok du skal skrive til.

Resultatet er et access_token som brukes som Bearer-header på alle REST-kall.

SOAP: sesjonsbasert login

SOAP-API-et har sin egen Login-operasjon på AuthenticateSoap-porten. Du sender Username, Password, ApplicationId og en tom IdentityId, og får tilbake et LoginResult — en sesjons-ID. Den må sendes som cookie-header på alle påfølgende SOAP-kall: Cookie: ASP.NET_SessionId={LoginResult}.

Sesjonen utløper. Hvis scenariet ditt har lange pauser eller henter store batcher mellom SOAP Login og RegisterInvoicePayment, er sesjonen død når du kommer dit. Vår tommelfingerregel: SOAP-blokken kjøres som siste segment per ordre, ikke som et felles preamble for hele batchen.

Kunde-oppslag: Data Store eller direkte mot Finago

I dagens produksjonsmønster slår vi opp kunder i en Make.com Data Store som mapper Shopify-epost til Finago-kunde-ID. Hvis kunden finnes, bruker vi den lagrede ID-en. Hvis ikke, sender vi kundedataene inline i POST-bodyen til /v1/salesorders, og Finago oppretter kunden automatisk.

Dette er teknisk gjeld. Det renere mønsteret er å spørre Finago direkte — GET /v1/customers?email=… — slik vi gjør i Tripletex-integrasjonen. Data Store-tilnærmingen var sannsynligvis en workaround rundt en tidligere API-begrensning som ikke nødvendigvis gjelder lenger.

Det er også en aktiv feil i nåværende oppsett: når en ny kunde opprettes via inline-POST, oppdateres ikke Data Store med den nye Finago-kunde-ID-en. Konsekvensen er at neste ordre fra samme kunde lager en ny duplikat i Finago. Hvis du bygger dette i dag: enten skriv tilbake til Data Store etter opprettelse, eller hopp Data Store-mønsteret og gå rett mot Finago.

Linjer, rabatter og refusjoner

For hver linje på Shopify-ordren slår vi opp produktet i Finago på variant-SKU via /v1/products?productSearch. URL-en bruker prosent-tegn som SQL-wildcard (URL-enkodet som %25), så vi får treff også når SKU er en delstreng av Finagos produktnavn.

Rabatt beregnes per linje som prosent av differansen mellom original og rabattert enhetspris. Det er samme formel som i Tripletex B2C, og den fungerer fordi Shopify allokerer ordre-rabatter til linjer før vi ser dataene.

Refunderte linjer filtreres bort eksplisitt. Vi mapper over order.refunds[].refund_line_items[].line_item_id, flater listen, og sjekker om gjeldende linje-ID er med. Hvis den er det, hoppes linjen over. Dette er den reneste refusjonshåndteringen vi har i noen integrasjon, og den bør egentlig porteres til Tripletex B2C og PowerOffice GO også.

Fra ordre til faktura til betalt faktura

Salgsordren opprettes som draft. Etter at frakt og linjer er lagt til, PATCH-er vi salgsordren til status Invoice med en distributionMethod på manualdistribution — det betyr at Finago ikke prøver å sende fakturaen automatisk til kunden, vi har allerede levert kvitteringen via Shopify.

Forfallsdato settes til ordredato + 14 dager. Det er en konvensjon, ikke en regel — diskuter med bokholderen om dere vil ha en annen frist for nettbutikkordrer.

Deretter går vi over til SOAP. Login, GetIdentity for å validere sesjonen, og til slutt RegisterInvoicePayment med fakturanummer, beløp og bankkonto. Det er denne siste operasjonen som lukker bilaget. Uten den ville bokholderen måtte registrere betalingen manuelt for hver ordre.

Produktstruktur og SKU-stabilitet

Hele integrasjonen henger på variant-SKU. Finagos produktoppslag bruker SKU som primær søkenøkkel, og vi har ingen annen stabil identifikator på tvers av Shopify og Finago.

Det betyr at strukturelle endringer i Shopify-katalogen er en risiko. Vi har sett dette konkret hos en nordisk apparel-merchant som migrerte fra én-produkt-per-farge til ett produkt med fargevarianter. Så lenge SKU-ene migreres 1:1 over til de nye variantene, er omleggingen transparent for Finago. Hvis SKU-formatet endres i samme operasjon, brytes produktoppslaget og fakturalinjene matcher ikke produktmasteret lenger.

Cutover-sekvensen vi anbefaler: publiser den nye sammenslåtte produktstrukturen, avpubliser (ikke slett) de gamle per-farge-produktene, vent én full faktura- og fulfillment-syklus for å bekrefte at Finago prosesserer nye ordrer rent, og først da slett de gamle produktene.

Sikkerhet rundt credentials

Når du bruker rå HTTP-moduler i Make.com — som er nødvendig for Finago sitt SOAP-API — havner Authorization-headere direkte i scenario-JSON. Eksporterer du scenariet for backup eller dokumentasjon, eksporteres credentials med.

Mønsteret vi bruker: legg sensitive verdier i Make sine organisasjons-nivå Custom Variables og refererer dem som getCustomVariable('finagoSoapPassword'). Verdiene følger ikke med scenario-eksporter. Litt mer oppsett, men du slipper at credentials lekker via en JSON-fil noen sender på Slack.