- Jaké jsou varianty vyvolání podepsání z integrované aplikace?
- Jak se předávají podklady k podepisování?
- Jaké parametry jsou při volání nepovinné a k čemu se používají?
- Jaký je nejjednodušší scénář podepisování při integraci?
- Jak vkládat podpisy automaticky?
- Jak odeslat několik dokumentů v jedné sadě?
- Jak vybrat, které typy podpisu podepisující mají použít?
- Jak vhodně určit název dokumentu?
- Jak se předávají identifikační čísla dokumentu?
- Jdou změnit texty zasílaných e-mailů a SMS?
- Jak získám výsledek předání podkladů pro podpis
Jaké jsou varianty vyvolání podepsání z integrované aplikace?
Je několik způsobů, jak Signi propojit s aplikací. Uživatelům lze zpřístupnit jeden způsob nebo i více, aby si mohli vybrat způsob odpovídající situaci, v nichž potřebují podepisovat.
Různé způsoby vyvolání Signi z integrované aplikace.
1. Distanční podpis
Po vyvolání podpisu v integrované aplikaci odešle Signi e-mailové zprávy s odkazem na stránky pro podepsání v pořadí určeném podpisovým scénářem. Pokud je uvedeno telefonní číslo, může odcházet i SMS notifikace. Je to obdoba standardního odeslání dokumentu k podpisu přes uživatelské rozhraní Signi. Uživatel vůbec Signi nevidí, pracuje výhradně s integrovanou aplikací.
Při volání Signi API se dokument předává do stavu K odeslání tj. "state": "pending".
2. Podpis v integrované aplikaci
V uživatelském rozhraní Signi je volba Podpis na jednom zařízení, kdy navrhovatel i všechny protistrana/y jsou na jednom místě a podepisují v Signi v jednom okamžiku na jednom zařízení.
Při integraci s jinou aplikací lze toto zrealizovat obdobně s tím, že se podepisuje v integrované aplikaci. Signi při předání dokumentů či podkladů pro vzor vrací URL pro podpis jednotlivých podepisujících - viz Jak získám výsledek předání podkladů pro podpis. Integrovaná aplikace pak zobrazí stránky s těmito adresami pro podpis jednoho či více podepisujících. Pozor, pokud je podepisujících více, musí mít všichni svůj prostor k podpisu. Pokud se podepisuje více dokumentů najednou v sadě, pořád je vše zobrazené pod jedním URL stránky k podpisu, jen vidí uživatel v levém panelu několik záložek s jednotlivými dokumenty.
Při volání Signi API se dokument předává do stavu K odeslání tj. "state": "pending".
3. Signi jako fronta práce
V tomto režimu integrovaná aplikace pošle dokument do Signi tak, aby se v Signi ukázal pracovníkovi navrhovatele pracujícího s tabletem či mobilem jako dokument ke zpracování.
Obchodník jednající s klientem na provozovně nebo u klienta, řidič předávající zboží, servisní technik zasahující u zákazníka podepíše dokument na svém zařízení - typicky tabletu či mobilu.
Při volání Signi API se dokument předává do stavu Rozpracováno tj. "state": "draft".
4. Signi přes QR kód
Při této variance jeden pracovník používá jak počítač s firemním IS tak Signi
Propojená aplikace zobrazí QR kód s URL stránky k popisu, kterou vrátí Signi API po předání dokumentu k podpisu. Tento kód načte tablet a zobrazí příslušnou stránku k podpisu. Nemusí z něj být při tom nikdo přihlášen do Signi. Při volání Signi API se dokument předává do stavu K odeslání tj. "state": "pending".
Alternativně se může při volání Signi předat dokument do seznamu dokumentů k podpisu v Signi. QR kód v tomto případě bude sloužit k zobrazení dokumentu uživateli přihlášenému v Signi pro další zpracování.
Jak se předávají podklady k podepisování?
1. předání souborů
Do Signi se z vaší Aplikace předá soubor k podpisu, formát viz V jakých formátech se předávají soubory k podpisu? a informace o umístění podpisů v dokumentu.
Protistraně je pak při schvalování dokumentu zobrazen dokument včetně polí k podpisu.
Dokument včetně podpisů je ze Signi zaslán zpět do aplikace jako soubor PDF.
Více viz Vytvoření smlouvy / dokumentu 2.0 > Z dokumentu a “Jak při předávání dokumentů k popisu předat informaci o umístění podpisů?” níže.
2. Předání parametrů pro vzor
V Signi je připraven vzor dokumentu se značkami odpovídajícími jednotlivým parametrům dokumentu na vhodná místa ve dokumentu.
Konkrétní hodnoty parametrů, například jméno klienta, se předají jako podklady při vyvolání požadavku na vytvoření smlouvy.
Dokument včetně podpisů je ze Signi zaslán zpět do aplikace v PDF .
Více k tématu Vytvoření smlouvy / dokumentu 2.0 > Ze vzoru a odstavec níže Jak při použití vzorů při podepisování předat parametry k vyplnění do vzoru.
Jaké parametry jsou při volání nepovinné a k čemu se používají?
Pro zaslání dokumentu k podpisu je nutný jen e-mail, jméno a příjmení. Telefon je nutný, pouze pokud neumožníte protistranám ho zadat a měnit. Nicméně mezi parametry jsou i další identifikační údaje.
Některé údaje jsou nutné při předávání podkladů pro vzor, kdy ve vzoru dokumentu není žádná identifikace smluvních stran a vyplňují se z parametrů předaných při volání.
I zde je třeba povinné jméno, datum narození má smysl zadávat tehdy, kdy zákazník chce, aby pro přesnější identifikaci smluvní strany bylo uvedeno.
Při předání dokumentů nejsou nutné, nicméně pro zachování stejné struktury parametrů tam zůstávají.
Ve zprávách podepisujícím přes SMS a e-mail se použije Jméno, Příjmení či Organizace coby identifikace odesílatele dokumentu. Stejně jako ve jménu odesílajícího v hlavičce e-mailu.
Pokud se předají údaje o podepisujících ve strukturované podobě, bylo by možné po jejich následné registraci jim zobrazit i jejich dokumenty podepsané bez registrace. Vzhledem ke GDPR a potenciálnímu riziku omylu tato funkce zřejmě nebude dostupná.
Jaký je nejjednodušší scénář podepisování při integraci?
Při propojování je dobré začít nejjednodušším scénářem podepisování a pak ho případně zesložiťovat dle potřeb uživatelů. Jak vypadá:
Autorem / navrhovatelem dokumentů (is_proposer=true při volání API ) je e-mail zakladatele workspace v Signi ,do kterého se přes API dokumenty posílají, tj. typicky e-mail hlavního účtu na Signi pro firmu, nebo někoho, kdo tam má právo podepisovat. Dokument pouze schvaluje (contract_role=”approve”), tj. není na dokumentu vidět jeho podpis. Při volání přes API proběhne jeho schválení automaticky.
Všichni podepisující či schvalující bez ohledu na to, zda jsou z firmy navrhovatele či nikoliv, jsou označeni jako protistrany (is_proposer=false). Díky tomu vůbec nemusí mít zavedený účet v Signi, pouze v integrované aplikaci. Přijdou jim všem výzvy k podpisu a oni mohou dokument podepsat. Nevýhodou je pouze to, že fyzicky musí podepsat každý dokument.
Více viz Příklad 2
Jak vkládat podpisy automaticky?
Pokud pracovníci organizace:
mají vytvořený účet na Signi,
byli vlastníkem workspace pozváni do workspace s nastaveným právem podepisovat a pozvánku přijali,
může být jejich podpis vložen do dokumentu automaticky. Podle EIDAS je to v pořádku, podpis probíhá v kontrolovaném prostředí Signi, které zajistí, že podpis bude neoddělitelně připojen k odpovídajícím dokumentům, a volající aplikace (vaše) daného člověka autentifikovala a autorizovala ho k vytvoření, podepsání a předání dokumentu k podpisu dalším protistranám.
Scénář podepisování předaný přes API pak bude obsahovat například takto , autorem / navrhovatelem dokumentu, jehož podpis může být za podmínek výše vložen automaticky je [email protected]:
{ "settings": { "signing_order": "one_at_a_time", "autosign_proposers": "V Praze" }, "people": [ { "is_proposer": true, "email": "[email protected]", "contract_role": "sign" }, { "is_proposer": false, "party_order": 1, "email": "podepisujícizakazní[email protected]", "contract_role": "sign" } ],
Libovolný uživatel workpace s právem podpisu jako autor/navrhovatel dokumentu může být podepsán i automaticky. Musí ale podepisovat jako první před protistranami. Pro propojení na Signi přitom lze použít API klíč zakladatele workspace. 3 pracovníci/e v HR tak mohou být na "svých" dokumentech automaticky podepsány, pouze při volání API jsou jejich maily uváděny jako emaily navrhovatele tj. “is_proposer”: true u osoby na první místě podpisového scénáře v poli Person.
Více k tématu Jaké jsou možnosti podepisování zástupců organizace používající Signi?
Jak odeslat několik dokumentů v jedné sadě?
Posloupnost volání
endpoint template {.... Last_document:false… }
endpoint template attachment {.... Last_document:false… }
endpoint template attachment {.... Last_document:false… }
endpoint template attachment {.... Last_document:true… }
Dokument může mít neomezené množství příloh, podpis každého je účtován jako samostatný podpis.
Pokud má člověk podepsat více dokumentů v jedné dávce, dojde mu pouze jedna SMS a e-mail. Pak se mu ukáží jednotlivé dokumenty, které musí podepsat jeden po druhém.
Několik dokumentů odeslaných v jedné sadě - například zákazníkovi přijde jeden e-mail, po jeho rozkliknutí má přístup ke všem dokumentům v sadě viz výše a může je podepsat (např. nabídku či smlouvu) či jen schválit (např.- Všeobecné podmínky).
PŘIPRAVUJEME: Výsledek podpisu každého z dokumentů se nyní předává samostatným voláním příslušného webhooku pro daný dokument. Chceme přidat volbu, kdy se webhook bude volat jen jednou pro celou odeslanou sadu.
Jak vybrat, které typy podpisu podepisující mají použít?
Signi umožňuje podepisovat více typy podpisů viz Typy podpisů v Signi. Typy podpisu se určují pro každého podepisujícího zvlášť v sekci Person, atributu "contract_role". Možné hodnoty atributu "contract_role" a odpovídající typy podpisu:
notice - Na vědomí - Osobě pouze odchází notifikační mail při uzavření dokumentu anebo pří všech operacích na dokumentu viz více funkce “Na vědomí” a příklad volání API.
approve - Schválit - Podepisující musí kliknout na tlačítko “Schválit”, ale jeho podpis nikde na dokumentu není vidět viz funkce Schválení.
sign - Biometrický podpis - Podepisuje se obdobou vlastnoručního podpisu na listinném dokumentu, součástí podpisu mohou a nemusí být citlivé osobní údaje dle nastavení workspace.
sign_bank_id_sign - BankID SIGN - Podpis přes jednu ze služeb Bankovní identity / BankID, umožnění podpisu je třeba v Signi aktivovat, jinak se vrátí chybová hláška, pro aktivaci se obraťte na [email protected], a dohodnout se na způsobu provozování - buď má navrhovatel smlouvu s Bankovní identitou a v Signi využije svá nastavení služby nebo mu může Signi službu přeprodávat.
sign_certificate - Podpis certifikátem a kvalifikovaný podpis - Podpis kvalifikovaným nebo komerčním certifikátem, umožnění podpisu je třeba v Signi aktivovat, jinak chybová hláška
"Contract role [sign_certificate] is not enabled for this workspace"
Pro aktivaci se obraťte na [email protected]. Signi kvalifikované ani komerční certifikáty nevydává, je třeba si je zajistit u certifikačních autorit typu Post Signum, 1. CA jiné vydavatele nebo specializované služby, které vám se zřízením certifikátů pomohou.
Konkrétní příklady volání Signi API s různými typy podpisů viz Příklad 2 - Předání PDF dokumentu k podpisu.
Dočasná omezení voleb typu podpisů:Více typů podpisu u jednoho podepisujícího
- Zatím nelze u jednoho podepisujícího kombinovat více typů podpisů např. biometrický anebo BankID SIGN.
Kvalifikované podpisy
Z principu není možné automatické vložení podpisu.
V jednom podpisovém scénáři scénáři mohou být kombinované se Schválením a Na vědomí ale ne jinými typy podpisů (jinak chybová hláška "All people need to have role [approve OR sign_certificate] assigned" ).
Lze podepisovat na MS Windows a Apple Mac. Nelze podepisovat na tabletech a mobilních telefonech, která nemají nativní podporu práce s certifikáty v operačním systému, potřebná napojení na HMS pro uložení certifikátů připravujeme.
Zatím nelze kombinovat s umístěním podpisů na přidaný list Podpisového archu. Nyní předpokládáme, že s vloženým dokumentem již nelze manipulovat, pouze řídávat podpisy do podpisové vrstvy.
BankID SIGN
Z principu není možné automatické vložení podpisu.
V jednom podpisovém scénáři scénáři mohou být kombinované se Schválením a Na vědomí ale ne jinými typy podpisů.
Zatím nelze kombinovat s umístěním podpisů na přídaný list Podpisového archu. Nyní předpokládáme, že s vloženým dokumentem již nelze manipulovat, pouze řídávat podpisy do podpisové vrstvy.
Vkládaný dokument musí již být v podpiovém formátu PDF/A, některé banky jiný neumoňují podepsat. Konverze může vyvolat vizuální změny dokumentu, konverzi dokumentu připravujeme ji včetně jejího vynucení pří volání API.
Na vědomí
- Není ještě k dispozici na produkčním prostředí
Jak vhodně určit název dokumentu?
Název dokumentu je zároveň název souboru PDF podepsaného dokumentu, který se předává zpět do integrovaného systému anebo při stažení dokumentu z uživatelského rozhraní. Zároveň PDF soubor kontrolního list se jmenuje stejně jako PDF podepsaného dokumentu, jen v názvu je prefix KL_ .
Je tedy vhodné při integraci posílat do API v názvu dokumentu, tj. contract_name, nějakou unikátní hodnotu zároveň srozumitelnou pro podepisující. Půjde pak snadno dohledat jednoznačně jak dokument, tak jeho kontrolní list. Zároveň je třeba myslet na to, že název dokumentu se ukazuje podepisujícím v e-mailových a SMS notifikacích, tj. není úplně vhodné posílat např. číslo samotné. Příklad správného názvu: “Čestné prohlášení k reklamaci č. 6493543”.
Jak se předávají identifikační čísla dokumentu?
Nyní se pro identifikaci používá číslo dokumentu v Signi - Contract_ID, které je výsledkem vyvolání podpisu a je i součástí volání webhooku (v HEAD sekci).
Pokud si chcete předávat i identifikaci dokumentu v integrovaném systému, jako workaround je možné tuto identifikaci vložit do adresy webhooků.
PŘIPRAVUJEME: Předání identifikace dokumentu v integrovaném systému v logice “vaše číslo/naše číslo” do parametrů vyvolání podpisu i webhooků.
Jdou změnit texty zasílaných e-mailů a SMS?
Ano, lze - je to nastavení platné pro celý workspace/pracovní prostor a může je měnit jakýkoli uživatel s přístupem do prostoru.
Lze určit i jméno odesílatele, resp. jméno adresáta odpovědi (REPLY TO).
Parametry v textech k záměně dle aktuálního stavu:
{CONTRACTNAME} - Doplní název dokumentu, pokud není vyplněn název souboru nebo použitého vzoru
{NAME} - Doplní celé jméno vlastníka pracovního prostoru
{CLIENTNAME} - Doplní celé jméno klienta - u osob jméno a příjmení, u firem?
Jak získám výsledek předání podkladů pro podpis
Okamžitý výsledek předání podkladů pro podpis zjistíte synchronně jako “Response” na volání příslušného endpointu.
Pokud jsou podklady kompletní a validní, kód odezvy je 200. Chybové kódy začínají 400 , kde v body je popis chyby. Občas můžete narazit na univerzální chybu 500, snažíme se ji minimalizovat.
V BODY odpovědi získáte i hodnotu proměnné Contract_ID, což je identifikace dokumentu v Signi. Tento údaj je pak použit ve webhooku (viz dále), lze ho použít pro stažení Kontrolního listu s průběhem podpisování dokumentu apod.
Součástí odezvy jsou i URL unikátních adres stránek pro podpis dokumentu konkrétními podepisujícími/schvalujícími, které lze použít při integraci.
Příklady výsledků požadavku na podpis dokumentu či vzoru.
Byl tento článek užitečný?
To je skvělé!
Děkujeme Vám za zpětnou vazbu
Je ním líto, že jsme vám nepomohli
Děkujeme Vám za zpětnou vazbu
Zpětná vazba odeslána
Oceňujeme vaši snahu a pokusíme se článek opravit