API-specifikation för digital post – integration mellan verksamhetssystem och Ekopost

Översikt

API:et låter kommuner, regioner och andra organisationer skicka digital post direkt från sina verksamhetssystem, med Ekopost som utskickstjänst. Det följer SKR:s gemensamma API-specifikation för digital post från verksamhetssystem (Digital post REST-API, version v1).

Operationer

Bas-URL: https://api.ekopost.se/gn

Format

• Anrop och svar är JSON i UTF-8. Ange Content-Type: application/json.
• Fältnamnen skrivs i camelCase enligt specifikationen. Ekoposts övriga API använder snake_case, så modellerna kan inte delas mellan API:erna.
• Datum anges som ÅÅÅÅ-MM-DD och tidpunkter enligt ISO 8601 i UTC.
• Fält utan värde utelämnas i svaren.
• Fel returneras som application/problem+json, se Felhantering.

Exempel på headers

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json; charset=UTF-8

Flöde

1. Kontrollera mottagaren (valfritt)
   hasAvailableMailbox visar om mottagaren kan nås digitalt.
2. Skicka meddelandet
   sendDigitalMail för brev och sendDigitalInvoice för fakturor, med ett unikt messageId.
3. Ekopost tar emot försändelsen
   Ekopost validerar anropet, väljer kanal och registrerar försändelsen. Svaret innehåller distributionId och timeStamp.
4. Leverans
   Leveransen till brevlåda, bank eller tryck sker efter svaret. Spara id:na i svaret för uppföljning, se Ekopost-tillägg i svaret.

Kom igång

För att ansluta behöver organisationen:

• ett Ekopost-konto,
• ett klientcertifikat (X.509) med organisationsnumret, som Ekopost registrerar på kontot, se Klientcertifikat,
• för digital leverans: Mina meddelanden eller Kivra som kontots primära kanal, se Avsändare och kanal.

Kontakta hejsan@ekopost.se för att komma igång. Du kan börja testa i sandbox innan certifikatet är på plats, se Testa i sandbox.

Testa i sandbox

I Ekoposts sandbox kan du testa operationerna utan klientcertifikat och organisations-JWT. Sandbox nås via http://api.sandbox.ekopost.se/gn (utan https), och inget som skickas där levereras till mottagarna.

• Skapa ett sandbox-konto och en API-nyckel, se Sandbox i Ekoposts API-dokumentation.
• Autentisera med Authorization: api-key <nyckel> i stället för certifikat och JWT.
• I övrigt fungerar API:et som i produktion. Bland annat ska avsändar-id:t höra till en kanal som är uppsatt på sandbox-kontot, se Avsändare och kanal.
• API-nyckel godtas bara i sandbox. I produktion krävs alltid klientcertifikat och organisations-JWT, och de kan inte testas i sandbox.

Exempel på anrop i sandbox (RAW)

POST /gn/has-available-mailbox HTTP/1.1
Host: api.sandbox.ekopost.se
Authorization: api-key YiuyotGtRNDXik56lgq6
Content-Type: application/json; charset=UTF-8

{
  "organizationNumber": "5555555555",
  "recipientId": [
    "199912312387"
  ]
}

Avsändare och kanal

Avsändar-id:t i anropet avgör vilken digital kanal Ekopost använder och skickas vidare som avsändare i den kanalen. Det är messageHeader.sender.senderId i sendDigitalMail och sendDigitalInvoice, och organizationNumber i hasAvailableMailbox.

Per operation

• hasAvailableMailbox: uppslaget görs i kanalen för organizationNumber. Använd samma avsändar-id som i utskicket, så gäller svaret den kanal brevet eller fakturan skickas i.
• sendDigitalMail: ett organisationsnummer eller en tenant key. Kan avsändar-id:t inte användas digitalt, för att kanalen inte är kontots primära kanal eller för att värdet varken är ett organisationsnummer eller en tenant key, skickas brevet som fysisk post, precis som när mottagaren inte kan nås digitalt. Vid fysisk post spelar avsändar-id:t ingen roll.
• sendDigitalInvoice: samma som för sendDigitalMail. Kan avsändar-id:t inte användas digitalt skickas fakturan som fysisk post, se Kanalval för fakturor.

Bra att veta

