Embedování umožní uživatelům vašeho systému zobrazit, spravovat a/nebo odesílat obálky přímo z vašeho systému, namísto prostředí DigiSignu. Vaši uživatelé tak nemusí ani mít uživatelský účet DigiSign, nemusí se do něj hlásit.
Pro úpravu a odeslání konkrétní obálky mají uživatelé 5 minut. Poté si musí případně vygenerovat nový odkaz.
Embedování editace/detailu obálky
Pro embedování je potřeba mít existující obálku (tedy znát její ID). Pokud ještě obálku nemáte můžete ji vytvořit přes REST API nebo ve webovém rozhraní.
Pro vytvoření embedovacího odkazu slouží endpoint Embed Envelope
/api/envelopes/{{envelopeID}}/embed
target
V requestu lze pomocí atributu target určit, kam má odkaz směřovat:
edit - editace obálky (výchozí)
tags - umísťování polí
detail - detail obálky
Pro embedování editace nebo umísťování polí musí být obálka ve stavu koncept (draft), nebo korekce (correction).
allowedActions
Pomocí atributu allowedActions lze určit povolené akce na detailu obálky. Pokud se atribut neodešle, jsou povolené všechny akce.
Akce nad detailem obálky:
envelopeResend - odeslat znovu obálku
envelopeCancel - zrušit obálku
recipientResend - odeslat znovu příjemci
recipientEdit - upravit příjemce
recipientDelete - smazat příjemce
Akce nad editací / umístěním polí obálky:
signatureTagManipulation - změnit umístění pole Podpis
approvalTagManipulation - změnit umístění pole Schválení
attachmentTagManipulation - změnit umístění pole Příloha
documentTagManipulation - změnit umístění pole Osobní doklad
dateOfSignatureTagManipulation - změnit umístění pole Datum podpisu
radioButtonTagManipulation - změnit umístění pole Přepínací pole
textTagManipulation - změnit umístění pole Text
checkboxTagManipulation - změnit umístění pole Zaškrtávací pole
envelopeSend - odeslat obálku
documentReplace - vyměnit dokument
documentRename - změnit název dokumentu
language
Atributem language se určí, v jakém jazyce bude výsledná stránka zobrazena
POST /api/envelopes/3974d252-b027-46df-9fd8-ddae54bc9ab9/embed
{
"target": "detail",
"allowedActions": ["envelopeResend", "envelopeCancel", "recipientResend", "recipientEdit", "recipientDelete"],
"language": "en"
}
V odpovědi se vrátí url, s platností 5 minut
{
"hash": "154715c6978c4614ae69d88be591fcd5",
"url": "https://api.digisign.org/ee/15471...1fcd5",
"iat": 1629972916,
"exp": 1629973216,
}
Na vrácenou url lze přesměrovat uživatele systému a otevře se mu požadovaná stránka editace obálky. Případně lze url otevřít do <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)
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": "sent" // discard, saved
}
tyto stavy se dají zachytit pomocí
window.addEventListener(‘message’, () => { //* your code *// });
Seznam Eventů v editační částí
[ ‘sent’, ‘saved’, ‘discarded’, ’logout’] - možné akce na odchycení u obálky v editaci
Seznam Eventů v podpisové částí
[‘signed’] - možné akce na odchycení v podpisové části
Seznam Eventů na Envelope Detail
[‘canceled’, ‘correction’, ‘discarded’, ‘resend’] - možné akce na odchycení v obálce detailu
Seznam Eventů recipenta na Envelope Detail
Při těchto akcích je kromě klíče status k dispozici také ‘recipientId’ pro identifikaci, kterého recipienta se změna týká
[‘recipientResend’, ‘recipientRemove’, ‘recipientUpdate’] - možné akce na odchycení v obálce detailu
Demo
Zde si můžete vyzkoušet embed okna bez implementace https://app.digisign.digital.cz/demo