Signering API

Digital signering med BankID. Låt användare signera dokument, avtal och villkor med juridiskt bindande e-signaturer.

Översikt

Digital signering fungerar som autentisering, men med ett viktigt tillägg: du skickar med en text (userVisibleData) som användaren ser och godkänner i BankID-appen. Signaturen knyts kryptografiskt till denna text.

Juridisk giltighet
BankID-signaturer uppfyller kraven för avancerad elektronisk underskrift enligt eIDAS-förordningen och är juridiskt bindande i Sverige.

Starta signering

Skapar en ny signeringssession där användaren signerar angiven text.

POST /api/v1/auth/{provider}/sign

Request Body

Parameter Typ Beskrivning
endUserIp Required string Slutanvändarens IP-adress
userVisibleData Required string Text som visas för användaren i BankID-appen. Max 40 000 tecken.
userVisibleDataFormat Optional string Format: simpleMarkdownV1 för formaterad text, eller utelämna för ren text
userNonVisibleData Optional string Dold data som inkluderas i signaturen men inte visas. Max 200 000 tecken.
personalNumber Optional string Personnummer (12 siffror) för att begränsa till specifik person
callbackUrl Optional string URL för redirect efter slutförd signering
webhookUrl Optional string URL för webhook-notifiering
state Optional string Eget värde som returneras i callback/webhook 
curl -X POST https://id.tic.io/api/v1/auth/bankid/sign \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endUserIp": "192.168.1.1",
    "userVisibleData": "Jag godkänner avtalsvillkoren för tjänsten.\n\nAvtal: 2024-001\nBelopp: 10 000 SEK",
    "userNonVisibleData": "{\"contractId\":\"2024-001\",\"hash\":\"abc123\"}",
    "callbackUrl": "https://example.com/signed",
    "state": "contract-2024-001"
  }'

Response

200 OK
{
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "provider": "bankid",
  "orderRef": "131daac9-16c6-4618-beb0-365768f37288",
  "autoStartToken": "7c40b5c9-fa74-49cf-b98c-bfe651f9a7c6",
  "qrStartToken": "67df3917-fa0d-44e5-b327-edcc928297f8",
  "qrStartSecret": "d28db9a7-4cde-429e-a983-359be676944c",
  "sessionExpiresAt": "2024-01-15T14:35:00Z"
}

simpleMarkdownV1 formatering

BankID stödjer enkel markdown-formatering för userVisibleData. Sätt userVisibleDataFormat: "simpleMarkdownV1" för att aktivera.

Syntax Beskrivning Exempel
# Rubrik Rubrik nivå 1-3 # Avtal, ## Villkor
*text* Fetstil *Viktigt*
+ item Punktlista + Första punkten
+1 item Numrerad lista +1 Steg ett
--- Horisontell linje ---
|A|B| Tabell (max 5 kolumner) |Produkt|Pris|

Exempel med formatering

# Avtalsbekräftelse

Jag godkänner följande:

+ Allmänna villkor version 2024.1
+ Personuppgiftsbehandling enligt GDPR
+ Betalningsvillkor 30 dagar netto

---

|Tjänst|Pris|
|:-|:-|
|Grundtjänst|500 kr/mån|
|Tillägg|100 kr/mån|

*Signerat den 2024-01-15*
Undvik avslutande mellanslag
I vissa versioner av BankID-appen kan ett mellanslag efter fetstil (*text* ) orsaka fel. Undvik avslutande mellanslag på rader.

Hämta signatur

När signeringen är klar innehåller svaret signaturdata.

GET /api/v1/auth/{sessionId}/collect

Response (status: complete)

200 OK
{
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "complete",
  "user": {
    "personalNumber": "199001011234",
    "givenName": "Anna",
    "surname": "Andersson",
    "name": "Anna Andersson"
  },
  "signature": {
    "value": "PD94bWwgdmVyc2lvbj0iMS4wIi...",
    "ocspResponse": "MIIHfgoBAKCCB3cwggdzBg..."
  },
  "completedAt": "2024-01-15T14:32:00Z"
}

Signaturdata

Fält Beskrivning
signature.value XML-DSig signatur (Base64-kodad). Innehåller signerad data, certifikat och kryptografisk signatur.
signature.ocspResponse OCSP-svar (Base64-kodat). Bevisar att certifikatet var giltigt vid signeringstillfället.

Verifiera signatur

Signaturen är en XML-DSig som kan verifieras kryptografiskt. Den innehåller:

  • Den signerade texten (userVisibleData)
  • Eventuell dold data (userNonVisibleData)
  • Användarens certifikat med personnummer och namn
  • Tidsstämpel för signeringen
  • Kryptografisk signatur
Spara signaturen
Spara både signature.value och signature.ocspResponse tillsammans med det signerade dokumentet. OCSP-svaret behövs för att bevisa att certifikatet var giltigt vid signeringstillfället.

Användningsområden

Scenario Rekommendation
Avtalsvillkor Visa sammanfattning i userVisibleData, spara dokumenthash i userNonVisibleData
Betalningar Visa belopp och mottagare tydligt. Använd markdown för struktur.
Fullmakter Specificera vad fullmakten gäller och giltighetstid.
GDPR-samtycke Lista specifikt vilka uppgifter som behandlas och i vilket syfte.