Přeskočit na hlavní obsah
Embedování správy obálky

Obálky nemusíte spravovat jen v DigiSignu, ale můžete je zobrazit, spravovat a/nebo odesílat přímo z vašeho systému.

Klára Šleisová avatar
Autor: Klára Šleisová
Aktualizováno před více než měsícem

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

Dostali jste odpověď na svou otázku?