Versions Compared

Old Version 110

changes.mady.by.user Roman Řípa (Unlicensed)

Saved on

compared with

New Version 111

changes.mady.by.user Roman Řípa (Unlicensed)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

Než začneme

Co si má business rozmyslet před integrací?

Klíčové otázky jsou popsané v 7 otázek k rozmyšlení před integrací se Signi . Doporučujeme si je projít, člověk se pak vyhne nepříjemným překvapením typu “Aha a kde vezmeme e-mail jednatele zákazníka?” nebo “Aha a jak uživatel vlastně vybere, které dokumenty chce odesílat v jedné sadě?” v situaci, kdy už má integraci skoro odevzdat. Ač se zdá “podepsání dokumentu” triviální úloha, někdy získání všech podkladů, různé podpisové scénáře a reakce na výsledky podepisování zcela triviální nejsou.

Jak si nastavit prostředí Signi pro integraci?

1.Založit jediný hlavní účet na Signi, který je Vlastníkem všech workspace

  • Založení účtu na Signi - viz postup na Vytvoření účtu a první přihlášení do aplikace. Hlavní účet Signi doporučujeme založit pod e-mailem nikoliv konkrétního člověka, ale na e-mail typu info@firma.cz či signi@firma.cz s tím, že pošta zaslaná na tento e-mail musí být přístupná zřizovateli účtu. Ten musí potvrdit registrační e-mail zaslaný ze Signi.

  • Přes tento účet se následně řeší i veškeré objednávání a placení služeb Signi, zakládání workspace, nastavování jejich parametrů, přidávání lidí do týmu, generování API klíčů apod. pro vaši firmu.

2. Založit workspace pro testování integrace

  • Při založení účtu na Signi se automaticky vytvoří pracovní prostor - workspace pro zřizovatele účtu.

  • Pro integraci se pod hlavním účtem vytvoří typicky ještě další 2-3 workspace např. Agenda X - PRODUKCE / Agenda X - TEST / Agenda X - DEVELOPMENT, viz Vytvoření více workspace . Nemíchají se tak provozní data s vývojovými či testovacími.

  • Každý workspace má svůj API klíč, každé prostředí na straně integrované aplikace používá API klíč pro "svůj" workspace.  Při přechodu z vývoje na test či produkci tedy stačí prohazovat API klíče.

3. Zpřístupnění API a získání API klíčů

  • Pro vývojový / demonstrační workspace je přístup API zdarma, aktuálním řešením je napsat na help@signi.com žádost “Integrační balíček” s uvedeným hlavním e-mailem a názvem workspace, které chcete v tomto režimu používat. My vám přístup přes API povolíme.

  • Následně si pro workspace pod svým hlavním účtem vygenerujete API klíče svých workspace, viz Generování API klíče.

4. Využití workspace pro agendy mimo integraci 

  • Ve vaší organizaci můžete mít i workspace pro používání Signi napřímo přes uživatelské rozhraní, kdy uživatelé vkládají dokumenty k podpisu přes uživatelské rozhraní Signi.

  • Více viz Kombinace obou přístupů.

Info

Pokud se nastavováním nechcete probírat sami, rádi vás celým procesem provedeme v rámci zprovozňování Signi ve vaší firmě.

Osvědčilo se vám něco jiného? Narazili jste na situace, kdy vám toto uspořádání nevyhovuje? Dejte nám vědět.

Jaké jsou nejčastější chyby při volání Signi API

  1. Chybové kódy začínající 400 jsou specifické chyby Signi, kde z chybového hlášení má být zřejmé, co je příčinou a jak ji odstranit.

  2. “Invalid JSON” může znamenat , že je skutečně někde syntaktická chyba v JSON, což se vzhledem k jeho složitosti snadno stane. Pomoci mohou různé JSON validátory, např. https://jsonformatter.curiousconcept.com/. Další možností je, že soubor resp. řetězec není ve znakové sadě UTF-8 , ale ASCII , UNCODE a podobně.

  3. 400 - "Contract must have at least one proposer." - Musí být určeno, kdo bude autor dokumentu za navrhovatele. Hodnota parametru isProposer je v tomto případě true. Může to být e-mail vlastníka workspace, který dokument jen schvaluje tj. nepodepisuje, příčemž schválení proběhne při volání přes API automaticky. Více vic Příklad 2.

  4. Občas můžete narazit na univerzální chybu 500, snažíme se ji minimalizovat. Pomozte nám ji minimalizovat nahlášením situace na help@signi.com .