• Avsändar-id:t jämförs inte med kontots organisationsnummer. Organisationen identifieras av klientcertifikatet och organisations-JWT:n.
• Ett organisationsnummer skickas vidare till Mina meddelanden med 12 siffror och 16 först, till exempel 165555555555, oavsett om det anges med 10 eller 12 siffror. En tenant key skickas som den är.
• Är kanalen inte uppsatt på kontot svarar hasAvailableMailbox 400 på fältet. Brev och fakturor skickas i stället som fysisk post.
• Ett felskrivet organisationsnummer, till exempel med fel kontrollsiffra, känns inte igen: hasAvailableMailbox svarar 400 på fältet, och brev och fakturor skickas som fysisk post. Kontrollera formatet om en försändelse oväntat skickas som fysisk post.

Säkerhet

Varje anrop autentiseras i två lager enligt specifikationen: ett klientcertifikat (mTLS) och en organisations-JWT som den avsändande organisationen signerar. apiInfo kräver bara klientcertifikat.

Klientcertifikat (mTLS)

Certifikatet presenteras i TLS-handskakningen (TLS 1.2 eller senare). Ekopost godkänner anslutningen när certifikatet:

• är registrerat hos Ekopost på organisationens konto och inte är spärrat,
• är inom sin giltighetstid,
• innehåller organisationsnumret i subject, i attributet organizationIdentifier (OID 2.5.4.97, till exempel NTRSE-5555555555) eller serialNumber (OID 2.5.4.5),
• har samma organisationsnummer som kontot det är registrerat på.

Varje anslutning loggas med certifikatets organisationsnummer, serienummer, tidpunkt och eventuell orsak till att den nekades. Vid nekad anslutning svarar API:et 401 utan att ange orsaken. Kontakta Ekopost om ett certifikat nekas.

Organisations-JWT

POST-operationerna kräver också en JWT i Authorization-headern. Organisationen skapar och signerar token själv med den privata nyckeln till samma klientcertifikat som används för mTLS. Ekopost verifierar signaturen mot certifikatets publika nyckel.

Authorization: Bearer <token>

Övriga claims, till exempel iat och jti, tas emot men kontrolleras inte. Ekopost tillåter en minuts tidsavvikelse. Ge token kort giltighetstid och skapa en ny när den har gått ut. Diggs REST API-profil rekommenderar högst 5 minuter.

Exempel på innehåll i token

// Header
{
  "alg": "RS256",
  "typ": "JWT"
}

// Payload
{
  "sub": "5555555555",
  "iat": 1791187200,
  "exp": 1791187500
}

Exempel: skapa token (C#)

Exemplen kräver .NET Framework 4.7.2 eller senare, eller .NET 6 eller senare.

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Security.Cryptography;
using System.Security.Cryptography.X509Certificates;
using System.Text;

public static class OrgJwt
{
    // Signerar en organisations-JWT (RS256) med den privata nyckeln till klientcertifikatet
    public static string Create(X509Certificate2 certificate, string organisationNumber)
    {
        var now = DateTimeOffset.UtcNow.ToUnixTimeSeconds();

        var header = Base64Url(Encoding.UTF8.GetBytes("{\"alg\":\"RS256\",\"typ\":\"JWT\"}"));
        var payload = Base64Url(Encoding.UTF8.GetBytes(
            "{\"sub\":\"" + organisationNumber + "\",\"iat\":" + now + ",\"exp\":" + (now + 300) + "}"));

        using (var rsa = certificate.GetRSAPrivateKey())
        {
            var signature = rsa.SignData(
                Encoding.ASCII.GetBytes(header + "." + payload),
                HashAlgorithmName.SHA256,
                RSASignaturePadding.Pkcs1);

            return header + "." + payload + "." + Base64Url(signature);
        }
    }

    private static string Base64Url(byte[] bytes)
    {
        return Convert.ToBase64String(bytes).TrimEnd('=').Replace('+', '-').Replace('/', '_');
    }
}

Exempel: anropa API:et (C#)

// Certifikatet med privat nyckel används både för mTLS och för att signera token
var certificate = new X509Certificate2("organisation.pfx", "lösenord");

var handler = new HttpClientHandler();
handler.ClientCertificates.Add(certificate);    // mTLS
var client = new HttpClient(handler);           // återanvänd samma klient för alla anrop

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.ekopost.se/gn/has-available-mailbox");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", OrgJwt.Create(certificate, "5555555555"));
request.Content = new StringContent(
    "{\"organizationNumber\":\"5555555555\",\"recipientId\":[\"199912312387\"]}",
    Encoding.UTF8,
    "application/json");

var response = await client.SendAsync(request);

hasAvailableMailbox

Kontrollerar om en eller flera mottagare kan ta emot digital post från avsändaren. Används innan ett meddelande skapas, för att veta om digital leverans är möjlig.

Anrop

Exempel på anrop (RAW)

POST /gn/has-available-mailbox HTTP/1.1
Host: api.ekopost.se
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json; charset=UTF-8

{
  "organizationNumber": "5555555555",
  "recipientId": [
    "199912312387",
    "191212121212"
  ]
}

Svar

Exempel på svar (RAW)

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "recipientId": "199912312387",
    "reachable": true
  },
  {
    "recipientId": "191212121212",
    "reachable": false
  }
]

