Hjälpcentret · Guide för utvecklare

Koppla en e-handel till Bookigo

Bookigo har inga färdiga kopplingar till Shopify, Stripe, PayPal, Zettle eller WooCommerce. Det som finns är ett öppet API och webhooks, och med dem kan ni själva (eller en tjänst som Zapier eller Make, eller en utvecklare) skapa kunder och fakturor när en beställning kommer in och få besked när fakturan är betald. Guiden visar vad som finns och vad ni själva behöver ta hand om.

Hela API:t finns som OpenAPI-beskrivning.

Så går det till

1. Skapa en API-nyckel under Inställningar → Integrationer. Välj bara läsa om kopplingen aldrig ska skriva. Nyckeln visas bara en gång, och den kan ha ett utgångsdatum och vara begränsad till de IP-adresser som anropen kommer från.
2. Lägg nyckeln på den server eller i den tjänst som tar emot beställningarna, aldrig i webbläsaren eller i koden som kunderna når. Nyckeln gäller för ett företag och kan inte se något annat.
3. När en beställning är betald: skapa kunden (POST /customers) om den inte redan finns, och skapa sedan fakturan (POST /invoices) med en rad per orderrad.
4. Registrera betalningen (POST /invoices/{id}/payments) när webbutiken eller betalleverantören har bekräftat den, med rätt betalsätt (till exempel card eller swish).
5. Vill webbutiken få besked tillbaka: lägg till en webhook under Inställningar → Integrationer och välj händelserna ni behöver.

Adresser i API:t

Alla anrop går till /api/v1 med rubriken Authorization: Bearer fk_…. Svaren är JSON.

• POST /customers Skapa kunden från beställningen. Ett organisationsnummer som redan finns ger felet DUPLICATE (409).
• GET /customers Hämta kunder, om ni vill slå upp en kund innan ni skapar en ny.
• GET /products Hämta artiklarna med artikelnummer (sku), pris och momssats.
• POST /invoices Skapa ett fakturautkast, eller utfärda direkt med issue: true.
• POST /invoices/{id}/issue Utfärda ett utkast.
• GET /invoices/{id}/pdf Hämta fakturan som PDF.
• POST /invoices/{id}/payments Registrera en betalning som webbutiken eller betalleverantören tagit emot.
• GET /invoices/{id} Hämta fakturan med rader och betalningar.

Exempel

Kunden (POST /customers). Svaret innehåller kundens id.

{
  "type": "person",
  "name": "Anna Andersson",
  "email": "anna@example.se",
  "addressLine1": "Exempelgatan 1",
  "postalCode": "111 22",
  "city": "Stockholm",
  "country": "SE"
}

Fakturan (POST /invoices). Siffrorna är exempel och säger inget om vilken momssats eller vilket momsscenario som gäller för er försäljning.

{
  "customerId": "<kundens id från svaret ovan>",
  "invoiceDate": "2026-11-05",
  "dueDate": "2026-11-05",
  "paymentTermsDays": 0,
  "currency": "SEK",
  "vatScenario": "domestic",
  "orderNumber": "<webbutikens ordernummer>",
  "lines": [
    { "description": "Exempelartikel", "sku": "ART-1", "qtyMilli": 2000, "unit": "st", "unitPriceOre": 19900, "vatRate": 2500 }
  ],
  "issue": true
}

Betalningen (POST /invoices/{id}/payments). Betalsätten är bankgiro, plusgiro, bank_transfer, swish, card, cash och other.

{
  "amountOre": 39800,
  "paidAt": "2026-11-05",
  "method": "card",
  "reference": "<betalleverantörens referens>"
}

Gränser och sådant ni själva tar hand om

• Alla belopp anges i öre (1 kr = 100), antal i tusendelar (1500 = 1,5) och momssatser i baspunkter (2500 = 25 %). Beloppen ska alltså räknas om från webbutikens egna format.
• Momssatsen anges per rad och momsscenariot per faktura. Bookigo väljer dem inte åt er utifrån vad webbutiken säljer eller vart. Att de är rätt för försäljningen är ert ansvar, och frågor om moms vid försäljning till andra länder tar ni med er redovisningskonsult.
• API:t har ingen idempotensnyckel. Skickar ni samma beställning två gånger blir det två fakturor. Spara därför fakturans id tillsammans med beställningen hos er och kontrollera det innan ni skapar en ny faktura. Fältet orderNumber kan fyllas i med webbutikens ordernummer, men det går inte att filtrera fakturalistan på det.
• Det finns inget i API:t för avräkningar, utbetalningar eller avgifter från betalleverantören. Registrerar ni betalningen på fakturan bokförs betalningen, men hur leverantörens utbetalning och avgifter bokförs görs i Bokföring → Avräkningar eller på annat sätt i Bokföring.
• En utfärdad faktura kan inte ändras. Ett fel rättas med en kreditfaktura i Bookigo.
• Högst 120 anrop per minut och nyckel. Svaret 429 betyder att ni ska vänta en minut. Har företaget avslutats får ni 403 ORGANIZATION_CLOSED, och i läsläge (obetald faktura från Bookigo) får ni 403 READ_ONLY på anrop som skriver.

Få besked med webhooks

Bookigo skickar en signerad POST till er adress när något händer. Händelser som passar en e-handel:

• invoice.issued Fakturan är utfärdad och har fått nummer och OCR.
• payment.registered En betalning är registrerad (hel-, del- eller överbetalning).
• invoice.paid Fakturan är helt betald.
• invoice.credited Fakturan är krediterad.

Så ser en leverans ut. Rubrikerna är Bookigo-Event, Bookigo-Delivery och Bookigo-Signature.

{
  "id": "<leveransens id>",
  "event": "payment.registered",
  "createdAt": "2026-11-05T10:15:00.000Z",
  "data": {
    "invoiceId": "<fakturans id>",
    "invoiceNumber": "<fakturanummer>",
    "paymentId": "<betalningens id>",
    "amountOre": 39800,
    "paidAt": "2026-11-05",
    "method": "card",
    "status": "paid",
    "remainingOre": 0
  }
}

• Adressen måste börja med https:// och peka på en publik värd. Interna adresser nekas. Omdirigeringar följs inte, och svaret ska komma inom 10 sekunder.
• Svara med en 2xx-statuskod. Annars försöker Bookigo igen, högst sex försök med växande uppehåll, och leveransen markeras som misslyckad om den inte går igenom.
• Samma händelse kan komma mer än en gång (till exempel vid omförsök). Rubriken Bookigo-Delivery och fältet id i kroppen är samma vid varje försök, så spara id:t och hoppa över det ni redan har tagit emot.
• Kontrollera alltid signaturen och att tiden är färsk (till exempel inom fem minuter) innan ni litar på innehållet. Hemligheten (börjar med whsec_) visas bara när webhooken skapas.
• Använd den råa kroppen (texten som den kom) när ni räknar signaturen, inte en JSON-tolkning som ni skrivit ut igen.

Signaturen är t=<unixtid>,v1=<hex>, där hex är HMAC-SHA256 med webhookens hemlighet över <unixtid>.<råa kroppen>. Så kontrollerar ni den:

import { createHmac, timingSafeEqual } from "node:crypto";

// raw = kroppen som text, exakt som den kom. header = värdet i Bookigo-Signature.
export function checkBookigoSignature(raw, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300) return false; // äldre än fem minuter
  const expected = createHmac("sha256", secret).update(t + "." + raw).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(String(parts.v1 ?? ""));
  return a.length === b.length && timingSafeEqual(a, b);
}

Vanliga frågor