API, webhooks, OAuth og MCP: overblik over udviklerfladen

LedgerBees udviklerflade lader dig forbinde din egen software og AI-agenter til dit firma i LedgerBee. Den samler API-nøgler, webhooks, OAuth-klienter og MCP ét sted.

Hvor finder du det

Åbn venstremenuen og vælg Integrationer ("Integrations") – siden ligger på /system/integrations og har fire faner:

• Integrationer – kataloget over tredjepartsforbindelser (marketplace).
• Webhooks – dine webhook-endpoints. Hvert endpoint har sin egen detaljeside på /system/integrations/webhooks/ .
• API-nøgler ("API Keys") – langlivede nøgler til server-til-server-integrationer.
• OAuth-klienter ("OAuth Clients") – med underfanerne OAuth-klienter og Forbundne apps ("Connected apps").

Fanerne Webhooks, API-nøgler og OAuth-klienter er kun synlige for firmaadministratorer. Almindelige brugere ser kun integrationskataloget.

Den offentlige udviklerdokumentation ligger på docs.ledgerbee.com, og selve API'et serveres fra https://api.ledgerbee.com/api. På fanerne Webhooks, API-nøgler og OAuth-klienter finder du desuden en Udviklerguide ("Developer guide")-knap med valgmulighederne Copy for LLM, Download markdown og Open docs site, så du eller din AI-assistent kan hente den relevante guide direkte.

Hvad kan du bruge API'et til

Via det offentlige API kan en integration læse firmadata og kontoplanen, håndtere kunder og leverandører, oprette posteringer, køre abonnementsfakturering, sende fakturaer, kreditnotaer, tilbud og ordrebekræftelser, administrere varer og priser, registrere webhooks og mere. API'et er versioneret i stien (de fleste endpoints ligger under v1, enkelte posterings-endpoints har v2-efterfølgere) og ændres kun additivt: Der kan komme nye felter til, men eksisterende felter bliver aldrig omdøbt, fjernet eller ændret i type.

Tre typer legitimation

• API-nøgler: langlivede hemmeligheder, der sendes med hver forespørgsel – bedst til server-til-server-integrationer.
• OAuth-klienter: bruger client-credentials-flowet til at udstede kortlivede bearer-tokens (én time).
• Forbundne apps: AI-agenter og andre apps, der har fået adgang gennem et brugergodkendt OAuth-login. Det er sådan, MCP-serveren (grænsefladen for AI-agenter) autoriseres.

Derudover kan udgående webhooks sende signerede hændelsesnotifikationer (abonnementslivscyklus, fakturering, kunder, gemte kort, tilbud, ordrebekræftelser og projekter) til dine egne HTTPS-endpoints, så du ikke behøver at polle API'et.

Centrale begreber