Předání podkladů k podepisování

Jak se předávají podklady k podepisování?

1. Předání souborů

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é jsou způsoby podepsání z integrované aplikace?

Jsou 3 základní cesty :

1. Distanční podepsání přes API

  • Po vyvolání podpisu v integrované aplikaci se po zavolání end pointu Signi API odešle e-mailová zpráva s odkazem na stránky pro podepsání. 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 přímo v integrované aplikaci přes API

  • 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 pod jedním URL, 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 k podepisování na tabletu/mobilu

  • 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".

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.

  1. 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í.

  2. 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.

  3. 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ří 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.

Lze se vyhnout tomu, aby zástupce navrhovatele musel podepisovat každý dokument?

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.

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í - PŘIPRAVUJEME - Osobě pouze odchází notifikační mail při uzavření / odmítnutí / expiraci.

  • approve - Schválit - Podepisující musí kliknout na tlačítko “Schválit”, ale jeho podpis nikde na dokumentu není vidět,

  • sign - Biometricky podpis - Podepisuje se obdobou vlastnoručního podpisu na listinném dokumentu, součástí podpisu mohou a nemusí být ciltivlé 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 sales@signi.com, 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 sales@signi.com . 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 .

Info

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ř. biomerický 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

Dokumenty

V jakých formátech se předávají soubory k podpisu?

  • V aktuální verzi lze přes API posílat v PDF, DOC, DOCX, XLS, XLSX, JPG, HTML .

  • V HTTP requestu se soubory k podpisu s předávají ve formátu - multipart/form-data.

PŘIPRAVUJEME:

  • Ve variantě End Pointů Full RestAPI budou binární soubory překódovány do textu.

Jak předávat informaci o umístění podpisů při předávání souborů?

Umísťování podpisů se řeší v případě, že posíláte k podpisu své dokumenty. V případě využití vzorů Signi jsou pozice podpisů dány vzorem.

Jaké jsou možnosti:

  1. Umístění podpisů na závěr dokumentu

  2. Umístění podpisu na zadanou stránku a souřadnice

  3. Umístění podpisů dle Pole pro umístění podpisů - Placehoder

1. Umístění podpisů na závěr dokumentu

Nejjednodušším způsobem, jak umístit podpisy do dokumentů, je, že Sifni přidá k výslednému PDF dokumentu samostatný list na závěr dokumentu a umístí tam všechny podpisy. Při 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" . Více také viz Příklad 2 - Umístění podpisů na závěr dokumentu.

Přiklad dynamického umístění podpisu

2. Umístění podpisu na zadanou stránku a souřadnice

Při volání endpointu Vytvoření smlouvy 2.0 > Z dokumentu lze i přesně určit, kde má být podpis umístěn v poli positions u každé osoby. Tím se pokryjí typicky formuláře, kde je místo k podpisu vždy stejné.

  • 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 podepisujícího a 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ářů.

  • Pří více záznamech v poli positions je naopak podpis jednoho podepisujícího vyžadován na více místech jednoho dokumentu. To se hodí např. v případech, kdy je v jednom PDF sloučeno více dokumentů a podepisující se má podepsat na několik z nich.

3. Umístění podpisů dle Pole pro umístění podpisů - Placeholder

Další možností jak určit umístění podpisů přímo v dokumentu je vložením tzv. polí pro umístění podpisů, v angličtině nazývaných např. placehoders, na vhodná místa v dokumentu. Logika je podobná jako u polí v šablonách pro hromadnou korespondenci, pouze se nenahrazují hodnoty typu [příjmení] ,ale nahrazují se podpisy konkrétních lidí . Více také v Příklad 2 - Použití C - Využití polí pro podpis / placeholdery.

