POST/api/v1/verifikat

Bokför en affärshändelse från ditt eget system

Skriver ett verifikat genom motorns egen bokföringsfunktion — samma väg som bokföringsformuläret i programmet, samma spärrar, samma nummerserier. Det här är den generella skrivvägen in i huvudboken: kundfakturarutten tar en faktura, orderintaget tar en butiksorder, och den här tar en affärshändelse av vilket slag som helst.

**Varför den finns.** Vi bygger med flit inga färdiga kopplingar mot enskilda butiks- eller betalplattformar — en adapter mot någon annans API är löpande drift, inte en funktion. Du får i stället ett generiskt format och ett öppet API, och kopplingen byggs en gång och ägs av dig. Den här rutten är det som gör det möjligt.

**Spärrarna gäller lika.** Balanskravet (debet = kredit), kravet på ett belopp skilt från noll, minst två rader, att kontot finns och är aktivt, periodlåset, momslåset och avslutade räkenskapsår — allt ligger inuti motorns funktion och gäller för API:et precis som för dig själv i gränssnittet. Ett anrop som stoppas av ett lås får 422 med skälet utskrivet.

**Rutten skapar aldrig konton.** Ett konto som saknas i kontoplanen eller är avaktiverat ger 422 med kontonumret utskrivet. Lägg upp kontot under Kontoplan först.

**Nyckeln behöver båda behörigheterna: Bokföra och Läsa.** Radernas konton slås upp i kontoplanen för att momsen ska kunna kontrolleras innan verifikatet skrivs, och den uppslagningen är en läsning. En nyckel med enbart Bokföra får 403 med det beskedet i klartext.

**Idempotensen är inte valfri, och skälet är att ett verifikat inte går att ta bort.** Skicka din egen externa referens — ordernumret, körningens id — som Idempotency-Key. Samma referens igen ger samma verifikat tillbaka i stället för ett andra.

Din installations adress

Debet & Kredit kör på din egen server, så bas-URL:en är din — inte vår. Skriv in den här, så byts den ut i varje kodexempel i dokumentationen.

POST https://din-installation.se/api/v1/verifikat

Behörighet

Bokföra ledger:write

Skapar och bokför fakturor genom samma spärrar som programmet självt: momslås, låsta perioder och avslutade räkenskapsår gäller lika.

Takt

600 anrop per timme och nyckel (ställbart per nyckel).

Parametrar

Huvuden

Namn	Typ	Krävs	Beskrivning
`Idempotency-Key`	string	ja	8–255 tecken du väljer själv, unikt per affärshändelse. Använd din egen externa referens: samma referens igen ger samma verifikat i stället för ett andra. `kassa-2026-03-12`

Kropp (JSON)

Namn	Typ	Krävs	Beskrivning
`seriesCode`	string	ja	Verifikationsseriens kod, högst två tecken. Serien måste finnas för räkenskapsåret datumet ligger i. `A`
`date`	date	ja	Verifikationsdatum (ÅÅÅÅ-MM-DD). Avgör räkenskapsår, period och vilka lås som prövas. `2026-03-12`
`description`	string	ja	Vad affärshändelsen avser. Står i huvudboken och kan inte ändras i efterhand. `Dagskassa 12 mars`
`counterparty`	string	nej	Motparten, om det finns en. `Kortinlösen AB`
`rows`	array	ja	Minst två rader med account, debit och credit. Frivilligt per rad: note, cost_center och project (dimensionernas uuid, inte deras koder).

Svar

Exempel på anrop:

{
  "seriesCode": "A",
  "date": "2026-03-12",
  "description": "Dagskassa 12 mars",
  "counterparty": "Kortinlösen AB",
  "rows": [
    {
      "account": 1930,
      "debit": 12500,
      "credit": 0,
      "note": "Insättning"
    },
    {
      "account": 3001,
      "debit": 0,
      "credit": 10000
    },
    {
      "account": 2611,
      "debit": 0,
      "credit": 2500
    }
  ]
}

Exempel på svar:

{
  "id": "8f14e45f-ceea-467a-9a3a-1f2b3c4d5e6f",
  "series": "A",
  "number": 12,
  "label": "A12",
  "verification_date": "2026-03-12",
  "url": "https://din-installation.se/verifikat/8f14e45f-ceea-467a-9a3a-1f2b3c4d5e6f"
}

Statuskoder

Kod	error	Betydelse
200	—	Verifikatet bokfördes — eller är sedan tidigare bokfört med samma Idempotency-Key. Svaret bär numret och en länk till posten.
400	`idempotency_required`	Huvudet Idempotency-Key saknas.
400	`invalid_request`	Kroppen går inte att läsa, balanserar inte, saknar belopp, har färre än två rader, eller ber om en källa som bara programmet självt får sätta. Svaret säger vilket.
409	`idempotency_conflict`	Samma Idempotency-Key har redan använts med en annan kropp.
409	`idempotency_in_progress`	Ett anrop med samma Idempotency-Key behandlas just nu. Skicka om exakt samma anrop om en stund — du får då det första svaret. Byt INTE nyckel: det första anropet kan mycket väl ha bokfört.
413	`payload_too_large`	Kroppen är större än 512 kB. Ett verifikat är några kilobyte; taket stoppar en kropp som inte är ett.
422	`period_locked`	Perioden är låst, momslåst eller räkenskapsåret avslutat. Verifikatet är läst men kan inte bokföras — svaret säger vilken spärr som gäller.
422	`unprocessable`	Motorn tog emot verifikatet men kunde inte bokföra det: ett konto som saknas eller är avaktiverat, en verifikationsserie som inte finns för året, ett datum utan räkenskapsår, eller en dimension som inte är aktiv.
403	`insufficient_scope`	Nyckeln är giltig men saknar behörigheten rutten kräver.
401	`unauthorized`	Saknad, felformad eller okänd nyckel.
401	`key_revoked`	Nyckeln är återkallad av installationens ägare.
429	`rate_limited`	Nyckelns kvot för timmen är förbrukad. Retry-After säger när den återställs.
503	`server_misconfigured`	Installationen saknar konfiguration för API:et.

Felkroppens fält och råd om omförsök står på Fel och statuskoder.

Kodexempel

curl -X POST "https://din-installation.se/api/v1/verifikat" \
  -H "Authorization: Bearer dk_live_DIN_NYCKEL" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2026-0042" \
  -d '{
  "seriesCode": "A",
  "date": "2026-03-12",
  "description": "Dagskassa 12 mars",
  "counterparty": "Kortinlösen AB",
  "rows": [
    {
      "account": 1930,
      "debit": 12500,
      "credit": 0,
      "note": "Insättning"
    },
    {
      "account": 3001,
      "debit": 0,
      "credit": 10000
    },
    {
      "account": 2611,
      "debit": 0,
      "credit": 2500
    }
  ]
}'