Så avgörs reachable

• Uppslaget görs i den kanal som organizationNumber pekar ut: Mina meddelanden eller Kivra, se Avsändare och kanal. reachable är true om mottagaren kan ta emot post från avsändaren där.
• Använd samma avsändar-id som i utskicket, så gäller svaret den kanal brevet eller fakturan skickas i.
• Svaret har en rad per mottagare, i samma ordning som i anropet.
• Om uppslaget mot kanalerna inte kan genomföras svarar API:et 500. Ett tekniskt fel rapporteras aldrig som reachable: false.

sendDigitalMail

Skickar ett brev med PDF-dokument. Ekopost levererar till mottagarens digitala brevlåda när det går och annars som fysisk post.

Anrop

Exempel på anrop (RAW)

POST /gn/send-digital-mail HTTP/1.1
Host: api.ekopost.se
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json; charset=UTF-8

{
  "messageHeader": {
    "messageId": "6d4d5bba-9468-4e3e-bb34-0a14c586285a",
    "recipientId": "199912312387",
    "importantMessage": true,
    "sender": {
      "senderId": "5555555555",
      "name": "A kommun"
    },
    "headerSubject": "Beslut om bygglov",
    "postAddress": {
      "name": "Bosse Bula",
      "addressLineOne": "Storgatan 1",
      "addressLineTwo": "Lgh 1101",
      "zipCode": "12345",
      "city": "Borgholm",
      "country": "Sverige"
    },
    "supportInfo": {
      "supportText": "Kontakta oss via e-post eller telefon.",
      "contactInformationUrl": "https://www.example.se/kontakt",
      "contactInformationPhoneNumber": "+46701234567",
      "contactInformationEmail": "info@example.se"
    },
    "metaData": {
      "senderAttention": "Bygg- och miljökontoret",
      "sendingSystem": "System A",
      "costCenter": "BYGG-123"
    }
  },
  "attachments": [
    {
      "contentType": "application/pdf",
      "body": "JVBERi0xLjQKJ...",
      "filename": "beslut.pdf"
    }
  ],
  "bodyInformation": {
    "contentType": "text/plain",
    "body": "Hej! Här kommer beslutet om ditt bygglov."
  }
}

Svar

DistributionIdentity med Ekoposts id för försändelsen, tidpunkten då den registrerades och Ekoposts id:n i metaData.other, se Ekopost-tillägg i svaret.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "distributionId": "3f2c8e9a-1b4d-4c7e-9a2f-6d5e8b1c0a47",
  "timeStamp": "2026-10-05T08:15:42.123Z",
  "metaData": {
    "other": [
      { "tag": "ekopost.campaignId", "value": "9b1e4c2a-0f3d-4e8b-a6c1-2d7f5e9b8a10" },
      { "tag": "ekopost.envelopeId", "value": "3f2c8e9a-1b4d-4c7e-9a2f-6d5e8b1c0a47" }
    ]
  }
}

Kanalval

Den digitala kanalen avgörs av messageHeader.sender.senderId, se Avsändare och kanal. Taggarna ekopost.* beskrivs under Ekopost-specifika val. E-post används inte som kanal: emailAddress valideras men används inte för leverans.

Fysisk post

• Fysisk post kräver postAddress med name, addressLineOne, zipCode och city. Adressen kontrolleras när Ekopost har valt fysisk post. Saknas den svarar API:et 400 med de fält som saknas.
• Adressen kan i stället hämtas från folkbokföringen med ekopost.addressLookup: navet, se Adress från Navet.
• Adressen skrivs på ett adressblad som läggs först i brevet, eller på första sidan om kontot är inställt för det.
• Meddelandetexten i bodyInformation skrivs inte ut. Bara PDF-filerna skickas.

