Pro embedování podpisové relace rozlišujeme 2 přístupy:
Podepisování jednoho příjemce - podpisem prochází jeden konkrétní příjemce
Podpisovou ceremonii - v rámci jedné podpisové relace se podepisuje více příjemců najednou
Embedování podpisu jednoho podepisujícího
Pro implementaci embedded podepisování stačí tyto 3 kroky:
Krok 1: Vytvořit obálku
Přes webové rozhraní či REST API vytvoříte obálku, kdy je u příjemců třeba zvolit jednu z rolí:
signer - podepisující
approver - schvalovatel
Příjemcům zároveň dorazí e-mail s výzvou k podpisu/schválení. Pokud si nepřejete, aby jim tyto e-maily chodily, tak u příjemců nastavte Doručení výzvy k podpisu → Nedoručovat (je třeba prvně povolit v Nastavení > Bezpečnost). Případně přes API odesláním parametru příjemce channelForSigner = none.
Krok 2: Vygenerovat URL
Odkaz pro vytvoření embedovaného podpisu obálky získáte provoláním endpointu Embed Envelope Recipient:
POST /api/envelopes/{envelopeID}/recipients/{recipientID}/embed
Endpoint v requestu očekává JSON objekt s nepovinnými parametry.
1) returnUrl
URL, na kterou DigiSign přesměruje po potvrzení uživatelské operace. K této URL automaticky doplníme parametr s typem události ve formátu "event=success", seznam událostí:
success - dokončené podepsání/schválení
declined - odmítnutí podpisu
dissaproved - zamítnutí schválení
Pokud parametr nevyplníte, k přesměrování nedojde a zobrazí se výchozí potvrzovací stránka DigiSign.
2) failureUrl
URL, na kterou DigiSign přesměruje, pokud se během podepisování vyskytne chyba. K této URL automaticky doplníme parametr s typem chyby ve formátu "error=lockedError", seznam errorů:
lockedError - obálka je uzamčena pro změny
bankIdClaimsMismatch - neshoda ověřovaných dat s Bank iD
identificationClaimsMismatch - neshoda ověřovaných dat s DigiSign Identify
identificationDenied - identifikace (DigiSign Identify) zamítnuta
certificateNameMismatch - neshoda jména podepisujícího se jménem na certifikátu
certificateSignatureFailed - podpis certifikátem selhal
internal - generická chyba
Pokud parametr nevyplníte, k přesměrování nedojde a zobrazí se výchozí stránka s informací o chybě.
3) expireAt
Datum a čas expirace platnosti vygenerované URL. Nebude-li parametr poslán, automaticky je platnost získaného odkazu 5 minut.
Po vypršení platnosti odkazu je klientovi zobrazena obrazovka Obálka neexistuje.
Krok 3: Zobrazit URL uživateli
Uživateli zobrazíte získanou URL přesměrováním nebo do nového okna.
Embedování podpisové ceremonie
Využívá se zejména pro podepisování přes mobilní aplikaci, kdy je možné na jednom zařízení (tzv. zařízení zprostředkovatele) podepisovat za více příjemců najednou.
Podmínky pro vyvolání podpisové ceremonie
Využití podpisové ceremonie je podmíněno následujícími nastaveními:
Příjemci musí mít nastaven typ podpisu Vlastnoruční ("signatureType":"biometric")
Příjemci nesmí mít nastaveno žádné ověření, tedy přes API nastavit hodnoty "none" pro tyto atributy: authenticationOnOpen, authenticationOnSignature
Příjemci musí mít nastavenu roli Podepisuje osobně ("role":"in_person") a zároveň zadaný e-mail zprostředkovatele, tj. uživatele DigiSign, na jehož zařízení budou podepisovat ("intermediaryEmail"). Ve webovém rozhraní se tato role nastaví automaticky na pozadí, jakmile podepisujícímu nastavíte Zařízení = Zařízení zprostředkovatele (osobně)
Po odeslání obálky příjde zprostředkovateli e-mail s výzvou k zajištění podpisu. Podepisujícím v roli in_person výzva k podpisu neodchází.
Vygenerování URL podpisové ceremonie
Odkaz pro vytvoření embedovaného hromadného podpisu obálky získáte provoláním endpointu Embed Evelope Signing:
POST /api/envelopes/{envelopeID}/embed/signing
Endpoint v requestu očekává JSON objekt s parametry.
1) recipients (povinné)
Pole s ID příjemců, kteří mají v rámci ceremonie podepisovat. Uváděno jako cesta k příjemci tedy ve formátu:
/api/envelopes/{{envelopeID}}/recipients/{{envelope_recipientID}}
2) returnUrl (nepovinné)
URL, na kterou DigiSign přesměruje po dokončení podepsání. Pokud parametr nevyplníte, k přesměrování nedojde, a zobrazí se výchozí stránka o úspěšném podpisu.
3) expireAt (nepovinné)
Datum a čas expirace platnosti vygenerované URL. Nebude-li parametr poslán, automaticky je platnost získaného odkazu 5 minut.
Po vypršení platnosti odkazu je klientovi zobrazena obrazovka Obálka neexistuje.
Odchytávání Eventů
V rámci <iframe> nebo vyskakovacího okna se při konečných stavech (koncept uložen, koncept zahozen, obálka odeslána) v rámci javascriptu volá .postMessage() s objektem, ve kterém se nachází status
{
"status": "signed"
}tyto stavy je možné zachytit pomocí
window.addEventListener(‘message’, () => { //* your code *// });Seznam Eventů v podpisové částí
signer
Možná úskalí embedování
iframe
Otevírání do <iframe> je momentálně sice možné, ale tuto metodu nedoporučujeme používat. Povolení iframe přidává bezpečnostní rizika a může se stát, že ho budeme nuceni v budoucnu zakázat.
Iframe není podporovaný v případě Bank iD ověření či Bank iD Sign (banky jej z bezpečnostních důvodů blokují).
Embedování ihned po odeslání obálky
Odeslání obálky probíhá asynchronně na pozadí, a může chvíli trvat (řádově vteřiny, max 1 minutu) - dochází zde k přípravě dokumentů, odeslání emailů/sms, zpracování automatických podpisů, aj. Pokud by obálka ještě nebyla připravena, endpoint vrátí chybu, že příjemce ještě není odeslaný.
Technicky můžete embedování ihned po odeslání řešit zobrazením stránky s textem např. "Obálka se připravuje" a s automatickým refreshem (pomocí Javascriptu, nebo <meta http-equiv="refresh" content="2">).
Vyzkoušejte embedovaný podpis bez programování
Pro vyzkoušení embedování bez nutnosti implementace nabízíme naše jedoduché demo (dostupné pouze z testovacího prostředí).
Na stránce je možné vyzkoušet podpis více podepisujících v ceremonii (současně na jednom zařízení) - Embedování podpisové ceremonie obálky
Nebo podpis jednotlivých podepisujících - Embedování podpisu příjemce