Přeskočit na hlavní obsah

Embedování podpisu

Potřebujete podepisování vyvolat z vlastní aplikace nebo podepsat za více příjemců najednou? K tomu slouží embedování podpisové relace.

Klára Šleisová avatar
Autor: Klára Šleisová
Aktualizováno před více než týdnem

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

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.

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:

  1. Příjemci musí mít nastaven typ podpisu Vlastnoruční ("signatureType":"biometric")

  2. Příjemci nesmí mít nastaveno žádné ověření, tedy přes API nastavit hodnoty "none" pro tyto atributy: authenticationOnOpen, authenticationOnSignature

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

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

Dostali jste odpověď na svou otázku?