PDF-filer

Gäller både attachments för brev och files för fakturor.

• contentType ska vara application/pdf och body filen BASE64-kodad.
• Den första filen är huvuddokumentet. Alla dess sidor ska ha samma format: A4 eller Letter.
• Övriga filer är bilagor. Sidorna får vara A4 eller A3 (stående eller liggande) eller Letter.
• Filerna får inte vara skadade eller lösenordsskyddade.

Följ Ekoposts dokumentspecifikation och mall för marginaler för bästa resultat vid fysisk post.

Upprepade anrop (messageId)

messageId (UUID) identifierar meddelandet. Skickar samma organisation samma messageId igen skapas ingen ny försändelse. Svaret innehåller i stället samma distributionId, timeStamp och metaData som första gången. Det gör det säkert att göra om ett anrop efter till exempel en timeout. Innehållet i det upprepade anropet jämförs inte. Kommer två anrop med samma messageId samtidigt väntar det andra tills det första är klart och får sedan samma svar. Är det första anropet inte klart inom en minut svarar det andra 503 Service Unavailable med headern Retry-After. Gör om anropet efter angiven tid.

Använd ett nytt messageId för varje nytt meddelande. Det gäller både brev och fakturor.

sendDigitalInvoice

Skickar en betalningsbar faktura eller påminnelse till Kivra, eller som brev med PDF:en till Mina meddelanden. Kan fakturan inte levereras digitalt skickas den som fysisk post.

Anrop

Exempel på anrop (RAW)

POST /gn/send-digital-invoice HTTP/1.1
Host: api.ekopost.se
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json; charset=UTF-8

{
  "messageHeader": {
    "messageId": "0b1c6f2e-5a77-4e0f-9d3b-2f8a4c6e1d90",
    "recipientId": "199912312387",
    "sender": {
      "senderId": "5555555555",
      "name": "A kommun"
    },
    "headerSubject": "Faktura från A kommun",
    "postAddress": {
      "name": "Bosse Bula"
    },
    "supportInfo": {
      "supportText": "Frågor om fakturan? Kontakta oss via e-post.",
      "contactInformationEmail": "faktura@example.se"
    }
  },
  "invoiceBody": {
    "amount": 1234.50,
    "currencyCode": "SEK",
    "dueDate": "2026-11-30",
    "paymentReferenceType": "SE_OCR",
    "paymentReference": "426523791",
    "accountType": "BANKGIRO",
    "accountNumber": "12345",
    "type": "INVOICE",
    "reference": "Faktura 12345",
    "payable": true
  },
  "files": [
    {
      "contentType": "application/pdf",
      "body": "JVBERi0xLjQKJ...",
      "filename": "faktura-12345.pdf"
    }
  ]
}

Svar

DistributionIdentity, på samma sätt som för sendDigitalMail.

Kanalval för fakturor

Fakturor följer samma regler som brev, se Kanalval: digitalt när importantMessage är true och mottagaren kan nås i den kanal som messageHeader.sender.senderId pekar ut, annars fysisk post. Kanalen avgörs av avsändar-id:t, se Avsändare och kanal.

Fakturauppgifter

• paymentReferenceType: SE_OCR för OCR-nummer och TENANT_REF för annan betalningsreferens.
• reference är fakturanummer eller rubrik.
• type: REMINDER skickas som påminnelse i Kivra.
• payable: false visar fakturan i Kivra utan möjlighet att betala. En betalningsbar faktura måste ha ett belopp större än 0, och i Kivra en förfallodag som inte har passerat.

apiInfo

Returnerar information om API:et. Kräver bara klientcertifikat, ingen JWT.

Svar

Exempel på svar (RAW)

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "apiName": "Digital post REST-API",
  "apiVersion": "v1",
  "apiStatus": "active"
}

Ekopost-specifika val

Specifikationen tillåter fria nyckel/värde-par i messageHeader.metaData.other. Ekopost använder två taggar för val som specifikationen saknar. I sendDigitalMail gäller alla värden. I sendDigitalInvoice gäller bara ekopost.addressLookup: navet; rek, protected och guardian ger 400 för fakturor.

