Billy API: sådan kobler du Billy på webshop, CRM og betaling

Kort svar: Billy API er et JSON-baseret REST-API, som lader andre systemer oprette fakturaer, kontakter og varer, registrere betalinger og hente posteringer i Billy. Det er det samme API, som Billys egen webapp bruger, så næsten alt hvad du kan gøre i programmet, kan også gøres via API'et. Adgangen er enkel: Du opretter et adgangstoken i Billy og sender det med i hvert kald. Til gengæld er der ingen OAuth-godkendelse for tredjepartsapps og ingen dokumenterede webhooks, og det former, hvordan en integration bør bygges.

Hvad er Billy API?

Billy er et dansk regnskabsprogram, som ifølge Billy selv bruges af over 30.000 selvstændige (Billy). Billy er i dag en del af Shine, hvilket står øverst på Billys egen hjemmeside (Billy).

Billy API v2 er et JSON-baseret REST-API. Billy skriver, at deres egen webapp bruger nøjagtigt det samme API, og at det derfor altid understøtter den fulde funktionalitet. Alle kald går til https://api.billysbilling.com/v2 og skal bruge SSL (Billy API v2 Documentation). Spørgsmål til API'et sendes til dev@billy.dk.

Hvad kan man koble med Billy API?

Billys appunivers er delt op i kategorier som webshop, betaling, CRM, løn, kassesystem og time- og sagsstyring. Her finder du blandt andet Shopify, Magento 2, Stripe, MobilePay, Zettle, Shopbox, Minuba og LeadCraft (Billy). Det er et godt sted at starte, før I overvejer at bygge selv.

Sådan fungerer adgangen til Billy API

Billy understøtter to måder at logge ind på (Billy API v2 Documentation):

• Adgangstoken. Brugeren logger ind i Billy, går til indstillingerne og opretter et adgangstoken med et beskrivende navn (i dokumentationen hedder stien Settings → Access tokens). Tokenet sendes i headeren X-Access-Token. Det gælder kun én virksomhed, og det udløber ikke.
• HTTP Basic Auth. Du kan også logge ind med brugerens e-mail og adgangskode. Det er praktisk til et hurtigt test i browseren, men til en integration er et adgangstoken det sikre valg, så ingen adgangskode ligger i jeres system.

GET https://api.billysbilling.com/v2/invoices?page=1&pageSize=100
X-Access-Token: <adgangstoken>
Accept: application/json

Billy skriver, at de planlægger at understøtte en trebenet OAuth-løsning på et tidspunkt (Billy API v2 Documentation). Indtil da er der ingen godkendelsesknap, hvor kunden klikker "Tillad". Skal en integration bruges af flere virksomheder, må hver kunde selv oprette et token og overdrage det, og har en kunde flere virksomheder, skal der et token til hver.

Hvilken pakke kræver det?

Billys prisside lister "ubegrænsede integrationer" under Plus-pakken (Billy). API-dokumentationen nævner ikke et pakkekrav for egne adgangstokens, så spørg Billy, før I bygger en integration til en virksomhed på Free eller Basic.

Sådan er API'et bygget

Billy API er usædvanligt konsekvent, og det gør det hurtigt at arbejde med, når man først kender mønstret (Billy API v2 Documentation):

• Fem handlinger. Hver ressource tilgås med sit navn i flertal, fx /v2/invoices, og understøtter hent én, list, opret, opdater og slet.
• Alt der ændres, kommer med i svaret. Opretter du en fakturalinje, indeholder svaret også fakturaen med det nye beløb.
• Relationer i ét kald. Med parameteren include kan du hente fx en faktura med linjer og kunde på én gang, enten sideloaded eller embedded.
• Atomiske gem. Opretter du en faktura med linjerne indlejret, gemmes enten det hele eller intet.
• Betaling via bankPayments. En faktura markeres som betalt ved at oprette en bankbetaling, der matcher beløbet og peger på fakturaen.

Begrænsninger at kende

• Sider. Lister hentes med page og pageSize. pageSize kan højst være 1.000, hvilket også er standarden. Svaret viser i meta.paging, om der er flere sider (Billy API v2 Documentation).
• Filtre der stille ignoreres. Ukendte parametre bliver ikke afvist, men ignoreret. Et filter med en stavefejl giver derfor bare en ufiltreret liste uden fejlbesked. Filtre på relationer skal have endelsen Id, fx accountId (Billy API v2 Documentation).
• Ingen webhooks i dokumentationen. API-dokumentationen beskriver hverken webhooks eller en fast grænse for antal kald. En integration, der skal opdage ændringer, må derfor hente data med jævne mellemrum, og den bør stadig sprede kaldene og håndtere fejl pænt.

Byg selv eller brug en færdig app?

Til de klassiske flows, som salg fra Shopify eller betalinger fra Stripe og MobilePay, findes der færdige apps i Billys appunivers, og de er næsten altid hurtigere og billigere end at bygge selv (Billy).

En egen integration mod Billy API giver mening, når I har et system uden færdig kobling, fx et branchesystem, et hjemmebygget bookingsystem eller et tidsregistreringsværktøj, der skal fakturere timer på den rigtige kunde. Fordi Billy bruger faste tokens og ingen webhooks, er det typisk en mindre integration end mod e-conomic eller Dinero, men den skal bygges med et tidsplanlagt job i stedet for hændelser. Se hvordan vi arbejder med Billy-integration, systemintegration og AI-automatisering. Vil I koble Billy sammen med andre værktøjer uden kode, så læs Hvad er n8n?, og sammenlign gerne med e-conomic API og Dinero API.

Typiske faldgruber

• Tokens der aldrig udløber. Et lækket token giver adgang, indtil nogen sletter det i Billy. Gem det krypteret, og giv hver integration sit eget navngivne token, så det kan slås fra uden at stoppe resten.
• Adgangskoder i koden. Brug ikke Basic Auth med en medarbejders login i en integration. Skifter personen adgangskode eller stopper, stopper integrationen også.
• Tavse filterfejl. Test hvert filter mod kendte data, da et forkert parameternavn ikke giver fejl.
• Dubletter. Uden webhooks og hændelses-ID'er skal integrationen selv huske, hvilke ordrer den har sendt, så samme ordre ikke bliver til to fakturaer.
• Moms og konti. Lad bogholderen godkende konti og momssatser, før I går live.