• API-nøgle – en hemmelighed pr. firma, oprettet under Integrationer > API-nøgler og sendt i request-headeren x-api-key. Har et navn, valgfri beskrivelse, valgfri udløbsdato, valgfri IP-whitelist og et sæt scopes. Nøgleværdien vises kun én gang ved oprettelsen.
• Scope – en tilladelse på en nøgle eller OAuth-klient, der afgør, hvilke endpoints den kan nå (fx "Journal Entries: Read" eller "Subscriptions: Write"). Grupperes som læse/skrive pr. område.
• Rotation (API-nøgle) – genererer en ny nøgleværdi; den gamle virker i 10 minutter, så du kan nå at skifte i dine applikationer.
• IP-whitelist – valgfri liste over IP-adresser, en nøgle eller klient må bruges fra. Forespørgsler fra andre IP'er afvises med 401, hvor årsagen fremgår.
• Webhook-endpoint – en offentlig HTTPS-URL hos dig, der abonnerer på et eller flere hændelsesemner. Ved oprettelsen får du en signeringshemmelighed (med præfikset whsec_), som kun vises én gang.
• Emner (topics) – de hændelsestyper, et endpoint abonnerer på, grupperet som Abonnement, Fakturering, Kunde, Kort, Tilbud, Ordrebekræftelse og Projekt (fx "subscription.billed", "billing.invoice_sent", "customer.created", "card.expiring", "quote.converted", "project.archived").
• Signering (Standard Webhooks) – hver levering har tre headere (webhook-id, webhook-timestamp, webhook-signature). Signaturen er en HMAC-SHA256 over besked-id, afsendelsestidspunkt og den rå body og kan verificeres med endpointets signeringshemmelighed.
• Leveringsstatus – hver levering i endpointets log er Afventer ("Pending"), Leveret ("Delivered") eller Fejlet ("Failed"). Detaljesiden viser totaler, succesrate, gennemsnitlig svartid, en graf over leveringer over tid og en Kør nu ("Run now")-handling til at gentage en levering med det samme.
• OAuth-klient – en maskine-til-maskine-legitimation (klient-id + klienthemmelighed) oprettet under Integrationer > OAuth-klienter. Veksles til et bearer-token, der lever 3600 sekunder. Har scopes, valgfri IP-whitelist, aktiv/inaktiv status og en klienttype vist som Menneske ("Human") eller Agent.
• Primær/sekundær hemmelighed – en OAuth-klient kan have to hemmeligheder samtidig, så du kan rotere uden nedetid: Generér den sekundære, skift dine apps over, og tilbagekald derefter den primære.
• Forbundne apps – listen over apps (typisk AI-agenter), der har fået adgang gennem et brugergodkendt OAuth-login. Kolonner: App, Version, Godkendt af, Scopes, Udstedt og Senest brugt. Apps kan omdøbes pr. firma, få tilladelser redigeret (træder i kraft med det samme) eller frakobles (tilbagekalder adgang og aktive sessioner øjeblikkeligt).
• MCP-server – LedgerBees grænseflade for AI-agenter (Claude, ChatGPT, Cursor, VS Code, Codex og andre MCP-klienter). Én forbindelse er knyttet til præcis ét firma. Autorisation sker via OAuth 2.1 med browserlogin – ingen API-nøgle er nødvendig. Der findes desuden en separat, anonym udvikler-MCP-server, der kun serverer de offentlige udviklerguides.
• Autorisationsskærm – siden Godkend adgang ("Authorize access") på /oauth/consent, hvor en bruger godkender en apps forbindelse. Den viser, hvilket firma der gives adgang til, advarer om ikke-verificerede eller helt nyregistrerede apps og lader brugeren vælge præcis, hvilke tilladelser der gives (ønskede scopes er markeret og forvalgt).
• MCP-sessionsparring – når en MCP-forbundet agent vil styre appens brugerflade, spørger appen "Par MCP-session med denne fane?" ("Pair MCP session with this tab?"). Den parrede fane er den, agent-styrede handlinger (fx at åbne en postering) navigerer i, og den viser indikatoren Styres af ... ("Controlled by ...") med handlingen Stop styring ("Stop being controlled").
• Salary API – en lille, udfaset kompatibilitetsflade for en lønintegration med endpoints for konti, kassekladder, kladdetransaktioner og filupload under en v2-sti. Den bruger de samme API-nøgler og scopes som det offentlige API og findes kun, indtil integrationen er flyttet til standard-endpoints. Nye integrationer bør bruge de almindelige endpoints i stedet.

De vigtigste regler

• Alle hemmeligheder på siden (API-nøgleværdier, webhook-signeringshemmeligheder, OAuth-klienthemmeligheder) vises præcis én gang ved oprettelsen og kan ikke hentes frem igen. Løsningen er altid at rotere eller oprette en ny.
• Scopes og licenser er to uafhængige adgangskrav. Et kald skal opfylde begge: Et manglende scope giver 403 med en "insufficient permissions"-fejl, mens et firma uden modulets licens får 403 med en "license required"-fejl, der nævner den licens, der skal aktiveres. MCP-endpoints kræver, at firmaet har MCP-licensen.
• Ressource-endpoints har i dag ingen fast forespørgselskvote, men din integration bør altid behandle en 429 som noget, der kan prøves igen.
• Når et firma offboardes, deaktiveres dets webhook-endpoints, og MCP-adgange tilbagekaldes.