Taggar och värden är skiftlägesokänsliga och varje tagg får förekomma en gång. Okända taggar ignoreras, så other kan även innehålla annan metadata. Ett ogiltigt värde ger 400.

Exempel

"metaData": {
  "costCenter": "BYGG-123",
  "other": [
    { "tag": "ekopost.postalType", "value": "rek" },
    { "tag": "ekopost.addressLookup", "value": "navet" }
  ]
}

REK

• ekopost.postalType: rek skickar brevet som rekommenderat brev (REK), alltid som fysisk post, även om mottagaren kan nås digitalt.
• Adressen anges i postAddress eller hämtas med ekopost.addressLookup: navet. Uppfyller den inte kraven för REK svarar API:et 400.
• supportInfo.contactInformationEmail används som avsändarens kontaktadress för försändelsen. Saknas den används kontots kontaktuppgifter.
• REK är inte tillgängligt för konton med produktion i Norge.

Skyddad post

• Med ekopost.postalType: protected levereras brevet digitalt som vanligt om mottagaren kan nås digitalt.
• Annars skickas det som skyddad post: ingen postadress används, och mottagarens personnummer skrivs i adressfältet.
• Kontot måste vara aktiverat för skyddad post, annars svarar API:et 400.

Adress från Navet

• Med ekopost.addressLookup: navet hämtas mottagarens folkbokföringsadress när brevet eller fakturan ska skickas som fysisk post. Den används i stället för postAddress.
• Uppslaget görs bara när fysisk post används.
• Hittas ingen fullständig adress svarar API:et 404 och inget skickas.

Vårdnadshavare

• Med ekopost.addressLookup: guardian hämtas mottagarens vårdnadshavare från Navet, och varje vårdnadshavare får en egen försändelse.
• Varje vårdnadshavare får brevet digitalt om det går, annars som fysisk post till sin folkbokföringsadress.
• Vårdnadshavarens namn och adress skrivs på dokumentet, även när brevet levereras digitalt. Adressen hamnar på ett adressblad som läggs först, eller på första sidan om kontot är inställt för det.
• Hittas inga vårdnadshavare, eller saknar någon av dem adress, svarar API:et 404 och inget skickas.
• distributionId är den första försändelsen. Svaret innehåller en ekopost.envelopeId per vårdnadshavare, se Ekopost-tillägg i svaret.

Kombinationer

En kombination som inte är tillåten ger 400.

Ekopost-tillägg i svaret

Svaret från sendDigitalMail och sendDigitalInvoice innehåller, utöver specifikationens distributionId och timeStamp, id:na för det som skapades i Ekopost. De anges som taggar i metaData.other, på samma sätt som valen i anropet. Fältet finns inte i specifikationens svar, och klienter som inte känner till det kan ignorera det.

Med id:na kan du följa varje försändelse i Ekoposts ordinarie API, till exempel med Get envelope (GET /campaigns/{campaign_id}/envelopes/{envelope_id}). Det ordinarie API:et autentiseras med api-key, Basic eller OAuth2.

Objekt

Objekten följer specifikationen. Kolumnen Krav anger vad Ekopost kräver.

MessageHeader

Sender

PostAddress

Fält som skickas får inte vara tomma.

EmailAddress

SupportInfo

MetaData

MetaDataOther

Attachment

BodyInformation

BodyInvoice

Se Fakturauppgifter för hur fälten används.

DistributionIdentity

Problem

Felhantering

Fel returneras med Content-Type: application/problem+json och objektet Problem. Texterna i detail och violations är på engelska.

Exempel: 400 Bad Request

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json; charset=utf-8

{
  "instance": "/gn/send-digital-mail",
  "type": "about:blank",
  "status": {
    "reasonPhrase": "Bad Request",
    "statusCode": 400
  },
  "title": "Bad Request",
  "detail": "The request is invalid. See violations for details.",
  "violations": [
    {
      "field": "attachments[0].contentType",
      "message": "Only application/pdf is allowed."
    }
  ]
}

Exempel: 401 Unauthorized (JWT)

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Content-Type: application/problem+json; charset=utf-8

{
  "instance": "/gn/send-digital-invoice",
  "type": "about:blank",
  "status": {
    "reasonPhrase": "Unauthorized",
    "statusCode": 401
  },
  "title": "Unauthorized",
  "detail": "The organisation JWT has expired."
}