Klarbon for developers

Start in three steps

1. Sign in and create an API key on your account page. The key is shown once, so keep it somewhere safe.
2. Send it with each call as Authorization: Bearer kb_live_.... Never put it in the address: such keys are refused.
3. Your first key brings 25 free API calls. For more, buy an API pack on your account page, or credits on the pricing page, or switch on auto top-up.

Quick start

Convert an invoice to XRechnung. Every route takes the file the same way; the API reference lists them all.

curl

curl https://klarbon.app/api/v1/convert \
  -H "Authorization: Bearer $KLARBON_API_KEY" \
  -H "Idempotency-Key: convert-invoice-4711" \
  -F file=@invoice.xml -F target=xrechnung

JavaScript (Node.js 20 or later)

import { readFile, writeFile } from "node:fs/promises"

const form = new FormData()
form.append("file", new Blob([await readFile("invoice.xml")]), "invoice.xml")
form.append("target", "xrechnung")

const response = await fetch("https://klarbon.app/api/v1/convert", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KLARBON_API_KEY}`,
    "Idempotency-Key": "convert-invoice-4711",
  },
  body: form,
})
const result = await response.json()
if (!result.ok) throw new Error(result.message)
await writeFile(result.file.filename, Buffer.from(result.file.content, "base64"))

Python (with requests)

import base64
import os

import requests

with open("invoice.xml", "rb") as invoice:
    response = requests.post(
        "https://klarbon.app/api/v1/convert",
        headers={
            "Authorization": f"Bearer {os.environ['KLARBON_API_KEY']}",
            "Idempotency-Key": "convert-invoice-4711",
        },
        files={"file": invoice},
        data={"target": "xrechnung"},
        timeout=120,
    )
result = response.json()
if not result["ok"]:
    raise RuntimeError(result["message"])
with open(result["file"]["filename"], "wb") as written:
    written.write(base64.b64decode(result["file"]["content"]))

What it costs

Paid calls spend your API balance first: prepaid API packs, bought by card on your account page, and 25 free calls that your first key brings. When the API balance is empty they spend the same credits as the site, plan credits first; bought credits cost €4.99 for one, €29.00 for 10 or €99.00 for 50. The site never spends the API balance. A call that fails costs nothing.

One API call pays for the same work as one credit.

A paid call answers with a credits block: what it spent, the API balance left in apiCalls and the credits left. When the API balance and the credits are both too low it answers 402 no_credits with topUpUrl before any work is done.

Auto top-up

Save a card on your account page, pick a pack and a threshold. When a call leaves your balance below the threshold, Klarbon buys the pack with that card, with the same receipt as any purchase. The API balance and the credits each have a setting of their own, with an API pack or a credit pack. Payments are made in advance, never billed afterwards. If a payment is declined or your bank asks you to confirm it, that auto top-up switches itself off and we email you.

Limits

• Files up to 20 MB, PDFs up to 50 pages.
• 60 requests a minute per key, in bursts of up to 10, and 120 a minute per account across its keys.
• Requests that reach rate limiting carry RateLimit and RateLimit-Policy headers; a per-minute rate-limit refusal carries Retry-After in seconds.
• Up to 10 keys per account. Auto top-up of credits and of the API balance each run at most 3 times a day.

Privacy

Files are processed for the request, without a document archive. Logs carry no file name, no content and no key. Only a keyed hash of each API key is stored.

Versioning

Version 1 only grows: new routes, new optional parameters, new fields. Clients should ignore fields they do not know. A breaking change ships as version 2 next to version 1, which then stays for at least 12 months.