← Billy API-integration

Billy API: en praktisk guide

Det, du skal vide for at læse data fra Billy: ét adgangstoken pr. virksomhed, sider på højst 1.000, relaterede data med include og beløb, der ligger på posteringer. Eksemplerne bruger præcis de stier og parametre, JaKonto selv kalder.

Indhold

  1. Login: X-Access-Token
  2. Paginering: page og pageSize
  3. Relaterede data: include med sideload eller embed
  4. Fakturaer: state, isPaid og balance
  5. Posteringer: beløbene ligger på /postings
  6. Faldgruber, vi selv er gået i
  7. Eller lad JaKonto gøre det

Login: X-Access-Token

Base-adressen er https://api.billysbilling.com/v2, kun over HTTPS. Send dit adgangstoken i headeren X-Access-Token.

Tokenet opretter du i Billy under Indstillinger → Adgangstokens → Opret adgangstoken. Det gælder én virksomhed og udløber ikke — har du flere virksomheder, skal hver have sit eget. Gem det krypteret.

curl https://api.billysbilling.com/v2/organization \
     -H "X-Access-Token: <ACCESS_TOKEN>" \
     -H "Content-Type: application/json"

Paginering: page og pageSize

Lister tager page og pageSize. pageSize er højst 1.000, og det er også standarden. Svaret har meta.paging med page, pageCount, pageSize, total og nextUrl — fortsæt, til page når pageCount.

import requests

H = {"X-Access-Token": "<ACCESS_TOKEN>"}
invoices, page = [], 1
while True:
    data = requests.get("https://api.billysbilling.com/v2/invoices", headers=H, timeout=30,
                        params={"page": page, "pageSize": 1000}).json()
    invoices += data["invoices"]
    if page >= data["meta"]["paging"]["pageCount"]:
        break
    page += 1

Relaterede data: include med sideload eller embed

Med include=ressource.felt:tilstand får du relaterede objekter i samme svar. sideload (standard) lægger dem i en egen liste ved siden af — f.eks. contacts ved siden af invoices; embed lægger dem inde i hvert objekt.

Svaret bruger ental og flertal som rod: {"invoice": {…}} for ét objekt, {"invoices": […]} for en liste.

curl -G https://api.billysbilling.com/v2/invoices \
     --data-urlencode 'include=invoice.contact:sideload' \
     -H "X-Access-Token: <ACCESS_TOKEN>"

→ {"meta": {…}, "invoices": [{"contactId": "…", …}], "contacts": [{"id": "…", "name": "…"}]}

Fakturaer: state, isPaid og balance

state er kun draft, approved eller voided. Om en faktura er betalt, står ikke i state, men i isPaid (true/false), og det ubetalte restbeløb står i balance. Begge felter er skrivebeskyttede og opdateres, når der registreres en betaling.

Vil du finde forfaldne fakturaer, så tag approved med isPaid=false og dueDate før i dag.

Posteringer: beløbene ligger på /postings

Beløb, konto og side (debit/kredit) ligger på /postings, ikke på /transactions. Afgræns perioden med minEntryDate og maxEntryDate (ÅÅÅÅ-MM-DD), udelad annullerede med isVoided=false, og hent konto og bilag med include.

curl -G https://api.billysbilling.com/v2/postings \
     --data-urlencode 'minEntryDate=2026-01-01' \
     --data-urlencode 'maxEntryDate=2026-06-30' \
     --data-urlencode 'isVoided=false' \
     --data-urlencode 'include=posting.account:sideload,posting.transaction:sideload' \
     -H "X-Access-Token: <ACCESS_TOKEN>"

Faldgruber, vi selv er gået i

  • Ukendte eller forkert skrevne parametre ignoreres stille — du får hele listen ufiltreret. entryDatePeriod skal f.eks. skrives dates:2026-01-01...2026-06-30 med tre punktummer; med komma kommer alle posteringer tilbage.
  • En betalt faktura har stadig state approved. Ser du kun på state, tæller alle betalte fakturaer som åbne tilgodehavender.
  • Beløb er kroner med decimaler; regn i øre (heltal), før du summerer.
  • Billy har ingen dokumenterede webhooks. Ændringer skal hentes med planlagt synkronisering.
  • Billy dokumenterer ingen rate limits. Hent store sider (pageSize=1000), og kald ikke parallelt mod samme virksomhed.

Eller lad JaKonto gøre det

JaKonto klarer token, paginering, sideload, betalingsstatus og posteringer og giver dig fakturaer, posteringer, konti og kontakter i samme form som fra e-conomic og Dinero — plus moms, resultatopgørelse og CSV. Billy-integrationen er i beta. Forbind med dit token:

curl -X POST https://jakonto.dk/api/v1/connections \
     -H "X-API-Key: jk_live_…" -H "Content-Type: application/json" \
     -d '{"system": "billy", "credentials": {"access_token": "<ACCESS_TOKEN>"}}'

curl https://jakonto.dk/api/v1/connections/$ID/invoices \
     -H "X-API-Key: jk_live_…"

Spørgsmål

Hvor er den officielle Billy API-dokumentation?

På billy.dk/api. Den beskriver hver ressource, dens felter og de filtre, en liste tager.

Hvor finder jeg mit Billy-adgangstoken?

I Billy under Indstillinger → Adgangstokens. Tokenet gælder én virksomhed og udløber ikke.

Hvor mange elementer kan jeg hente pr. side?

Højst 1.000 (pageSize=1000), som også er standard.

Har Billy webhooks?

Ikke dokumenterede. Ændringer hentes ved at synkronisere jævnligt.

Skriver JaKonto i Billy?

Nej. JaKonto læser kun.

e-conomic API-integration · Billy API-integration · Dinero API-integration · MCP-server