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

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

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 https://inera.atlassian.net/wiki/spaces/UTJ/pages/3501787166/Profilhantering.

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"
        }
	]
}]

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.

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:

Följande händelser kan generera aviseringar till intressenter:

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

      "createdBy": {
        "name": "Test Testsson",
        "userId": "191212121212",
        "notificationTypes": 
        [
          {
            "method": "email",
            "address": "creator@cgi.com"
          }
        ]          
      }

Å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 /wiki/spaces/UTJ/pages/4065591297.

 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

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

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 skapar ett dokumentobjekt med ett nytt dokument-ID. Svaret från tjänsten returnerar returnerar den fullständiga URL’en till dokumentet i “Location” HTTP headern.

Nästa steg är att ladda upp dokument innehållet som en octet stream, dvs som en binärström. Platsen att ladda upp dokumentinnehållet till fås genom att lägga till “/content” till värdet som angavs i “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 i svaret.

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

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

Å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

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