Propojení s iSmlouvou
Výhodou propojení aplikací a služeb s iSmlovou je jeho jednoduchost, celý proces zahrnuje 3 kroky.
Krok 1 - Vytvoření podkladových údajů
Ve vaší Aplikaci - ERP, CRM, DMS, webu, interní aplikaci apod. - jsou zadány požadované údaje či dokumenty o vašem klientovi / partnerovi / zaměstnanci, se kterým chcete uzavřít smlouvu přes API iSmlouva - dokumentů k podpisu se souřadnicemi podpisů anebo vzorů s parametry
Krok 2 - Vyvolání ověření
a) Ve vaší Aplikaci je/přidá se funkce, která na podnět uživatele předá podklady do iSmlouva a vyvolá ověření
b) iSmlouva má nebo připraví funkci, která bude přebírat podklady z vaší Aplikace a následně vyvolá ověření
Krok 3 - Převzetí výsledků
Ve vaší Aplikaci je/ se přidá informace o průběhu vytvoření a ověření dokumentů
Předání podkladů
Podporujeme dva způsoby předávání podkladů při integraci:
Předání souborů - Ve vaší Aplikace je vygenerován kompletní soubor ve formátu pdf, doc, docx, odt, který je s ostatními parametry odeslán do API iSmlouvy k podpisu.
Předání parametrů pro vzor - Vaše Aplikace poskytne metadata (hlavičky, obsah jednotlivých doplňovacích polí smlouvy apod.) pro doplnění vzoru dokumentu, který je vytvořen a uložen v aplikaci iSmlouva. Tato metadata společně s ostatními parametry jsou odeslány do API iSmlouvy.
Výchozí rozsah služeb iSmlouva zahrnuje pouze předávání dokumentů. Použití vzorů je placené rozšíření.
Více viz Jak se předávají podklady k podepisování?
Navrhovatel vs. smluvní strany
Při podepisování a tedy i předávání podkladů přes API je třeba odlišit:
Navrhovatel - Je tvůrce podepisovaného dokumentu a tedy musí mít účet v iSmlouvě. Může a nemusí být smluvní stranou, např. u realitních makléřů. Chodí mu zpět notifikace o tom, kdo dokument podepsal, odmítl podepsat apod. Může dokument zrušit. Nový dokument vidí v Odeslaných dokumentech. Ve variantě integrace "Jediný servisní účet" je právě tento účet tvůrcem dokumentu, který ale nepodepisuje.
Smluvní strana - Může a nemusí mít účet v iSmlouvě. Dokument může podepsat a odmítnout. Pokud má účet v iSmlouvě, nový dokument vidí v Odeslaných dokumentech, pokud je zároveň navrhoatelem nebo v Přijatých dokumentech, pokud nikoliv.
Existence účtu na službě iSmlouva
Člověk podepisující resp. schvalující dokument může a nemusí mít účet v iSmlouvě. Z hlediska volání API je to jedno, liší se ale chování služby, resp. její uživatelské rozhraní před zobrazením dokumentu k podpisu. Po kliknutí na notifikační SMS a e-mail, člověku, který:
nemá účet v iSmlouvě - se ukáže rovnou dokument k podepsání, až po podpisu se mu nabídne, zda si chce zřídit účet v iSmlouvě,
již má účet v iSmlouvě - se ukáže přihlašovací obrazovka iSmlouvy a po přihlášení má přístup k dokumentu k podepsání.
Scénáře podepisování
Ač se to na první pohled nezdá, existuje více různých variant podepisování resp. schvalování dokumentu, které lze navíc kombinovat pro různé zúčastněné strany:
Podepisuje
Schvaluje
Bianco podpis
Bez akce
Na vědomí
Potvrzuje pouze PINem
Podepisuje první / poslední / v pořadí
Podepisuje
Člověku se odesílá notifikační SMS a e-mail, musí dokument fyzicky podepsat.
Nastavení:
Is_proposer: true / false, jde-li o zástupce navrhovatele
"contract_role": "sign"
"autosign_place": parametr se nepředává anebo musí být prázdný
Člověk:
Člověk s daným e-mailem nemusí mít účet v iSmlouvě.
Pokud účet má a jde o zástupce navrhovatele, musí být v týmu pracovního prostoru/workspace, musí mít nastaveno právo podpisu, nemusí mít uložený grafický podpis.
Pokud účet má a nejde o zástupce navrhovatele, nemusí mít právo podpisu, nemusí mít uložený grafický podpis, předpokládá se, že má jediný workspace, do kterého se dokument umístí.
Ve variantě použití “Jediný servisní účet v iSmlouvě” skutečný statutární zástupce firmy není navrhovatelem tj. při volání je is_proposer = false, nesmí mít účet v iSmlouvě, jako navrhovatel bude veden servisní účet ve variantě “Bianco podpis”.
Bianco podpis
Navrhovateli se neodesílá notifikační SMS a e-mail, na dokumentu bude uveden jeho podpis. Příkladem použití jsou návrhy objednávek do určité výše.
Nastavení:
"contract_role": "sign",
"autosign_place": je vyplněn nějaký text, např. "V Praze"
Is_proposer: true
Člověk:
Tato možnosti se týká se pouze smluvní strany, která je zároveň navrhovatelem, tvůrcem dokumentu tj. Is_proposer: true. Uživatel s daným e-mailem musí být v týmu pracovního prostoru/workspace navrhovatele, má tam nastaveno právo podpisu a musí mít uložený grafický podpis ve svém uživatelském profilu. Pokud nemá uživatel uložený grafický podpis ve svém profilu, vrací se odpovídající chyba.
Schvaluje
Člověku se neodesílá notifikační SMS a e-mail, nic nepodepisuje, pouze zmáčknutím tlačítka dokument schválí.
Nastavení:
"contract_role": "approve"
"autosign_place": je vyplněn nějaký text, např. "V Praze"
Člověk:
Člověk s daným e-mailem nemusí mít účet na iSmlouvě.
Pokud účet má a jde o zástupce navrhovatele tj. is_proposer=true, musí být v týmu pracovního prostoru/workspace navrhovatele, musí mít nastaveno právo podpisu, nemusí mít uložený podpis.
Bez akce
Týká se situací, kdy někdo dokument navrhuje, ale není smluvní stranou. Příkladem je makléř v realitní kanceláři. Druhým příkladem je varianta použití “Jediný servisní účet v iSmlouvě” při integraci. Člověku se neodesílá notifikační SMS a e-mail, na dokumentu není jeho podpis, dokument má k dispozici pracovním prostoru.
Nastavení:
"is_proposer": true,
"contract_role": "approve",
"autosign_place": jakýkoliv text např. "V Praze"
Člověk:
Člověk s daným e-mailem je v týmu pracovního prostoru/workspace navrhovatele, nemusí mít právo podpisovat, nemusí mít uložený grafický podpis ve svém uživatelském podpisu.
Připravujeme
Připravujeme další varianty podepisování, například:
Na vědomí - Člověku se odesílá SMS a e-mail s odkazem na podepsaný dokument, resp. informace o jeho odmítnutí či expiraci, nijak se k dokumentu nevyjadřuje.
Podepisuje jen PINem - Člověku se odesílá notifikační SMS a e-mail, kromě schválení zadává PIN pro 2faktorovou funkcionalizaci.
Podepisuje první / poslední / v pořadí - Aktuálně notifikační SMS a e-mail odejde vždy všem stranám najednou. Tím se API liší od uživatelského rozhraní, kdy v rámci přípravy nejprve podepisuje navrhovatel a pat teprve protistrany. Pořadí podepisování půjde nastavovat.
Předání výsledků
Zpětným voláním
Součástí předávání podkladů pro podpis jsou i tři URL adresy tzv. “webhooků” pro každou hodnotu výsledku:
podepsáno - signed,
odmítnuto - rejected,
neověřeno - expired
kdy jeden z nich se vyvolá okamžiku, kdy daný stav nastane.
Průběžným ověřováním stavu
Někdy lze webhooky v integrovaném systému obtížně implementovat.
Místo toho je možné se dotazovat na aktuální stav dokumentu.
A to periodicky anebo např. při otevření detailu souvisejícího záznamu v integrovaném systému.
Více viz Jak získám výsledek předání podkladů pro podpis
Autentikace
Jediný servisní účet v iSmlouvě
Nejjednodušší scénář propojení, kdy účet v iSmlouvě má zákazník jen jeden a slouží pouze pro vytvoření workspace a fakturaci.
Žádný z podepisujících nemusí mít účet v iSmlouvě.
Stačí použít jeden API klíč k celému pracovnímu prostoru v iSmlouvě.
Účty pro podepisující v iSmlouvě
Podepisující musí mít účet při iSmlouvě a při každém podpisu se přihlašují do iSmlouvy .
Výhoda je, že mohou použít předpřipravené podpisy a lze řídit práva přístupu na úrovni iSmlouvy.
Lze stále používat jeden API klíč k celému pracovnímu prostoru v iSmlouvě.
Připravujeme i možnost osobních API klíčů či autentikaci přes Oauth2 apod.
Jak zajistit propojení
Integrace iSmlouvy na jiný systém může být zajištěna různými způsoby. Integraci může zajistit:
Tým iSmlouva s využitím integrační službywww.Integromat.com. Při malé náročnosti je v poplatku za využití integrace/API i zprovoznění integrace, při větší náročnosti je v poplatku časový a finanční odhad rozsahu prací.
Implementátor systému či integrací u daného uživatele přes integrační služby Integromat , MS Power Automate / Flow a podobně nebo přímým voláním API iSmlouvy. Dostane k tomu od iSmlouvy všechny podklady (viz tyto stránky) a podporu.
Interní IT uživatel přes integrační služby Integromat , MS Power Automate / Flow a podobně nebo přímým voláním API iSmlouvy. Dostane k tomu od iSmlouvy všechny podklady (viz tyto stránky) a podporu.
Stručný tahák - Co si ujasnit před integrací iSmlouvy s vaším systémem
Odkud se vezmou kontaktní údaje na podepisující? - Jméno, Příjmení, email, telefon (ten není povinný, ale pak ho uživatel musí zadat sám, aby mu přišla SMS a on mohl být ověřen).
Co se bude to posílat? - Hotový dokument PDF/DOCX/HTML/XSLX nebo jaký vzor a parametry pro něj.
Jak se vyvolá akce podpisování? - Akce v menu na relevantním záznamu, nastavení nějakého custom pole na hodnotu "Odeslat k podpisu” apod.
Kde uživateli ukážu výsledek podpisu? - Stav podepisování / výsledný dokument případně celou historii podepisování (viz kontrolní list)
Jak se umístí podpisy? - Nejjednodušší je statické umístění na přesné souřadnice (nyní pro formuláře), umístění na konci dokumentu (lze doplnit brzy: iSmlouva vloží podpis, jméno, příjmení, místo , čas ), dynamické umístění podpisu (cílový stav, placeholdery pro podpisy v dokumentu, vyžaduje flexibilitu určení např. více smluvních stran, za každou stranu podepisuje více lidí).
Jak se předávají výsledky zpět? - Preferovanou variantou je webhook volající aktivně integrovaný systému s výsledkem podepisování. Alternativně se lze z integrovaného systému periodicky ptát na výsledek podepisování.
Jaká bude vazba mezi uživateli a pracovními prostory iSmlouvy? - Nejjednodušší scénář: Na iSmlouvě jen zavedený servisní účet pro celý integrovaný systém nebo jeho jednotlivé koncové firemní zákazníky. Ten se při volání API uvádí jako navrhovatel dokumentu, který pouze "schvaluje" (nic se nikde nezaškrtává). Pokud má podepisovat někdo z firmy, je pak uveden jako jedna z podepisujících stran, přijde mu email a SMS. Pro každého zákazníka je vytvořen na iSmlouvě pracovní prostor, kde jsou jeho dokumenty a který má svůj API klíč používaný pří vládání dokumentů do jeho prostoru přes API. Další scénáře jsou možné.
Kdo bude platit? - Bud měsíční vyúčtování koncovému zákazníkovi zasílá provozovatel integrovaného systému a nakupuje kredity u iSmlouvy za velkoobchodní cenu, anebo koncový zákazník platí iSmlouvě a provozovatel integrovaného systému posílá měsíční fakturu na provizi. V oboru případech iSmlouva dodá počet kreditů po workspacech / zákaznících za měsíc.