Innehållsförteckning

Revisionshistorik

1. API

1.1. Översikt

Det här API:et stödjer elektroniska signeringar av dokument. Det har stöd för följande funktioner:

• Skapa ett signeringsuppdrag
• Specificera en eller flera signatärer
• Sekventiellt eller parallellt signeringsflöde.
• Ange ett anpassat signeringsmeddelande som visas för signatärerna vid signering
• Specificera en eller flera användare, förutom signatärerna, som ska kunna se underskriftsbegäran
• Specificera en eller flera användare, förutom signatärerna, som ska få aviseringar
• Ladda upp dokument och bilagor, där skillnaden är att bilagor inte signeras.
• Aviseringar skickas till signatärerna
• Återrapporering med händelser till externa applikationer
• Hämta signerat dokument och bilagor
• Hämta en valideringsrapport för det signerade uppdraget
• Hämta en händelserapport över alla stora händelser som rör signeringsuppdraget.
• Ta bort ett signeringsuppdrag

1.2. 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, föredraget aviseringssätt och eventuell metadata. Metadata används inte av Underskriftstjänsten - API men kan användas av klientapplikationen för att hålla klient-specifik information.

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.

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.

1.2.1. Signatärer

1.2.1.1. 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 https://confluence.cgiostersund.se/display/ST/Profilhantering.

1.2.1.2. Tillgängliga profiler

"signers": [
{
	"userId": "191212121212",
	"name": "Test Testsson Pnr",
	"signingProfile":
	"eln_ap_pnr_01",
    	"notificationTypes": [
		{
        	"method": "email",
        	"address": "signer1@company.com"
		}
	]
}]

"signers": [
{
	"userId": "191212121212@5563372191",
	"name": "Test Testsson Pnr+Orgno",
	"signingProfile": "eln_ap_pnr_01_orgid",
    	"notificationTypes": [
		{
        	"method": "email",
        	"address": "signer2@company.com"
		}
	]
}]

"signers": [
{
	"userId": "TST5565594230-135H",
	"name": "Test Testsson HSAid",
	"signingProfile": "digg_ap_hsaid_01",
    	"notificationTypes": [
		{
        	"method": "email",
        	"address": "signer3@company.com"
		}
	]
}]

"signers": [
{
	"userId": "TST5565594230-135H@5563372191",
	"name": "Test Testsson HSA-id+Orgno",
	"signingProfile": "eln_ap_orgperson_01",
	"notificationTypes": 
	[
		{
        	"method": "email",
        	"address": "signer4@company.com"
        }
	]
}]

"signers": [
{
	"userId": "XA:193911137077",
	"name": "Bernt Olof Larsson Foreign eID",
	"signingProfile": "eln_ap_eidas_natper_01",
	"notificationTypes": 
	[
		{
        	"method": "email",
        	"address": "signer5@company.com"
        }
	]
}]

1.2.1.3. Standardattributmappning

För mer information angående mappning av standard attribut se Profilhantering

1.2.2. 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.

1.2.3.  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.

1.3.  Avisering

1.3.1.  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.

1.3.2. Avisering av andra parter

Andra parter som behöver underrättas när en underskriftsbegäran har slutförts kan läggas till i underskriftsbegäran. Varje part läggs sedan 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 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 1.4 Åtkomst för användare som inte är signatärer

1.3.3. 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:
• DocumentSignedEvent
• NotifyDocumentSignedEvent
• SignFlowCancelledEvent
• NotifySignFlowCancelledEvent
• SignFlowStartedEvent
• SignFlowStartedReminderEvent
• UserCancelledEvent
• UserSignedEvent
• UserSignRequestEvent

Beroende på det valda underskriftsflödet kanske inte varje händelse är tillgänglig.

1.4. Åtkomst för användare som inte är signatärer

Signatärerna och skaparen av signeringsuppdraget (om den skapades via Underskriftstjänsten Webb) 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 2.1 SAD - Underskriftstjänsten Webb och API

1.4.1.  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.

"stakeholders": [
	{
		"key": "clientSubject",
		"value": "TST5565594230-135M"
	}
]

1.5. Ladda upp dokument

Dokument som ska undertecknas laddas upp till Underskriftstjänsten i två steg:

1. Skapa ett dokument objekt
2. Ladda upp dokumentet med hjälp av "octet-stream"

Det första steget returnerar ett dokument objekt med en plats och ett dokument-ID. Lägg till "/content" i "Location" fältet när dokumentfilen laddas upp.

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. Detta kontrolleras av en flagga i typen CreateDocumentEntry.

1.5.1.  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 CreateDocumentEntry-typen.

1.6. 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 i svaret.

1.7. 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.

1.8. 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.

1.9. 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.

1.10. 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.

1.11. 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. 

1.12.  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

1. Skapa ett signeringsuppdrag
2. Skapa ett dokument objekt
3. Ladda upp dokumentinnehållet
4. Upprepa steg 2 och 3 för alla aktuella dokument
5. Starta underskriftsflödet
6. Hämta status tills signeringsuppdraget har signerats, avbrutits eller en timeout har inträffat, eller använd en status-callbacks.
7. Hämta de signerade dokumenten
8. Hämta valideringsrapporten
9. Möjligtvis hämta händelseloggen
10. Ta bort signeringsuppdraget, eller låt den tas bort automatiskt av Underskriftstjänsten efter en konfigurerbar tidsperiod

2. Å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

3. Referenser

Här nedan finns exempel på hur anrop ser ut samt de olika funktionerna kan användas.

3.1. Användningsfall

För en mer detaljerad Systemdokumentation tillsammans med användningsfall se SAD - Underskriftstjänsten Webb och API

3.2. 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

3.3. 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