Skapa kunder, planer och prenumerationer via API:et

Historisk tillbakablick – november 2025 till april 2026
Den här artikeln skrevs i efterhand och samlar den dokumenterade utökningen av API-resurser.

API:et låter ett externt system hålla Aluntas centrala poster synkroniserade. Arbeta med objekten i deras naturliga ordning: skapa eller hitta kunden, skapa en plan med giltiga priser och intervall och skapa därefter prenumerationen.

Använd teamets personliga token från Inställningar → API för dessa anrop. Partner-OAuth är en separat auktoriseringsväg för partnerintegrationer och ändrar inte hur teamets API-token skapas eller återkallas.

Kunder och stabil mappning

Skapa en kund med ett namn; det är det enda obligatoriska fältet enligt OpenAPI-kontraktet. E-postadress, telefon, adress, postnummer, ort och country är valfria. Om du skickar country använder du en ISO 3166-1 alpha-2-kod med versaler, till exempel DK; om den utelämnas använder kontraktet teamets land som standard. Ett valfritt external_customer_id kan innehålla ditt systems referens. Spara både den externa referensen och Aluntas UUID; de löser olika problem. Återanvänd inte en extern referens för flera kunder utan en uttrycklig mappningsregel.

Planer och intervall

Läs planens pricing_type först. För en vanlig plan hämtar du dess förnyelseintervall och använder ett giltigt renewal_interval_uuid. En plan med nivåer har inga rader för förnyelseintervall i den samlingen; använd i stället nivåprisets dokumenterade interval och currency tillsammans med de indata för nivån som krävs när prenumerationen skapas. Kontrollera alltid att pris, valuta, prismodell och betalningsleverantör passar ihop. En plan är en återanvändbar beskrivning av vad som säljs. Den är inte samma sak som kundens faktiska pris eller startdatum.

Prenumerationen

När kunden och planen är klara skapar du prenumerationen med planens UUID, kundens UUID och antingen ett UUID för förnyelseintervall eller det par av intervall och valuta som planen med nivåer erbjuder. Ett syntetiskt exempel med nivåer kan använda de påhittade och obefintliga UUID:na {"plan_uuid":"00000000-0000-4000-8000-000000000002","customer_uuid":"00000000-0000-4000-8000-000000000001","interval":1,"currency":"DKK"}; använd det aktuella OpenAPI-schemat för exakta fältnamn och efterföljande nivåändpunkter. Svaret är den stabila källan till prenumerationens UUID och status. Läs av det igen efter skapandet om integrationen behöver visa startdatum, pris eller betalningsuppgifter.

Bankkonton kan skapas, uppdateras, läsas och tas bort via de dokumenterade ändpunkterna för bankkonton. Det håller ett externt administrations- eller ERP-gränssnitt synkroniserat; skapandet av ett bankkonto flyttar inte pengar och ändrar inte automatiskt en fakturas betalningsstatus.

Fel och avgränsningar

422 kan betyda att en landskod, valuta, intervall eller betalningsleverantör inte passar i begäran. Ett saknat intervall är inte ett skäl för klienten att hitta på ett alternativ. Läs paginering, fältnamn och statusar i OpenAPI och hantera belopp i den enhet som anges i relevant schema.

Se guiden om publikt API och webhooks (Markdown-fil, AI-agentvenlig) för aktuell ordning och exempel med syntetiska UUID:n.

Ett fullständigt exempel

Ett externt säljsystem kan först skicka en kund med external_customer_id: "crm_demo_42", spara det returnerade UUID:t och sedan hämta planens förnyelseintervall. Om planen har ett EUR-pris för 12 månader får klienten inte skapa prenumerationen i DKK eller med ett intervall som planen inte erbjuder. Efter skapandet sparar du prenumerationens UUID och läser tillbaka dess status. En senare webhook kan då kopplas till både den externa kundreferensen och Aluntas egna referenser.

Om kunden redan finns bör integrationen använda sin egen unika mappning eller söka efter den dokumenterade identiteten innan en till skapas. API:et ska inte deduplicera enbart efter namn. Om ett bankkonto tas bort ska klienten även kontrollera aktuella regler för standardkonto och användning; CRUD-åtgärder för bankkonton är inget betalningskommando.

Varför saknas ett intervall? För en vanlig plan saknas ett giltigt pris för förnyelseintervallet. För en plan med nivåer är en tom samling för förnyelseintervall förväntad; läs nivåpriserna och använd intervall tillsammans med valuta.

Kan jag ändra en plan utan att ändra alla prenumerationer? En plankatalog och en befintlig prenumeration är olika saker; läs ändpunktens beskrivning och prenumerationens svar.

Vad ska jag göra med 422? Visa felfältet, korrigera den ogiltiga kombinationen och skicka samma avsikt igen först när indata är giltiga.