V dokumentu k popisu

V dokumentu určeném k podpisu je třeba nejprve umístit pole pro umístění podpisu dle následujících pravidel:

  • Pole pro umístění jednotlivých podpisů označují texty např. “signi-signature-0” , “signi-signature-1”, “signi-signature-2”, “signi-signature-3” atd. pro první, druhý a další podpis. Číslování podpisů by mělo odpovídat pořadí podepisování dokumentu. Pole pro toho, kdo má podepsat první je “signi-signature-0” .

  • Při volání přes API , na rozdíl pro umísťování podpisů v uživatelském rozhraní, není nutné tuto jmennnou konvenci dodržovat. Názvy polí libovolná, jen je třeba následně stejné názvy použít ve volání Signi API. Jediné doporučení od vývoje Signi - nepoužívejte v názvech polí mezery, diakritiku, speciání znaky a místo podtržítek použivejte pomlčky.

  • Text s názvem odpovídá levému hornímu rohu finálního vloženého podpisu. Text s názvem je vhodné uvádět v dokumentu bíle. Text ve výsledném PDF sice zůstane, ale bude překryt podpisem.

  • Při umisťování podpisů se počítá s tím, že podpis je široký cca na  ⅓ stránky a vysoký je v poměru cca 16:9 . Pro umístění textů je tedy vhodné do dokumentu vložit  tabulku s 2 či 3 sloupci. I tabulku je následně třeba obarvit na bílo.

  • Nezáleží na typu podpisu. - Do pole pro umístění v dokumentu lze vložit jakýkoliv typu podpisu - biometrický, BankIS SIGN či podpis s certifikátem například kvalifikovaný podpis.

  • V dokumentu může být pole pro podpis umístěno na více místech dokumentu. - JEden podepsiující pak budepodepsán v dokumentu vícekrát.

  • V dokumentu může být více polí pro umístění podpisů než je v podpisovém scénáři. - Dokument pak může počítat s tím, že za jednotlivé strany podepisuje více podepisujících.

  • Pokud je třeba podpis zmenšit, je to nyní možné nastavit jako vlastnost workspace v Signi, ne pro jednotlivá volání Signi API. Kontaktujte pro nastavení help@signi.com .

V JSON

Následně v podpisovém scénáři v JSON ve volání API se příslušná pole pro umístění podpisu uvedou u konkrétních osob v poli positions v proměnné anchor tj. např. signi-signature-00 a signi-signature-02 , příklad celého volání viz Příklad 2 - Použití C - Využití polí pro podpis / placeholdery.

Code Block
{
            "is_proposer": false,
            "email": "zakaznik@seznam.cz",
            "contract_role": "sign",
            "person_type": "nature",
            "first_name": "John",
            "last_name": "Doe#2",
            "positions": [
              {
                "anchor": "signi-signature-02"
              } 
            ]
        }

Pole pro umístění podpisu - placeholder přířazené ke konkrétní osobě v JSON požadavku na Signi API

Vzory

Jak při použití vzorů zjistit, které parametry vzor má?

End point https://api.signi.com/api/v1/contract/templates vám vrátí všechny vzory přístupné pro workspace s API klíčem použitým pří volání, ve vráceném seznamu vzorů jsou ve formě JSON uvedeny parametry volání jednotlivých vzorů - viz např. níže.

Code Block
{
    "templates": [
        {
            "id": 396,
            "contract_name": "Pohybový doklad ",
            "parameters": [
                {
                    "id": "111",
                    "name": "Typ dokladu",
                    "type": "con-options",
                    "values": [
                        "Příjemka",
                        "Výdejka",
                        "Objednávka vydaná",
                        "Objednávka přijatá",
                        "Rezervace vydaná",
                        "Rezervace přijatá",
                        "Příjemka",
                        "Vratné obaly"
                    ]
                }
                ...
            ]
        }
    ]
}

