Page Comparison

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 email 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, přiodávání lidí do týmu a podobně.

• Pod tímto účtem jsou také získatelné API klíče všech workspace používaných v organizaci viz Generování API klíče.

2. Workspace pro testování integrace

• Pří 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é aplikaci používá API klíč pro "svůj" workspace.  Pří přechodu z vývoje na test či produkci tedy stačí prohazovat API klíče.

• Workspace TEST a DEVELOPMENT jsou používány v režimu “DEMO”, kdy podepisování v nich by nemělo čerpat žádné kredity za podepsané dokumenty a API by mělo být zpřístupněné automaticky po založení workspace v DEMO režimu. Zatím tato funkce není v Signi k dispozici, dočasným řešením je napsat na help@signi.com žádosti “Chci DEMO workspace ”s uvedeným hlavním e-mailem a názvem workspace, které chcete v režimu DEMO používat.

3. Workspace pro agendy mimo integraci 

• Paralelně k tomu, může mít organizace více workspace pro používání Signi napřímo přes uživateslké rozhraní, kdy uživatelé vkládají dokumenty k podpisu přes uživatelské rozhraní Signi

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

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

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.

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

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 Vytvoření smlouvy / dokumentu 2.0 > Ze vzoru a “Jak při použití vzorů při podepisování předat parametry k vyplnění do vzoru?” níže.

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.

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ři propojování je dobré začít nejjednosušší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 email zakladatele pracovního prostoru / workspace v Signi, do kterého se přes API dokumenty posílají tj. typicky e-mail hlavního účtu na Signi pro firmu navrhovatele dokumentu. Dokument pouze schvaluje (contract_role=true) tj. není na dokumentu vifdět jeho podpis. Při volání přes API proběhne jeh schválení automaticky.

• Všichni podepisující či schvalující bez ohledu na to, zda jsou z firmy navrhovatele či nikoliv jsou označení  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 dokuentu podepsat. Nevýhodou pouze je, že fyzicky musí podepsat každy dokument.

 "people": [
      {
        "is_proposer": true,
        "email": "vlastnikworkspace@firma.cz",
        "contract_role": "approve"
        .....
      },
      {
        "is_proposer": false,
        "party_order": 2,
        "email": "podepisujicizanavrhovatele@firma.cz",
        "contract_role": "sign"
        ....
      }
      {
        "is_proposer": false,
        "party_order": 3,
        "email": "podepisujicizaprotistranu@jinafirma.cz",
        "contract_role": "sign"
        .... 
      }
    ],

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ě jako dokument, tak jeho kontrolní list.  Zároveň je třeba myslet na to, že název dokumentu se ukazuje podepisujícím v emailových a SMS notifikacích tj. není úplně vhodné posílat např. číslo samotné. Příklad “Č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 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řídat volbu, kdy webhook se bude volat jen jednou pro celou odeslanou sadu.

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 podepsat distančně či na jednom zařízení přes API?

Jsou dvě základní cesty :

• Distanční podepsání přes API - 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í přes API - V uživatelském rozhraní Signi je volba Podpis na jednom zařízení , kdy navrhovatel i protistrana/y jsou na jednm místě a podesují mna stejném počítači, tabletu či mobilu. Pří integraci s jinou aplikací toto lze zrealizovat jiným způspobem. SIgni pří předání dokumentů či podkladů pro vozr 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í stránky s těmito adresami pro podpis jednotlivých podepisujících , 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. Pokud se podepisuje více dokumentů najednou v sadě, pořád je vše pod jedním URL, jen vidí uživatel vlevém panelu několik záožek s jednotlivými dokumenty.

Dokumenty

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

• Může jít o PDF, DOC, DOCX, XLS, XLSX, HTML formáty, pozor, pře převodu některých variant těchto formátů může dojít k chybám při převodu např. příliš stará verze PDF formátu, příliš velký XLXS soubor a podobně.

• 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 doumenty. V případě využití vzorů Sigbi jsou pozice podpisů dány vzorem.

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

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

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 pramatery volání jednotlivých vzorů viz např níže. Sdílené vzory lze získat pomocí

