Opprett kunder, planer og abonnementer via API-et
Historisk tilbakeblikk – november 2025 til april 2026 Denne artikkelen ble skrevet i ettertid og samler den dokumenterte utvidelsen av API-ressursene.
Historisk tilbakeblikk – november 2025 til april 2026
Denne artikkelen ble skrevet i ettertid og samler den dokumenterte utvidelsen av API-ressursene.
API-et lar et eksternt system holde Aluntas kjerneregistre synkronisert. Arbeid med objektene i naturlig rekkefølge: Opprett eller finn kunden, opprett en plan med gyldige priser og intervaller, og opprett deretter abonnementet.
Bruk teamets personlige token fra Innstillinger → API for disse kallene. Partner-OAuth er en egen autoriseringsvei for partnerintegrasjoner og endrer ikke hvordan teamets API-token opprettes eller tilbakekalles.
Kunder og stabile koblinger
Opprett en kunde med et navn; dette er det eneste obligatoriske feltet i OpenAPI-kontrakten. E-post, telefon, adresse, postnummer, by og country er valgfrie. Hvis du sender country, bruker du en ISO 3166-1 alpha-2-kode med store bokstaver, for eksempel DK; hvis den utelates, bruker kontrakten landkoden til teamet som standard. Et valgfritt external_customer_id kan inneholde referansen fra systemet ditt. Lagre både den eksterne referansen og Aluntas UUID; de løser forskjellige behov. Ikke gjenbruk en ekstern referanse for flere kunder uten en uttrykkelig koblingsregel.
Planer og intervaller
Les planens pricing_type først. For en vanlig plan henter du fornyelsesintervallene og bruker en gyldig renewal_interval_uuid. En trinnbasert plan har ingen rader med fornyelsesintervaller i denne samlingen; bruk det dokumenterte interval og currency for trinnprisen sammen med trinninndataene som kreves ved opprettelse. Sørg alltid for at pris, valuta, pristype og betalingsleverandør passer sammen. En plan er en gjenbrukbar beskrivelse av det som selges. Den er ikke det samme som kundens gjeldende pris eller startdato.
Abonnementet
Når kunden og planen er klare, oppretter du abonnementet med planens UUID, kundens UUID og enten en UUID for fornyelsesintervallet eller paret med trinnintervall og valuta som planen tilbyr. Et syntetisk eksempel på en trinnbasert plan kan bruke de fiktive, ikke-eksisterende UUID-ene {"plan_uuid":"00000000-0000-4000-8000-000000000002","customer_uuid":"00000000-0000-4000-8000-000000000001","interval":1,"currency":"DKK"}; bruk det gjeldende OpenAPI-skjemaet for nøyaktige feltnavn og eventuelle senere trinnendepunkter. Svaret er den stabile kilden til abonnementets UUID og status. Les det på nytt etter opprettelsen hvis integrasjonen trenger å vise startdato, pris eller betalingsopplysninger.
Bankkontoer kan opprettes, oppdateres, leses og slettes via de dokumenterte bankkontoendepunktene. Dette holder et eksternt administrasjonsgrensesnitt eller ERP-grensesnitt synkronisert; opprettelse av en bankkonto flytter ikke penger og endrer ikke automatisk betalingsstatusen til en faktura.
Feil og avgrensninger
422 kan bety at landkode, valuta, intervall eller betalingsleverandør ikke passer til forespørselen. Et manglende intervall er ingen grunn til at klienten skal finne på et alternativ. Les paginering, feltnavn og statuser fra OpenAPI, og håndter beløp i enheten som er dokumentert i det relevante skjemaet.
Se veiledningen for offentlig API og webhooks (Markdown-fil, AI-agentvenlig) for den gjeldende rekkefølgen og eksemplene med syntetiske UUID-er.
Et fullstendig eksempel
Et eksternt salgssystem kan først sende en kunde med external_customer_id: "crm_demo_42", lagre UUID-en som returneres og deretter hente planens fornyelsesintervaller. Hvis planen har en EUR-pris for 12 måneder, skal klienten ikke opprette abonnementet med DKK eller et intervall planen ikke tilbyr. Etter opprettelsen lagrer du abonnements-UUID-en og leser statusen tilbake. En senere webhook kan da kobles både til den eksterne kunde-ID-en og Aluntas egne referanser.
Hvis kunden allerede finnes, bør integrasjonen bruke sin egen unike kobling eller søke etter den dokumenterte identiteten før den oppretter en ny. API-et skal ikke deduplisere bare etter navn. Hvis en bankkonto slettes, bør klienten også kontrollere gjeldende regler for standardkonto og bruk; CRUD-operasjoner for bankkontoer er ikke betalingskommandoer.
Hvorfor mangler et intervall? For en vanlig plan mangler det en gyldig fornyelsesintervallpris. For en trinnbasert plan er en tom samling av fornyelsesintervaller forventet; les trinnprisene, og bruk intervall sammen med valuta.
Kan jeg endre en plan uten å endre hvert abonnement? En plankatalog og et eksisterende abonnement er forskjellige ting; les endepunktbeskrivelsen og abonnementsvaret.
Hva skal jeg gjøre med 422? Vis feltfeilen, korriger den ugyldige kombinasjonen, og send samme forretningsintensjon på nytt først når inndataene er gyldige.
Menneskene og KI-hjelperne bak oppdateringene
Bo Møller og Emil Højbjerg er hovedutviklerne bak Alunta. De bruker mesteparten av tiden på å kode og har derfor overlatt formuleringen av disse forklaringene til KI-hjelperne våre.
KI-hjelperne skriver med utgangspunkt i oppdateringene vi har publisert. Bo og Emil står bak endringene og har ansvar for at informasjonen gjenspeiler det som faktisk er lansert.
