Pro embedování podpisové relace rozlišujeme 2 přístupy:
Podepisování jednoho příjemce - rozhraním podpisu prochází jeden konkrétní příjemce
Podpisovou ceremonii - v rámci jednoho podpisového rozhraní 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 (dokumentace), kdy u příjemců je třeba zvolit jednu z rolí:
signer - podepisující
approver - schvalovatel
Příjemci dorazí zároveň i e-mail s výzvou k podpisu/schválení (výchozí nastavení); výzvu je možné pro příjemce vypnout pomocí “channelForSigner=none” (pouze přes API) a je jedno, kterou cestu pro podepsání zvolí.
Krok 2: Vygenerovat URL
Přes API si vygenerujete URL pro embedování podpisové relace konkrétního podepisujícího. K tomu slouží endpoint: /api/envelopes/{envelopeID}/recipients/{recipientID}/embed
Endpoint v requestu očekává JSON objekt s nepovinnými parametry:
returnUrl - URL, na kterou DigiSign přesměruje po úspěšném podepsání. Pokud parametr nevyplníte, k přesměrování nedojde, a zobrazí se výchozí stránka o úspěšném podpisu.
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ě.
expireAt - datum a čas expirace platnosti vygenerované URL
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.
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 nastavenou 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í.
Přes API si vygenerujete URL pro embedování podpisové ceremonie. K tomu slouží endpoint: /api/envelopes/{envelopeID}/embed/signing
Endpoint v requestu očekává JSON objekt s parametry:
recipients (povinné) - pole s ID příjemců, kteří mají v rámci ceremonie podepisovat
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.
expireAt (nepovinné) - datum a čas expirace platnosti vygenerované URL
Možná úskalí embedování
iframe
Otevírání do <iframe> je momentálně sice možné, ale tuto metodu nedoporučujeme. Povolení iframe přidává bezpečnostní rizika a může se stát, že budeme nuceni ho v budoucnu zakázat (https://en.wikipedia.org/wiki/Clickjacking). IFRAME není podporovaný v případě Bank iD ověření (banky to 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í 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">).
Jak si vyzkoušet embedovaný podpis bez programování
Přihlásíte se do webového rozhraní v testovací zóně - https://app.digisign.digital.cz
Vytvoříte a odešlete obálku k podpisu
u podepisujícího zvolíte roli “Podepisuje osobně”
V detailu obálky kliknete na tlačítko “Debug dialog”
U daného příjemce pod dropdownem “...” je odkaz “Demo”
Do nového okna se otevře DEMO embedovaného podpisu, kde DigiSign je umístěn do iframe.