Jak předávat informaci o umístění podpisů při použití vzorů?

Při 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.

Jeden podpis lze umístit ve vzoru vícekrát, v kódu vzoru se pouze uvede vícekrát pole pro dané pořadí podpisu. Podepisující se ale fyzicky musí podepisovat pouze jednou.

Více o zajištění návaznosti mezi volání API a kódu vzoru viz níže.

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řizpů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řizpůsobené i tomu. Dva základní scénáře jsou následující.

 

Pokud je scénář podepisování s podepisujícím navrhovatelem,

 "people": [
        {
            "is_proposer": true,
            "party_order": 1,
            "email": "me@example.com",
            "contract_role": "sign"
        },
        {
            "is_proposer": false,
            "party_order": 2,
            "email": "unregistered+1@example.com",
            "contract_role": "sign",

odpovídající pole pro podpisu ve vzoru jsou:

            <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="2"></con-sign>
                    </p>
                </td>
            </tr>


Pokud je scénář podepisování bez podepisujícího navrhovatele,

 "people": [
        {
            "is_proposer": true,
              "party_order": 1,
            "email": "zakladatelworkspace@firmanavrhovatele.cz",
            "contract_role": "approve"
        },
        {
            "is_proposer": false,
              "party_order": 2,
            "email": "me@example.com",
            "contract_role": "sign"
        },
        {
            "is_proposer": false,
            "party_order": 3,
            "email": "unregistered+1@example.com",
            "contract_role": "sign",

odpovídající pole pro podpisu ve vzoru jsou:

<tr>
                <td>
                    <p>
                          <con-sign con-id="16" party-type="counterparty" party-order="2"></con-sign>
                    </p>
                </td>
                <td>
                    <p>
                        <con-sign con-id="17" party-type="counterparty" party-order="3"></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.

Code Block
"settings": {
        "signing_order": "one_at_a_time"
    },

Jak si zobrazím celý kód vzoru vzoru?

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 se využije endpoint Vytvoření smlouvy / dokumentu 2.0 > Ze vzoru. V sekci Parameters jsou předány jednotlivé parametru vzoru s tím, že “id” odpovídá id parametru ve vzoru.

Code Block
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

Code Block
    <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 při použití vzorů přes API skrývat a zobrazovat sekce ve vzoru ?

Ve vzorech lze definovat sekce, jejichž zobrazení lze následně přes API zapínat a vypínat. Ve vzoru k tomu slouží položka con-part .

Code Block
<con-part con-id="6" hideable=true>
        <div class="part1">
            <div>
                <h4>ADRESA PRE ZASIELANIE KOREŠPONDENCIE</h4>
                <con-section con-id="61">
                            <span class="col-2">Ulica: <con-textarea con-id="611" name="Ulica" label="[Doplňte]" placeholder="" description="Uveďte ulicu" style="color:#004085 !important;"></con-textarea></span>
                            <span class="col-1">| Súpisné číslo: <con-textarea con-id="612" name="Súpisné číslo" label="[Doplňte]" placeholder="" description="Uveďte súpisné číslo" style="color:#004085 !important;"></con-textarea></span>
                            <span class="col-1">| Orientačné č.: <con-textarea con-id="613" name="Orientačné číslo" label="[Doplňte]" placeholder="" description="Uveďte orientačné číslo" style="color:#004085 !important;"></con-textarea></span>
                            <span class="col-2">Obec: <con-textarea con-id="614" name="Obec" label="[Doplňte]" placeholder="" description="Uveďte obec" style="color:#004085 !important;"></con-textarea></span>
                            <span class="col-1">| PSČ: <con-textarea con-id="615" name="PSČ" label="[Doplňte]" placeholder="" description="Uveďte PSČ" style="color:#004085 !important;"></con-textarea></span>
                            <span class="col-1">| Číslo bytu: <con-textarea con-id="616" name="Číslo bytu" label="[Doplňte]" placeholder="" description="Uveďte číslo bytu" style="color:#004085 !important;"></con-textarea></span>
                        </span>
                    </p>
                </con-section>
            </div>
        </div>
    </con-part>

Zobrazení nebo skrytí celé sekce lze řídit tak, že mezi parametry předávanými přes API přidáme i ID parametru odpovídající sekci con-part, kdy hodnota je buď hide, či show.

Kód v JSON souboru pro vytvoření dokumentu ze vzoru pak v poli parameters obsahuje následující pro případ, že sekce con-part=2 má být skryta.

Code Block
....
"parameters": [
{
"id": "2",
"value": "hide"
},
...
Info

Pozor! Identifikátory sekcí con-part se NEukazují v seznamu parametrů vzoru - viz Jak při použití vzorů zjistit, které parametry vzor má? Jedna z možností, jak je zjistit, je stáhnout si celý kód vzoru pomocí Jak si zobrazím celý kód vzoru vzoru? a tam si příslušné identifikátory sekcí con-part najít.

Výsledky podepisování

Jak získat výsledky podepisování? 

1. 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í viz např. úvodní část JSON:

Code Block
{
    "contract_name": "Dokument s webhooky",
    "number": "000001",
    "state": "pending",
    "locale": "cs",
    "settings": {
        "signing_order": "proposers_before_counterparties"
    },
    "webhooks": [
        {
            "state": "completed",
            "url": "http://example.com/?source=signi&constract_id=1234&state=completed"
        },
        {
            "state": "rejected",
            "url": "http://example.com/?source=signi&constract_id=1234&state=rejected"
        },
        {
            "state": "expired",
            "url": "http://example.com/?source=signi&constract_id=1234&state=expired"
        }        
    ],
    ....
    další části JSON
}

  • 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ý dokumentse do integrované aplikace při vyvolání webhooku předává následovně:

    Code Block
    {
    
  "contract_id": 3359,
    
  "state": "completed",
    
  "file": "https://api.
    test
    signi.
    ismlouva.cz
    com/api/v1/contract/pdf/preview?hash=95d02b75275851c8851b3528a4b365fd7e03fa8991ed23b25e30d16c4558",
    
  "attachments": []
    
}
který

  • Odkaz na dokument 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 dokumentpř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 je v integrovaném workflow systému možné jedno větvení podmínek pro jeden případ, který ale zahrnuje více dokumentů.

2. Průběžným ověřováním stavu

  • Někdy lze webhooky v integrovaném systému obtížně implementovat. Nebo není z bezpečnostních důvodů vystavit přístup do systému z internetu.

  • Při odeslání dokumentu k podpisu v odpovědi získáte identifikátor dokumentu v Signi Contract_id, viz např. 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. S ním pak můžete volat např. end pointy: Stav dokumentu Stažení dokumentu Stažení auditní stopy / kontrolního listu dokumentu.

  • End pointy se volají ve vhodný okamžik, buď přes nějaký časovač/cron pravidelně, při otevírání formuláře, zmáčknutím tlačítka “Aktualizace stavu” apod.

V jakém formátu se předávají výsledné dokumenty?

  • 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.

Vzdálená identifikace

Vyvolání vzdálené identifikace - JEN K TESTOVÁNI

Vzdálená identifikace umožňuje ověřit identitu člověka pokročilými metadami buď přes Signi identifikaci nebo BankID identifikaci. Vyvolání vzdálené identifikace se děje ve 3 krocích:

  1. Založení dokumentu ze souboru či vzoru ve stavu draft,

  2. Získání Signi ID jednotlivých osob v rámci workspace,

  3. Vyvolání požadavku na identifikaci a podpis.

Vyvolání požadavku na identifikaci a podpis funguje přitom následovně:

  • Pokud daná osoba ještě nebyla nikdy identifikována v rámci workspace, odešle se jí výzva k identifikaci, ona poskytne potřebné podklady poskytne a pak pracovník navrhovatele identifikaci schválí a potvrdí odeslání výzvy k podpisu dokumentu/ů.

  • Pokud daná osoba již někdy identifikována byla v rámci workspace, odchází jí při vyvolání rovnou výzva k podpisu dokumentu/ů.

Konkrétní příklad kódu viz Příklad 6 - Vyvolání vzdálené identifikace.

Pokročilé

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 a účtovat pro koncové zákazníky ve svém rozhraní partneři.

Jaké jsou možnosti podepisování zástupců organizace použivající Signi?

Při integraci Signi umožňuje několik variant podepisování pracovníků organizace používající Signi, typicky statutáře, zplnomocněné obchodníky apod. :

  • A - Pracovníci organizace v Signi nemají účet, pouze přes něj podepisují stejně jako protistrany.

  • B - Pracovníci organizace v Signi mají účet, mohou se jejich podpisy vkládat automaticky.

  • C - Podpis pracovníka organizace je již vložen např. v grafické podobě do dokumentu vkládaného do Signi, Signi zajišťuje jen podpis protistran.

Klíčovým faktem přitom je, že každý dokument v Signi musí mít svého jednoznačného autora dokumentu.

Ve scénáři A

Výhodou scénáře je jednoduchost na zprovoznění. Nevýhodou je, že podepisující pracovníci organizace, typicky statutáři, musí podepsat či schválit každý jednotlivý dokument.

  • Pracovníci organizace nemusí mít účet v Signi, podepisují stejně jako protistrany - dostanou e-mail s výzvou k podpisu, otevřou si z něho stránku podpisu a dokument podepíší či schválí.

  • Pří integraci lze jako navrhovatele/autora dokumentu uvést e-mail zakladatele pracovního prostoru / workspace na Signi, kam se dokument odesílá, a říci, že on dokument bude pouze (přes API automaticky) schvalovat.

  • Pracovníci organizace i protistrany mohou dokumenty podepisovat (smlouvy) nebo pouze schvalovat (např. Všeobecné obchodní podmínky).

  • Scénář podepisování předaný přes API pak bude obsahovat například toto:

Code Block
{
    "settings": {
      "signing_order": one_at_a_time",
    }
    {
    "people": [
      {
        "is_proposer": true,
        "email": "zakladatelworkspace@firmanavrhujicidokument.cz",
        "contract_role": "approve"
      },
      {
        "is_proposer": false,
        "party_order": 1,
        "email": "podepisujiciobchodnik@firmanavrhujicidokument.cz",
        "contract_role": "sign"
      },
      {
        "is_proposer": false,
        "party_order": 2,
        "email": "podepisujícizakazník@firmaprotistrana.cz",
        "contract_role": "sign"
      }
    ],

Ve scénáři B

Pokud pracovníci organizace:

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 podepisujiciobchodnik@firmanavrhujicidokument.cz :

Code Block
{
    "settings": {
      "signing_order": "one_at_a_time",
      "autosign_proposers": "V Praze"
    },
    "people": [
      {
        "is_proposer": true,
        "email": "podepisujiciobchodnik@firmanavrhujicidokument.cz",
        "contract_role": "sign"
      },
      {
        "is_proposer": false,
        "party_order": 1,
        "email": "podepisujícizakazník@firmaprotistrana.cz",
        "contract_role": "sign"
      }
    ],
Info

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.

Ve scénáři C

Z hlediska EU direktivy eIDAS lze za elektronický podpis na úrovni prostý považovat i podpis v grafické podobě vložený do dokumentu. Je to obdoba situace, kdy v dopisu z banky je umístěn podpis odpovědného manažera banky, nepředpokládá se, že by se pracovník podepisoval na tisíce dokumentů.

Má smysl v případech, kdy je nízké riziko sporu resp. toho, že protistrana bude rozporovat podpis navrhovatele.

V tom případě podepisuje jen protistrana, zástupce navrhovatele, kterým je zakladatel workspace dokument automaticky schválí.

Code Block
{
    "settings": {
      "signing_order": one_at_a_time",
    }
    {
    "people": [
      {
        "is_proposer": true,
        "email": "zakladatelworkspace@firmanavrhujicidokument.cz",
        "contract_role": "approve"
      },
      {
        "is_proposer": false,
        "party_order": 2,
        "email": "podepisujícizakazník@firmaprotistrana.cz",
        "contract_role": "sign"
      }
    ],

Info

Volba  "contract_role = sign / approve"  říká, zda bude fyzicky nějaký podpis na dokumentu, či zda ho má nějaký člověk pouze schválit. 

  • Pokud má být vidět někde na dokumentu podpis, například na smlouvě, volá se se "sign".

  • Pokud má někdo dokument jen odsouhlasit, například Všeobecné podmínky, volá se s "approve".

Jak je zachycena vazba uživatel integrované aplikace a workspace a uživatel v Signi

Vazba uživatelé integrované aplikace - Signi workspace

  • Workspace v Signi slouží pro ukládání dokumentů, do jeho týmu může být přiřazeno více lidí. Více lidí naopak může mít přístup do více workspace.

  • Při volání Signi API se pro autentizaci používá API klíč, tj. jasně se určuje, do kterého workspace bude dokument uložen. Více viz Generování API klíče.

  • Pokud jsou ve vaší aplikaci evidováni: 

    • a) pouze uživatelé - musí být u každého uživatele uveden API klíč. 

    • b) také firmy či pobočky uživatelů - k nimž jsou pak přiřazení jednotliví uživatelé ukládající dokumenty v jednom workspace v Signi, může být Signi API klíč uveden u firmy či pobočky a využívat se při volání všech "jejích" uživatelů 

Vazba uživatelé integrované aplikace - Signi uživatelé

  • V režimu účtu A viz výše, je to jednodušší. Stačí mít 

    • u všech uživatelů zadaný e-mail hlavního účtu zákazníka v Signi,

    • u firmy/pobočky zadaný  e-mail hlavního účtu zákazníka v Signi.

  • V režimu účtu B je třeba u všech uživatelů zadaný jejich e-mail, kterým se přihlašují do Signi

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.

Jak testovat chování Signi pro neregistrované uživatele?

Signi se chová odlišně pro ty, kteří jsou a nejsou zaregistrovaní v Signi. U prvních Signi pro podepsání dokumentu vyžaduje jejich přihlášení do Signi. Jim doručené dokumenty k podpisu mají pak přístupné v jejich privátním workspace. Druhým se nabízí anonymní unikátní stránky pro identifikaci a podpisy.

Pro testování Signi pro neregistrované uživatele je vhodné následující:

použití emailů:

  • Pokud používáte emailové účty na Google, lze využít jejich funkci, kdy do schránky neco@firmanagoogle.cz přijdou i emaily odeslané na neco+cokoliv@firmanagoogle.cz . Pokud odešlete k podpisu dokument na v Signi neregistrovaného podepisujícího jarda.ripa+test@signi.com , dojdou notifikační emaily do vaší existující schránky jarda.ripa@signi.com , pod kteroužto adresou je účet v Signi vytvořen.

  • V jiných případech má smysl založil firemní e-mailovou skupinu neregistrovanivsigni@firma.cz , zařadit do ní všechny testovače Signi a používat tento email jako adresu podepisujícího neregistrovaného v Signi.

vyvolání odkazů pro podepisování protistran:

  • Pokud jste v www prohlížeči příhlášeni do Signi jako navrhovatelé, je třeba odkazy pro podpisy otevírat v anonymním okně, protože Signi jinak předpokládá, že dokument chcete podepisovat jako navrhovatel tj. odkaz pro protistranu je vám nepřístupný. Projeví se to zobrazením chyby neplatný link.

  • Tip: Pro testování podpisů protistran je možné si testování zkrátit tím, .že nečekáme na došlý email, ale využijeme odkaz přístupný v detailu dokumentu, který si zkopírujeme ikonou kopírování.