2.1 Utvecklarinfo - Underskriftstjänsten API
- Former user (Deleted)
- Tobias Haraldsson
- admin (Unlicensed)
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
• 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
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.
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
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. |
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 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
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.
Å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
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"
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.
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.
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
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 |
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