2.3 Utvecklarinfo - Underskriftstjänsten API
- Stefan Eriksson
Innehållsförteckning
Revisionshistorik
API
Översikt
Det här API:et stödjer elektroniska signeringar av dokument. Det har stöd för följande funktioner:
Skapa ett signeringsuppdrag
Optionellt specificera skaparen av signeringsuppdraget för att denna ska få åtkomst till signeringsuppdraget samt få händelseaviseringar om signeringsuppdraget.
Specificera en eller flera signatärer. Finns även stöd för att ange granskare, dvs personer som kan välja mellan att signera eller att godkänna utan att signera.
Sekventiellt eller parallellt signeringsflöde
Ange ett anpassat signeringsmeddelande som visas för signatärerna vid signeringstillfället
Specificera en eller flera användare (intressenter) som, förutom signatärerna/granskarna, ska kunna se underskriftsbegäran
Specificera en eller flera användare (intressenter) som, förutom signatärerna/granskarna, ska få aviseringar
Ladda upp dokument och bilagor, där skillnaden är att bilagor inte ska signeras
Optionellt specificera signatärer per uppladdat dokument
Aviseringar skickas till signatärerna, granskarna och intressenter
Återrapporering med händelser till externa applikationer
Hämta signerade dokument och bilagor
Hämta valideringsrapport för det signerade uppdraget
Hämta händelserapport över alla viktiga händelser som rör signeringsuppdraget
Ta bort ett signeringsuppdrag
Signeringsuppdrag
Första steget när man ska underteckna ett dokument är att skapa ett Signeringsuppdrag. Signeringsuppdraget innehåller information som titel, beskrivning, giltighetstid, en eller flera signatärer med föredraget aviseringssätt, typ av signeringsflöde och eventuell en extern referens från den anropande klientapplikationen . Den extern referensen används inte av Underskriftstjänsten - API men kan användas av klientapplikationen för att hålla klient-specifik information för per signeringsuppdrag.
Svaret innehåller ett Location-headerfält som pekar direkt på det skapade signeringsuppdraget. Detta fält kan användas som en bas-URI för alla följande förfrågningar mot detta signeringsuppdrag.
Signeringsflöde
Följande signeringsflöden finns:
Sekventiellt (“
sequence”)Signeringen sker i sekvens en person åt gången. Nästa person blir inte aviserad om ett pågående signeringsuppdrag förrän den tidigare personen har granskat eller signerat signeringsuppdraget.
Parallellt (“
parallel“)Alla personer som ska signera alternativt granska får avisering om ett pågående signeringsuppdrag samtidigt.
Se vidare kapitel Extra parametrar.
Signatärer
Underskriftsprofil
Underskriftsprofil anger vilken E-legitimation som ska användas och vilken attributprofil som ska användas vid underskrift av ett signeringsuppdrag. Attributprofilerna är desamma som definierats av den svenska myndigheten för digital förvaltning (DIGG). Varje attributprofil har ett namn som också används som namnet på Underskriftsprofilen.
En underskriftsprofil måste alltid anges per signatär när ett signeringsuppdrag skapas genom API.
Namn på Underskriftsprofil och attributprofiler, se Profilhantering.
Tillgängliga profiler
Profil | Beskrivning | Exempel på parametrar |
|---|---|---|
eln_ap_pnr_01 | Underteckning med svenskt personnummer, t.ex. personnummer. För användning med E-legitimationer som stöder denna profil, t.ex. BankID, Freja och SITHS. | Pnr Signatär"signers": [
{
"userId": "191212121212",
"name": "Test Testsson Pnr",
"signingProfile":
"eln_ap_pnr_01",
"notificationTypes": [
{
"method": "email",
"address": "signer1@company.com"
}
]
}]
|
eln_ap_pnr_01_orgid | Underteckning med svenskt personnummer, t.ex. personnummer, och svenskt organisationsnummer. För användning med E-legitimationer som stöder denna profil, t.ex. SITHS. | Pnr+OrgNo Signatär"signers": [
{
"userId": "191212121212@5563372191",
"name": "Test Testsson Pnr+Orgno",
"signingProfile": "eln_ap_pnr_01_orgid",
"notificationTypes": [
{
"method": "email",
"address": "signer2@company.com"
}
]
}]
|
digg_ap_hsaid_01 | Underteckning med HSA-id. För användning med E-legitimationer som stöder denna profil, t.ex. SITHS. | HSA-id Signatär"signers": [
{
"userId": "TST5565594230-135H",
"name": "Test Testsson HSAid",
"signingProfile": "digg_ap_hsaid_01",
"notificationTypes": [
{
"method": "email",
"address": "signer3@company.com"
}
]
}]
|
eln_ap_orgperson_01 | Underteckning med HSA-id och svenskt organisationsnummer. | HSA-id+OrgNo Signatär |
eln_ap_eidas_natper_01 | Underteckning med Foreign eID. För användning med E-legitimation som är godkänt utifrån eIDAS. | HSA-id+OrgNo Signatär |
Standardattributmappning
För mer information angående mappning av standard attribut se Profilhantering .
Anpassade meddelanden vid signering
Det är möjligt att visa ett specifikt meddelande för signatärer vid signering av ett underskriftsuppdrag, istället för det förinställda standardmeddelandet. Detta anpassade meddelande visas för alla som ska signera det specifika uppdraget, vilket ger möjlighet att specificera meddelandet för varje enskilt uppdrag.
För att genomföra detta, ska parametern 'visibleSignMessage' inkluderas i anropet under det första steget av skapandet av underskriftsuppdraget.
Extra parametrar
När ett signeringsuppdrag skapas kan man ange extra inställningar under parametern "extraParameters".
De vanligaste och viktigaste parametrarna är beskrivna här nedan, för fullständig information se avsnittet Open API specifikationer under kapitel 3.1.
Parameter | Värden | Standard | Beskrivning |
|---|---|---|---|
signing-flow | sequence parallel | parallel | Vilket signeringsflöde ska gälla |
status-callback-url | <callback url> | URL för mottagande av callbacks på statusuppdateringar. | |
redirect-url | <redirect-url> | URL för omdirigering efter slutförd signeringsprocess. | |
delete-after-days | <Number> | 30 | Antal dagar som signeringsuppdraget är kvar innan det gallras efter slutfört uppdrag ellet giltighetstiden har gått ut. |
Extra signatärsattribut
Fältet för användarattribut (UserAttributes) används för att skicka fler attribut till Underskriftstjänsten vid en underskrift. Fältet finns med för att stödja framtida förändringar.
Avisering
Signatär och avisering
Signatärsobjektet innehåller information om en person som ska underteckna dokumentet, såsom personens namn och minst en aviseringmetod.
Aviseringsmetoden beror på vilken metod Underskriftstjänsten - Webb har konfigurerats med vilket i dagsläget är e-post.
Avisering till intressenter
Andra intressenter som behöver underrättas när en underskriftsbegäran har slutförts kan läggas till i underskriftsbegäran. Varje intressent läggs till i listan över ytterligare mottagare med parametern "notify".
Dessa mottagare kommer att få en avisering när signeringsuppdraget har avslutats, antingen när signeringsuppdraget har signerats eller om signeringsuppdraget har löpt ut eller på annat sätt avbrutits.
Det bör noteras att samtliga intressenter (mottagare av aviseringar) måste specificeras med tillhörande HSA-id i parametern "stakeholders" för att kunna granska de signeringsuppdrag som är associerade med aviseringarna. Se mer under Åtkomst för användare som inte är signatärer
Aviseringsmall
Varje händelsestatus är kopplad till en aviseringmall. Mallen är en text/html-fil som kommer att användas för att generera texten för e-post aviseringen.
Följande händelser kan generera aviseringar beroende på konfigurationen:
Händelse | Avser | Beskrivning |
|---|---|---|
SignFlowStartedEvent | Signeringsuppdrag | Signeringsflödet är startat |
SignFlowStartedReminderEvent | Signeringsuppdrag | Påminnelsemejl |
SignFlowCancelledEvent | Signeringsuppdrag | Signeringsflödet är avbrutet |
DocumentSignedEvent | Signeringsuppdrag | Signeringsuppdraget är fullständigt signerat |
UserSignedEvent | Signatär/Granskare | Signatär/Granskare har signerat signeringsuppdraget |
UserApprovedEvent | Granskare | Granskare har godkänt signeringsuppdraget |
UserCancelledEvent | Signatär/Granskare | Signatär/Granskare har nekat/avbrutet signeringsuppdraget |
Följande händelser kan generera aviseringar till intressenter:
Händelse | Avser | Beskrivning |
|---|---|---|
NotifyDocumentSignedEvent | Signeringsuppdrag | Signeringsuppdraget är fullständigt signerat |
NotifySignFlowCancelledEvent | Signeringsuppdrag | Signeringsflödet är avbrutet |
NotifyUserCancelledEvent | Signatär/Granskare | Signatär/Granskare har nekat/avbrutet signeringsuppdraget |
Beroende på det valda underskriftsflödet kanske inte varje händelse är tillgänglig.
Uppdragsskapare
När ett signeringsuppdraget skapas via Underskriftstjänsten API finns det ingen given uppdragsskapare. Om ett signeringsuppdrag skall kopplas till en uppdragsskapare måste denna person anges via CreatedBy elementet. Personen som ange med CreatedBy kommer då att anges som skaparen av uppdraget och få då både åtkomst till uppdraget samt händelseaviseringar för signeringsuppdraget.
Exempel med CreatedBy
Åtkomst för användare som inte är signatärer (Intressenter)
Signatärerna kommer alltid ha åtkomst till signeringsuppdraget. Om andra parter ska få åtkomst till signeringsuppdraget måste de anges som intressenter vid skapandet av signeringsuppdraget. Detta är särskilt viktigt vid användning av API:et eftersom skaparen av signeringsuppdraget (personen) inte kan fastställas.
För mer information om hur man lägger till intressenter vid skapande av uppdrag se "AF API-1.1 Alternativflöde: Skapa signeringsuppdrag med intressenter" i SAD - Underskriftstjänsten Webb och API.
Exempel med Client Subject
Personen Stina med HSA-id TST5565594230-135M behöver ha access till signeringsförfrågan men är inte inkluderad som signatär.
Exempel med clientSubject
Ladda upp dokument
Dokument som ska undertecknas laddas upp till Underskriftstjänsten i två steg:
Skapa ett dokument objekt
Ladda upp dokumentet med hjälp av "
octet-stream"
Första steget är att skapa ett dokumentobjekt genom att anropa tjänsten med ett CreateDocumentRequest objekt. Svaret från tjänsten returnerar ett dokumentobjekt med ett nytt dokument-ID samt den fullständiga URL’en till dokumentet i “Location” HTTP headern. Viktigt att ange dokumenttypen med CreateDocumentRequest.documentMimeType.
Nästa steg är att ladda upp dokumentinnehållet som en octet stream, dvs som en binärström. Platsen till var dokumentinnehållet ska laddas upp till fås genom att lägga till “/content” till värdet på “Location” fältet.
Bilagor till en underskriftsbegäran kan också laddas upp. Dessa är dokument som inte ska undertecknas men innehåller information som signatären behöver för att kunna underteckna dokumentet. Om dokumentet är ett dokument som ska skrivas under eller en bilaga anges med CreateDocumentRequest.signDocument flaggan.
Korrelation mellan dokumentversioner
Varje gång ett dokument signeras skapas en ny version av det dokumentet. Det innebär också att dokumentets identitet (documentId) kommer att ändras.
En applikation kan hålla reda på det ursprungliga dokumentet och det korresponderande signerade dokumentet genom att använda korrelationsidentiteten som sätts vid skapandet av dokumentobjektet.
Korrelationsidentiteten för det ursprungliga dokumentet kommer att förbli oförändrad tills dokumentet har signerats fullständigt, vilket gör det möjligt att matcha det ursprungliga dokumentet med den signerade versionen av det dokumentet.
Om ingen korrelations-ID ges kommer det att sättas till dokumentets ID för det ursprungliga dokumentet. Se vidare CreateDocumentRequest.correlationId.
Initiera underskriftsflöde
När ett signeringsuppdrag har skapats och det nödvändiga dokumentet har laddats upp startas underskriftsflödet med "/sign"-endpointen. Detta kommer att utlösa utskick av aviseringar till de relevanta signatärerna och be dem logga in på Underskriftstjänsten och underteckna dokumentet. En direkt länk (URL) till dokumentet returneras med svaret från tjänsten i “Location”-fältet.
Hämta status
Begär status för signeringsuppdrag genom endpointen "/status". Fullständigt signerade uppdrag kommer att ha statusen StatusEnum.SIGNED.
De signerade dokumenten kan sedan hämtas.
Hämta signatärsstatus
Status per signatär kan också hämtas. Denna information kan vara användbar för att avgöra vem som har signerat eller inte. Se typen SignerStatusEnum.
Hämta status via callback
En callback-URL kan registreras när signeringsuppdraget skapas. Underskriftstjänsten kommer att försöka anropa den angivna URL:en när uppdraget har ändrat status. Se typen API CallbackStatusType.
Dokument och signerade dokument
Både signerade och osignerade dokument listas genom endpointen"/documents". Endast signerade dokument listas genom endpointen "/signedDocuments".
Dokument som är signerade flyttas från fältet documents till fältet signedDocuments i svaret.
Om en valideringsrapport genereras kommer den också att inkluderas i fältet signedDocuments efter ett fullständigt slutfört signeringsuppdrag.
Valideringsrapporten innehåller resultatet från en utförd signaturvalidering. Valideringsrapporten innehåller också det signerade dokumentet samt händelseloggen som en bifogad fil.
Dokumentinnehållet kan hämtas med hjälp av "/signRequests/<signaturförfrågan-id>/documents/<dokument-id>/content" eller "/signRequests/<signaturförfrågan-id>/signDocuments/<dokument-id>/content" beroende på om dokumentet är signerat eller inte.
Ta bort ett signeringsuppdrag
Att ta bort ett pågående signeringsuppdrag kan vara nödvändigt vid felaktiga eller oönskade signeringsuppdrag. Processen för att ta bort ett signeringsuppdrag involverar först att avbryta det pågående signeringsuppdraget och därefter genomföra själva borttagningen av signeringsuppdraget.
Händelselog
Alla åtgärder och händelser som är relevanta för ett specifikt signeringsuppdrag kan hämtas med hjälp av endpointen "/history".
Grundläggande flöde
Skapa ett signeringsuppdrag
Skapa ett dokument objekt
Ladda upp dokumentinnehållet
Upprepa steg 2 och 3 för alla aktuella dokument
Starta underskriftsflödet
Hämta status tills signeringsuppdraget har signerats, avbrutits eller en timeout har inträffat, eller använd en status-callbacks.
Hämta de signerade dokumenten
Hämta valideringsrapporten
Möjligtvis hämta händelseloggen
Ta bort signeringsuppdraget, eller låt den tas bort automatiskt av Underskriftstjänsten efter en konfigurerbar tidsperiod
Åtkomstkontroll
En applikation som behöver åtkomst till Underskriftstjänsten - API behöver autentisera sig emot tjänsten via mTLS med ett klientcertifikat utgivet av SITHS.
För mer information angående anslutning mot Underskriftstjänstens API, se Anslutningsguide - Underskriftstjänsten Webb och API .
Referenser
Här nedan finns exempel på hur anrop ser ut samt de olika funktionerna kan användas.
Användningsfall
För en mer detaljerad Systemdokumentation tillsammans med användningsfall se SAD - Underskriftstjänsten Webb och API .
API Specifikationer
Den senaste versionen av API-specifikationen kan hittas här.
För att använda yaml filen kan man använda valfri Open API Editor, exempelvis Swagger Editor
Version | Specifikation | Senast reviderad |
|---|---|---|
2.3 | 2023-12-12 | |
2.4 | 
| 2024-11-21 |
Postman Collection
Det finns utökad dokumentation under kollektionen i Postman som man kan läsa igenom för att få djupare förståelse för varje enskilt anrop.
Underskriftstjansten-Inera-20231213.postman_collection.json
Publik Information