{
    "templates": [
        {
            "id": 396,
            "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

• Vzor dokumentu je uložen v rozšířené verzi HTML. 

• Přístupný je na endpointu https://signi.docs.apiary.io/#reference/smlouva/smlouva/detail-smlouvy

• Obsahuje pole pro nahrazení reálnými hodnotami (placeholder), typu CON_TEXT a další.

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.

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

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

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. Více 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ří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 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": {
          <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>
           "signing_order": "one_at_a_time"
    },

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

• Vzor dokumentu je uložen v rozšířené verzi HTML. 

• Přístupný je na endpointu https://signi.docs.apiary.io/#reference/smlouva/smlouva/detail-smlouvy

• Obsahuje pole pro nahrazení reálnými hodnotami (placeholder), typu CON_TEXT a další.

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.

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: 
               <span class="col-1">| Číslo bytu: <con-textarea con-id="6161203" name="Číslo bytuStředisko" label="[DoplňteStředisko]" placeholder="Středisko" description="Uveďte číslo bytu" style="color:#004085 !important;Středisko "></con-textarea></span>textarea>

                
      </span>
  </con-section>

Část kódu vzoru

jak pří použití vzorů přes API skrývat a zobrazovat sekce ve vzoru ?

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

<con-part con-id="6" hideable=true>
        <div class="part1">
       </p>     <div>
           </con-section>     <h4>ADRESA PRE ZASIELANIE KOREŠPONDENCIE</h4>
    </div>         </div>   <con-section  </con-part>

Zobrazení nebo skrytí celé sekce lze řídit tak, že mezi parametry předávanými přes API přídá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.

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

Výsledky podepisování

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

Vyvoláním zpětného webhooku

• {

•   "contract_id": 3359,

•   "state": "completed",

•   "file": "https://api.test.ismlouva.cz/api/v1/contract/pdf/preview?hash=95d02b75275851c8851b3528a4b365fd7e03fa8991ed23b25e30d16c4558",

•   "attachments": []

• }

který je platný pouze 10 minut po vyvolání webhooku, později je při pokusu o stažení vrácena chyba.  

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áčnutí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.

Pokročilé funkce

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 se liší volání API, když uživatelé integrované aplikace ne/mají účet na Signi

Při integraci Signi umožňuje dva režimy účtů pracovníků organizace:

• 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

Image Removed

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

Ve scénáři A

• Pracovníci organizace nemusí mít účet v Signi, podepisují stejně jako protistrany.

• Nejjednodušší je využít jako navrhovatele dokumentu zakladatele pracovního prostoru/workspace, 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í podnímky).

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

{
    "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

• Pracovníci organizace musí mít účet v Signi a mohou si v účtu přednastavit svůj vlastní podpis a zároveň na pracovním prostoru/workspace povolit automatické podepisování navrhovatelem.

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

{
    "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"
      }
    ],

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 účtú 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 účtů B je třeba potom je třeba u všech uživatelů zadaný jejich email, kterým se přihlašují do Signi

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 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"
    },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řídá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.

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

Výsledky podepisování

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

  • {

  •   "contract_id": 3359,

  •   "state": "completed",

  •   "file": "https://api.test.ismlouva.cz/api/v1/contract/pdf/preview?hash=95d02b75275851c8851b3528a4b365fd7e03fa8991ed23b25e30d16c4558",

  •   "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 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 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. 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áčnutí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.

Pokročilé funkce

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 se liší volání API, když uživatelé integrované aplikace ne/mají účet na Signi

Při integraci Signi umožňuje dva režimy účtů pracovníků organizace:

• 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

Image Added

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

Ve scénáři A

• Pracovníci organizace nemusí mít účet v Signi, podepisují stejně jako protistrany.

• Nejjednodušší je využít jako navrhovatele dokumentu zakladatele pracovního prostoru/workspace, 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í podnímky).

• 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

• Pracovníci organizace musí mít účet v Signi a mohou si v účtu přednastavit svůj vlastní podpis a zároveň na pracovním prostoru/workspace povolit automatické podepisování navrhovatelem.

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

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
Souhlas vs. Podpis 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 s "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 účtú 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 účtů B je třeba potom je třeba u všech uživatelů zadaný jejich email, 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.