API

Ett anrop, ett brev.

REST över HTTPS, JSON in och ut, nyckel i Authorization. Det som tar tid är inte integrationen — det är att bestämma vad brevet ska säga.

API:et är i pilot. Vi tar in ett fåtal integrationer i taget och bygger fältmappningen tillsammans med er — det finns ingen självbetjäning att registrera sig i. Beställ ett provbrev, så hör vi av oss med en tid.

Det kortaste som fungerar

POST https://api.skrivio.se/v1/brev

{
  "mall": "tmpl_tack_efter_kop",
  "relation": "kund",
  "mottagare": {
    "namn":       "Petra Lindgren",
    "adress":     "Storgatan 14",
    "postnummer": "22350",
    "ort":        "Lund"
  },
  "falt": { "fornamn": "Petra", "produkt": "kockkniven 21 cm" },
  "referens": "order-88412"
}

Svar · 201

{
  "id": "brev_9f2c41",
  "status": "i_ko",
  "referens": "order-88412",
  "krediter_dragna": 1,
  "format": "a5_c6",
  "beraknad_postning": "2026-09-19",
  "uppgifter_raderas": "2026-09-26"
}

Raderingsdatumet står i svaret. Ni behöver inte fråga oss när mottagarens uppgifter försvinner — det står i kvittot från början.

Två lägen

Godkänner ni varje brev eller varje mall?

Ingen order går till pennan utan att en människa godkänt något. Frågan är bara vad — och svaret beror på om utskicket är en kampanj eller ett flöde.

Läge 1 · kampanj

Ni godkänner varje brev

För engångsutskick till en lista. Ni skapar ordern, hämtar förhandsgranskningarna och godkänner. Krediter dras först vid godkännandet.

POST /ordrar
→ GET /ordrar/{id}/forhandsgranskning
→ POST /ordrar/{id}/godkann
→ kön

Läge 2 · löpande

Ni godkänner mallen en gång

För brev som utlöses av något i ert system — en order, ett möte, ett medlemskap. Mallen granskas och godkänns en gång, sedan flödar breven.

(en gång) POST /mallar → granskning
→ POST /brev
→ kön
Varför det inte går att stänga av helt

Pennan skriver troget vad den matas med, i bläck, på papper ni redan frankerat. Ett fel i er databas blir femhundra felaktiga brev i riktiga brevlådor — det går inte att ångra. Därför finns det alltid ett godkännandesteg, och därför är det mall eller brev, aldrig ingetdera.

Fälten

Ett av dem är inte tekniskt.

FältVad det gör
mallkrävs Id på en godkänd mall.
relationkrävs Hur mottagaren känner er. Se nedan — det här är inte ett tekniskt fält.
mottagarekrävs Namn, adress, postnummer, ort. Valideras mot formatregler och spärregister. Postnumret tas emot i vilken form som helst — 21134, 211 34, 211-34, SE-211 34 — och normaliseras.
faltvalfritt Nyckel–värde för det som varierar i mallen.
referensvalfritt Er egen nyckel. Den är det enda vi behåller efter radering, så att ni kan matcha postningsdatum mot er egen data.
formatvalfritt a5_c6 (förvalt) eller a4_dl.
raderavalfritt vid_postning eller efter_7_dagar (förvalt).

relation

Vi skriver bara till mottagare ni redan har en relation med. Den regeln står i villkoren — och här är den ett obligatoriskt fält med fasta värden, så att den inte går att glömma bort i en integration.

// giltiga värden
"kund"          pågående kundförhållande
"tidigare_kund" avslutad affär
"offert"        har fått offert eller värdering
"mote"          har träffat er — visning, möte, event
"medlem"        medlem eller prenumerant
"givare"        har skänkt en gåva

Finns inget av dem, hör listan inte hemma hos oss. Vi kontrollerar att fältet är ifyllt — inte att det är sant. Ansvaret är ert.

Fel

Sex svar ni bör hantera.

// 422
{
  "fel": "relation_saknas",
  "meddelande": "Ange hur mottagaren
    känner er."
}
// 409
{
  "fel": "mottagare_sparrad",
  "meddelande": "Mottagaren finns i
    spärregister. Inget brev skickat."
}
KodFelVad ni gör
422relation_saknas Sätt fältet. Kan inte kringgås.
422adress_ogiltig Rätta adressen. Svaret pekar ut vilket fält som fallerade.
422text_for_lang Över formatets gräns: 300 tecken på a5_c6, 450 på a4_dl. Svaret anger vilken som gällde.
409mottagare_sparrad Inget att göra — och inget dras. Logga och gå vidare.
409mall_ej_godkand Mallen väntar på granskning eller har ändrats sedan den godkändes.
402krediter_slut Fyll på. Inget skrivs på kredit.

mottagare_sparrad är inget fel i er kod. Det är systemet som gör sitt jobb, och det enda rimliga är att logga och fortsätta med nästa mottagare.

Webhooks

Fyra händelser.

Posten meddelar ingenting, så vi meddelar det vi vet: när brevet lämnade oss, och när uppgifterna försvann.

{
  "handelse": "brev.postat",
  "brev_id": "brev_9f2c41",
  "referens": "order-88412",
  "postat": "2026-09-19T08:14:00+02:00"
}
brev.postatBrevet har lämnats till posten. Detta är det sista vi vet — vanliga brev spåras inte.
brev.returKom tillbaka som obeställbart.
order.godkandKrediter dragna, ordern i kö.
uppgifter.raderadeRaderingskvitto: ordernummer, datum, antal poster.

Varje anrop är signerat. Huvudet Skrivio-Signatur bär t=<tid>,v1=<signatur>, där signaturen är HMAC-SHA256 av tid.kropp med er hemlighet. Räkna om den och jämför, och avvisa anrop som är äldre än fem minuter. Svara med 2xx; annars försöker vi igen i två dygn.

Gränser

Det ni behöver veta innan ni bygger.

Brevtext300 tecken på a5_c6, 450 på a4_dl. Uppmätt på riktiga brev med tomrad mellan styckena: 178 tecken blir sju rader och fyller knappt halva A5-arket. Taken låter brevet bli fullt utan att bli trångt.
Formata5_c6 och a4_dl. Inga kort.
OrderMax 5 000 brev per order. Fler blir flera ordrar.
Anropstakt120 anrop per minut. Batcha hellre via /ordrar.
IdempotensIdempotency-Key stöds och krävs i praktiken — ett dubblerat anrop blir annars ett dubblerat brev.
TestlägeNycklar med test_ renderar förhandsgranskningar men skriver ingenting och drar inga krediter.
Idempotensnyckeln är inte valfri i praktiken

Ett dubblerat API-anrop mot de flesta tjänster ger en extra rad i en databas. Här ger det ett extra brev i någons brevlåda, med porto betalt och ingen ångerknapp. Sätt nyckeln.

Kom igång

Vad som faktiskt händer.

StegVem
01Genomgång med er utvecklare: fältmappning mot ert system, vilka händelser som ska utlösa brev.Tillsammans
02Testnycklar och testmiljö. Förhandsgranskningar renderas på riktigt, ingenting skrivs.Vi
03Mallarna skrivs och granskas.Ni skriver, vi granskar
04Ett provbrev till er själva ur er egen integration.Vi
05Skarpa nycklar.Vi

Uppstarten är en engångskostnad och månadsavgiften betalar drift och support — inte breven. Talen står under priser, tillsammans med var gränsen går mot att köpa på krediter.

Innan ni bygger

Beställ ett provbrev.

Det tar tre dagar att veta om produkten är värd en integration, och noll kronor att ta reda på det.

Beställ provbrev