Koncept Signi API

Owned by Zuzana Vankeova (Unlicensed)
Last updated: Nov 09, 2022 by Roman Řípa (Unlicensed)
4 min read

Princip propojení se Signi

Výhodou propojení aplikací a služeb se Signi 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 Signi  - 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 Signi a vyvolá ověření

  • b) Signi 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ů

Varianty použití Signi API

Předání podkladů

Podporujeme dva způsoby předávání podkladů při integraci:

  • Předání souborů - Ve vaší Aplikaci je vygenerován kompletní soubor ve formátu pdf, doc, docx, odt, který je s ostatními parametry odeslán do API Signi 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 Signi. Tato metadata společně s ostatními parametry jsou odeslány do API Signi. Více o vzorech zde.

Výchozí rozsah služeb Signi zahrnuje pouze předávání dokumentů. Použití vzorů je placené rozšíření.

Varianty vyvolání

Jsou 4 cesty vyvolání podepsání z integrované aplikace:

Předává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á v 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.

Toto se může hodit např. pro on-premise provozovaná řešení, která nejsou viditelná mimo firemní síť, tj. webhook nelze zrealizovat.

Více viz Jak získám výsledek předání podkladů pro podpis

3 kroky elektronického právního jednání

Elektronické právní jednání zahrnuje 3 kroky a to vzálenou identifikaci , el. podpis a archivaci elektronických dokumentů. Všechny tři kroky se nějakým způsobem promítají i do Signi API.

  • Vzdálená identifikace - v rámci podepisování v Signi probíhá standardně 2-faktorové ověření přes e-mail a telefon přes PIN zaslaný v SMS. Volitelně lze přes API vyvolat i pokročilé varianty vzdálené identifkace.

  • Podepisování - lze předávat soubory k podpisu nebo parametry pro vzory v Signi

  • Archivace - Dlouhodobou archivaci dokumentů lze zajistit přímo v Signi pomocí Signi Archiv . Alternativně lze jakýkoliv elektronický archiv se SIgni integrovat - podepsané uzavřené dokumenty posíoá Signi přes zpětně volané webhooky nebo si archiv dokumenty vhodné k archivaci zjiš%tuje archiv sám. Archiv dokumenty načtě, případně je může přes API ze Signi i smazat.

Způsoby autentikace

Jediný servisní účet v Signi

  • Nejjednodušší scénář propojení, kdy účet v Signi má zákazník pouze jeden a slouží pouze pro vytvoření workspace a fakturaci.

  • Žádný z podepisujících nemusí mít účet v Signi. 

  • Stačí použít jeden API klíč k celému pracovnímu prostoru v Signi.

Účty pro podepisující v Signi

  • Podepisující musí mít účet v Signi a při každém podpisu se přihlašují do Signi . 

  • Výhoda je, že mohou použít předpřipravené podpisy a lze řídit práva přístupu na úrovni Signi.

  • Lze stále používat jeden API klíč k celému pracovnímu prostoru v Signi. 

Připravujeme i možnost osobních API klíčů či autentikaci přes Oauth2 apod.

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 Signi a právo přístupu do daného workspace / pracovního prostoru v Signi. 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.

  • Protistrany - Může a nemusí mít účet v Signi. Dokument může podepsat a odmítnout. Pokud má účet v Signi, nový dokument vidí v Odeslaných dokumentech (pokud je zároveň navrhovatelem), nebo v Přijatých dokumentech (pokud není navrhovatelem).

Při integraci přes API je nejjednoudušší scénář Jediný servisní účet (viz výše). V tomto případě je automaticky navrhovatelem resp. autorem dokumentů vždy vlastník pracovního prostoru Signi, do kterého se posílá dokument k podpisu přes API. Ten na dokumentu nikde nefiguruje, ani ho nepodepisuje, ani ho neschvaluje. Podepisující či schvalovatelé, ať z firmy navrhovatele či mimo ni jsou smluvními stranami.

Existence účtu na službě Signi

Člověk podepisující, resp. schvalující dokument může a nemusí mít účet v Signi. Z hlediska volání API je to jedno, liší se pouze chování služby, resp. její uživatelské rozhraní před zobrazením dokumentu k podpisu.
Mohou tedy nastat 2 situace:  

  • uživatel nemá účet v Signi - po kliknutí na link v notifikační SMS / e-mailu se mu ukáže rovnou dokument k podepsání; až po podpisu se mu nabídne, zda si chce zřídit účet v Signi,

  • uživatel již má účet v Signi - po kliknutí na link v notifikační SMS / e-mailu se mu ukáže přihlašovací obrazovka Signi 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:

Formy vyjádření souhlasu:

Podepisuje - má podpis na dokumentu - s tím, že rypů podpisů je více
Schvaluje - jen potvrdí souhlas s dokumentem, podpis není vidět

Pořadí podepisování

  1. Podepisují nejdříve navrhovatelé a pak protistrany

  2. Záleží na pořadí podepisujících

Jak zajistit propojení

Integrace Signi na jiný systém může být zajištěna různými způsoby. Integraci může zajistit:

  • Tým Signi s využitím integrační služby Integromat. 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 Signi.  Dostane k tomu od Signi 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 Signi.  Dostane k tomu od Signi všechny podklady (viz tyto stránky) a podporu.