API-dokumentation

Klirros REST-API låter ditt system skapa och skicka fakturor, läsa status, hålla mottagar- och artikelregister synkade samt ta emot webhooks när något händer. Alla anrop går mot https://klirro.app/api/public/v1.

Autentisering

API-nycklar utfärdas av Klirro-teamet per konto och visas bara en gång. Skicka nyckeln som Bearer-token. Nyckeln ger åtkomst till exakt det konto den tillhör.

curl https://klirro.app/api/public/v1/invoices \
  -H "Authorization: Bearer klirro_sk_din_nyckel"

Endpoints

Skapa och skicka en faktura

Sätt send: true för att skapa och skicka i ett anrop. Vid skickning tilldelas fakturanummer och en kredit dras från kontot.

curl -X POST https://klirro.app/api/public/v1/invoices \
  -H "Authorization: Bearer klirro_sk_din_nyckel" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "name": "Exempel AB", "email": "ekonomi@exempel.se" },
    "due_date": "2026-04-30",
    "currency": "SEK",
    "lines": [
      { "name": "Konsulttimmar", "qty": 10, "unit": "Timme", "price": 1200, "vat_rate": 25 }
    ],
    "send": true
  }'

Webhooks

Registrera en https-adress så skickar vi en POST vid händelser: invoice.created, invoice.sent, invoice.paid, recipient.created, article.created. Vid registrering får du en signeringshemlighet som bara visas en gång.

Varje anrop har headern Klirro-Signature, en HMAC-SHA256 i hex av {timestamp}.{body} med din hemlighet, samt Klirro-Timestamp. Verifiera signaturen innan du litar på innehållet.

const expected = crypto
  .createHmac("sha256", process.env.KLIRRO_WEBHOOK_SECRET)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");

Fel

Fel returneras som JSON med kod och meddelande, t.ex. unauthorized, not_found, insufficient_credits.

{ "error": { "code": "insufficient_credits", "message": "insufficient_credits" } }