Jak se předávají podklady k podepisování?
Předání souborů
Do Signi se z vaší Aplikace předá soubor k podpisu v PDF, DOCX apod. 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.
Předání parametrů pro vzor
V Signi je připraven vzor dokumentu se značkami odpovídajícími jednotlivým pametrů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 “Jak při použití vzorů při podepisování předat parametry k vyplnění do vzoru?” níže.
Jak při předávání dokumentů k popisu předat informaci o umístění podpisů?
Dynamické umístění podpisu
Nejjednodušším způsobem, jak umístit podpisy do dokumentů pří předávání přes API, je připojení samostatného podpisového archu s podpisy na závěr dokumentu. Pří volání endpointu Vytvoření smlouvy 2.0 > Z dokumentu se jako jeden z parametrů v sekci settings uvede "missing_positions": "append_to_the_end" viz niže nebo celý příklad Hello World 2 .
"settings": {
"signing_order": "all_at_once",
"autosign_proposers": "V Praze",
"missing_positions": "append_to_the_end"
},
Příklad uvedení parametru misssing_positions
Přiklad dynamickoého umístění podpisu
Statické umístění podpisů
Určuje se parametry X, Y, sign_proposer[position][x] sign_proposer[position][y] sign_proposer[position][page] a sign_negotiator[position][x] sign_negotiator[position][y] sign_negotiator[position][page]
Jde o vzdálenost horního levého rohu podpisu od horního levého rohu dokumentu, bráno k rozměrům nahrávaného dokumentu v %, tj. hodnota je v rozmezí 0 - 100.
Doporučená velikost podpisů pro nahrání do profilu podepisujícího: od 2034 x 792 do 646 x 298
Určuje se umístění každého podpisu zvlášť, tj. na dokumentu může být libovolný počet podpisů, např. u vícestranných smluv či více podepisujících statutářů.
Umístění podpisů při použití vzorů v Signi
Pří použití vzorů dokumentů spravovaných přímo v Signi není třeba umístění podpisů řešit, umístění i velikost podpisů je daná vzorem.
PŘIPRAVUJEME: Velikost podpisů v nahrávaných dokumentech
velikost podpisu se vždy přizpůsobuje velikosti zařízení
pokud je velikost podpisu nadstandardní, půjde ovlivnit vhodným parametrem
Jak při použití vzorů při podepisování předat parametry k vyplnění do vzoru?
Při předávání údaj pro vzor jejsou v sekci parameters předány jednotlivé parametru vozru s tím, že “id” odpovídá id parametru ve vzoru.
BODY {
“number:”
... další standardní parametry dokumentů….
"parameters": [
{
"id": "12",
"value": "neurčito"
… další volitelné parametry pro daný vzor...}
"webhooks"
... další části volání
}
Část volání Endpointu “Vytvoření ze vzoru” v Signi API
<con-section con-id="12">:
Datum pohybu: <con-date con-id="1201" name="Datum pohybu" label="[Datum pohybu]" placeholder="Datum pohybu" description="Datum pohybu."></con-date>.<br>
Zakázka: <con-textarea con-id="1202" name="Zakázka" label="[Zakázka]" placeholder="Zakázka" description="Zakázka "></con-textarea><br>
Středisko:
<con-textarea con-id="1203" name="Středisko" label="[Středisko]" placeholder="Středisko" description="Středisko "></con-textarea>
</con-section>
Část kódu 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 a telefon, 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 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 universlání chybu 500, snažíme se jí 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.
Jak získat přístup ke stránkám pro podepsání?
Jsou dvě základní cesty :
Distanční podepsání - podepisujícím se po zavolání end pointu API odesílá emailová notifikace s odkazem na stránky pro podepsání. Pokud je uvedeno tel číslo, může odcházet i SMS notifikace. Je to obdoba standardního odeslání dokumentu k podpisu přes uživatelské rozhraní Signi.
Podpis na jednom zařízení - SIgni vrací URL pro podpis jednotlivých podepisujících viz Jak získám výsledek předání podkladů pro podpis a integrovaná aplikace zobrazí odpovídající odkazy, rámce apod. pro podpis jednotlivých osob. Pozor, pokud je podepisujících více, musí mít všechni svůj prostor k podpisu. Je to obdoba podpisu na jednom zařízení přes uživatelské rozhraní Signi.
Pozn: Nyní není v API přímo příznak pro to, zda se mají odesílat notifikace či nikoliv, pokud se má dít podpis na jednom zařízení, pří voání se u podepisujícího uvede jeden systémový e-mail. Podepisující se tak reálně ověřuje svým podpisem a případně PIem opsaným z ověřovací SMS zaslané při 2FA autorizaci.
Jak získat výsledky podepisování?
Vyvoláním zpětného webhooku
Součástí předávání podkladů pro podpis jsou i 3 URL adresy tzv. “webhooků” pro každou hodnotu výsledku:
podepsáno - signed,
odmítnuto - rejected,
neověřeno - expired.
URL adresy typicky obsahují volání integrované aplikace.
Zavolán je vždy jen jeden webhook z těchto tří podle výsledku. Pokud se parametr url ponechá prázdný, web hook se nevyvolá.
Ve vzoru volání na apiary.io je třeba text “your_webhook_url\” nahradit reálnou URL.
Nyní se volá webhook pro každý dokument zvlášť včetně příloh.
Při volání webhooku předáváme stejný API klíč jako byl použit pro volání Signi tj. zabezpečení je stejné jako směrem do Signi. Typ autorizace je tedy API Key, jako hodnota klíče x-api-key je uveden API klíč workspace, do kterého byl dokument k podpisu poslán, a hodnota se předává v Header.
Výsledný podepsaný dokument se do integrované aplikace při vyvolání webhooku předává následovně:
{
"contract_id": 3359,
"state": "completed",
"attachments": []
}
který je platný pouze 10 minut po vyvolání webhooku, později je při pokusu o stažení vrácena chyba.
Později lze stáhnout dokument přeshttps://api.signi.com/api/v1/contract/id/download
Soubor ve webhooku a end pointu download se předává ve formátu - Application/pdf .
PŘIPRAVUJEME: Volbu, kdy půjde pouze podepsat všechny dokumenty v jednom volání a zpět se bude volat pouze jeden webhook. Hodí se např. tehdy, pokud v integrovaném workflow systému je možné jedno větvení podmínek pro jeden případ, který ale zahrnuje více dokumentů.
Průběžným ověřováním stavu
Někdy lze webhooky v integrovaném systému obtížně implementovat.
Je možné se periodicky anebo např. při otevření detailu souvisejícího záznamu v integrovaném dokumentu dotazovat na aktuální stav dokumentu.
Při odeslání dokumentu k podpisu v odpovědi získáte identifikátor dokumentu Contract_id:
Response 200 HEADERS Content-Type:application/json BODY { "contract_id": "1234", "attachments": [] }
Stav příslušného dokumentu získáte přes End Point Detail smlouvy, tj. https://api.ismlouva.cz/api/v1/contract/id, kde id je Contract_id.
Jak se dostanu k polím definovaným v daném vzoru?
Vzor dokumentu je uložen v rozšířené verzi HTML.
Přístupný je na endpointu https://ismlouva3rdpartyservice1.docs.apiary.io/#reference/smlouvy/contract/contract-detail
Obsahuje pole pro nahrazení reálnými hodnotami (placeholder), typu CON_TEXT a další.
V jakém formátu se předávají soubory k podpisu i zpět?
Soubory k podpisu s předávají ve formátu - multipart/form-data
Soubor ve webhooku a end pointu download se předává ve formátu - Application/pdf
PŘIPRAVUJEME: Ve variantě End Pointů Full RestAPI budou binární soubory překódovány do textu.
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??
Vytváření hlavního dokumentu s několika přílohami
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.
PŘIPRAVUJEME: Výsledek podpisu každého z dokumentů se předává samostatným voláním příslušného webhooku. Volbu, kdy půjde pouze podepsat všechny dokumenty v jednom volání.
Je možné mít vlastní branding?
Vlastní branding se hodí :
v rámci prodejního procesu - kdy ukážeme zákazníkovi “jeho design” na prvcích komunikace = mailech a stránkách pro schválení dokumentů,
při skutečném nasazení.
Zatím nelze “naklikat”, lze zaslat požadavek.
Možnosti brandingu jsou popsány v Kroky podpisu dokumentu a možnosti brandingu - PUBLIC.
PŘIPRAVUJEME: Cílově půjde o jeden z úkonů, které mohou připravovat pro koncové zákazníky ve svém rozhraní a účtovat partneři.
Jak sladit vzory a volání API, aby se podpisy ukazovaly na správných místech ?
Pole pro podpisy ve vzorech je třeba mít přízpůsobené scénáři podepisování předávaném přes API. Pokud záleží na pořadí podepisujících, musí být vzory přízpůsobené i tomu. Dva základní scénáře jsou následující.
Pokud je scénář podepisování s navrhovatelem
"people": [ { "is_proposer": true, "email": "me@example.com", "contract_role": "approve" }, { "is_proposer": false, "party_order": 1, "email": "unregistered+1@example.com", "contract_role": "approve",
musí být pode pro podpisu ve vzoru
<tr> <td> <p> <con-sign con-id="16" party-type="proposer"></con-sign> </p> </td> <td> <p> <con-sign con-id="17" party-type="counterparty" party-order="1"></con-sign> </p> </td> </tr>
Pokud je scénář podepisování bez navrhovatele
"people": [ { "is_proposer": false, "party_order": 1, "email": "me@example.com", "contract_role": "approve" }, { "is_proposer": false, "party_order": 2, "email": "unregistered+1@example.com", "contract_role": "approve",
musí být pode pro podpisu ve vzoru
<tr> <td> <p> <con-sign con-id="16" party-type="counterparty" party-order="1"></con-sign> </p> </td> <td> <p> <con-sign con-id="17" party-type="counterparty" party-order="2"></con-sign> </p> </td> </tr>
Pokud záleží na pořadí podepisujících, je součástí volání endpointů v API i přepínač signing_order": "one_at_a_time", což odpovídá zaškrtnutí “Záleží na pořadí” v uživatelském rozhraní Signi. Při předávání podpisů přes API u jednotlivých osob / person odpovídá parametr “party_order” 1,2 3… pořadí podepisování a těmto číslům pak musí odpovídat příslušná umístění podpisů ve vzorech.
"settings": {
"signing_order": "one_at_a_time"
},
Proč není API Signi striktně RestAPI?
Signi je integrovaná s různě vyspělými aplikacemi.
Tomu odpovídá současná podoba API, kterou lze nazvat “Essential” a lze snadno použít jednoduše i při základním volání z jednoduchého webu na PHP či CURL utilitu přes HTTP.
PŘIPRAVUJEME: Paralelní verzi fundamentálně pojatého RestAPI, kde například binární soubory jsou překódované do textového řetězce.