Příklady volání Signi API

Pro příklady volání používáme Postman a curl. Pokud nejste ani v jednom zběhlí, nevadí. Navštivte náš úvod do API světa. Příklady volání v různých jazycích vám pak nabídne podrobná dokumentace end pointů, logika volání end pointů bude stejná.

Při osahávání API doporučujeme začít prvním příkladem, kde se nepředává soubor. Teprve až vše rozchodíte , vrhněte se na druhý příklad. Nejprve řešte jen předání souboru k podpisu. Až když vyvoláte odeslání e-mailů s výzvou k podpisu, doplňte webhooky pro zpětné informování do vaší aplikace.

1 Příklad 1 - Získání informací o zakladateli workspace
2 Příklad 2 - Předání PDF dokumentu k podpisu
3 Příklad 3 - Předání podkladů pro vzor
4 Příklad 4 - Získání informací o dokumentu
5 Příklad 5 - Získání informací o stavu podepisování jednotlivými podepisujícími
6 Příklad 6 - Podpis v integrované aplikaci
7 Příklad 7 - Vyvolání vzdálené identifikace

Příklad 1 - Získání informací o zakladateli workspace

Na produkčním prostředí Signi https://api.signi.com je workspace "Demo API" a má API klíč = “71c4123d242bdd38047bee838d17e3367dc3ea6748d0975217ce501e834a224c83cab8afd35c9b0e6ade806b7987fae80f97f5c8253cfbb9089cf21f” , při svých voláních zaměňte tento API klíč za API klíč svého workspace, který získáte po objednání služby "Integrace API" a Generování API klíče.
Pro získání informací o uživatele zakládajícím workspace, kam se budou dokumentu posílat se využije end point Autorizace > Detail uživatele.

Popis v dokumentaci

Popis enpointu Autorizace > Detail uživatele

Volání v Postmanovi

Požadavek je typu GET .
Adresa je https://api.signi.com/api/v1/me .
Na záložce Autorization je jako typ autorizace zvolen jako typ autorizace API Key a jako hodnota klíče x-api-key je uveden API klíč workspace a umístění API klíče je zvoleno Header.

Volání end point Detail Uživatele - User Detail v Postmanovi

Výsledek volání

{
    "user": {
        "email": "aplikace@signi.com"
    },
    "workspace": {
        "name": "iSmlouva marketing"
    },
    "token": {
        "expiration_date": "2030-08-07"
    },
    "links": {
        "tokens": "https://app.ismlouva.cz/api"
    }
}

Příklad 2 - Předání PDF dokumentu k podpisu

A - Umístění podpisů na závěr dokumentu

Na produkčním prostředí Signi https://api.signi.com je workspace "Demo API" a má API klíč = “71c4123d242bdd38047bee838d17e3367dc3ea6748d0975217ce501e834a224c83cab8afd35c9b0e6ade806b7987fae80f97f5c8253cfbb9089cf21f” , při svých voláních zaměňte tento API klíč za API klíč svého workspace, který získáte po objednání služby "Integrace API" a Generování API klíče.
Pro předání PDF dokumentu k podpisu se využije end point Vytvoření smlouvy 2.0 > Z dokumentu.
V tomto scénáři podepisuje zástupce navrhovatele dokumentu a protistrana. Zakladatelem workspace s právem navrhovat, schvalovat i podepisovat je účet demo@signi.com . Proto je tento účet ve voláních použit jako zástupce navrhovatele. Kontaktní údaje protistrany tj. v příkladu protistrana@firma.cz změňte pří testování na svůj e-mail, finálně pak vyplňujte e-mail reálné podepisující protistrany.

V příkladu:

se předepíše umístění podpisů na závěr dokumentu,
zároveň je předepsáno místo, v němž podepisuje zástupce navrhovatele. Pokud by místo “V Praze” bylo uvedeno “true”, přebíral by se údaj v nastavení workspace,
v tomto případě podepisují všichni najednou, alternativně lze zvolit, že podepisují nejprve zástupci navrhovatele a až pak protistran, anebo že “záleží na pořadí” tj. podepisují se v pořadí, které je určeno ve volání,
protistrana podepisuje viz contract_role: sign, mohla by dokument i pouze schvalovat, pak by na dokumentu nebyl vidět podpis,
pokud by podepisujících bylo uvedeno i telefonní číslo, přijde jim i notifikační SMS a zároveň svůj telefon již nebudou muset zadávat pro zaslání ověřovacího PIN kódu.

Pokud má podepisovat za navrhovatele reálný zástupce navrhovatele, uživatel s daným e-mailem musí mít v tomto případě povolen přístup do daného workspace v Signi a měl tam nastaveno právo podepisovat. Jinak volání přes API neprojde. Alternativně zástupci uživatelé nejsou uživateli Signi a podepisují obdobně jako protistrany. V tom případně se po nich nich nechce přihlášení do Signi.
Pokud by zástupce navrhovatele dokument nepodepisoval, není ve volání API uveden.
V uživatelském rozhraní Signi při vytvoření dokumentu přes API je jako autor dokumentu vždy zakladatel workspace.

Popis v dokumentaci

Popis endpointu Vytvoření smlouvy 2.0 > Z dokumentu

Volání v Postmanovi

Požadavek je typu POST .
Adresa je https://api.signi.com/api/v1/contract/ , na záložce Param je zadán parametr Type s hodnotou ”doc” tj. výsledná adresa je volání je https://api.signi.com/api/v1/contract/?type=doc .
Na záložce Autorization je jako typ autorizace zvolen jako typ autorizace API Key a jako hodnota klíče x-api-key je uveden API klíč workspace a umístění API klíče je zvoleno Header.
Na záložce Body je jako typ volání zvoleno multipart/form-data a jsou uvedeny dva klíče - data a uploaded_file_key. Pozor, oba dva jsou typu file , aby se do HTTP požadavku opravdu fyzicky přenesli soubory. V prvním je JSON s parametry volání endpointu, v druhém je soubor k podpisu - PDF anebo DOC, DOCX, XLS, XLSX, HTML. U každého klíče je třeba zvolit typ parametru je File, Klepnutím na “Select Files” se otevře výběr souboru, vložíte příslušný.

Záložka Param

Záložka Autorization

Záložka Body

Klíče na záložce Body jsou typu “File”, soubor k zaslání v požadavku se vybere z vašeho disku a nahraje přes “Select Files”.

JSON soubor s parametry volání

JSON soubory ke stažení

{
    "name": "irrelevant",
    "number": "irrelevant",
    "locale": "cs",
    "settings": {
        "signing_order": "all_at_once",
        "autosign_proposers": "V Praze",
        "missing_positions": "append_to_the_end"
    },
    "people": [
        {
            "is_proposer": true,
            "email": "aplikace@signi.com",
            "first_name": "Johny",
            "last_name": "Doe#1",
            "contract_role": "sign"
        },
        {
            "is_proposer": false,
            "email": "roman.ripa+20210341@signi.com",
            "contract_role": "sign",
            "person_type": "nature",
            "first_name": "John",
            "last_name": "Doe#2"
        }
    ],
    "file": "uploaded_file_key"
}

Ano, víme, takové předávání parametrů není čisté REST API, v dalších verzích API vylepšíme.

Výsledek volání

Výsledkem je odeslání notifikačního e-mailu na adresu protistrany. V End point vrací v contract_id jednoznačnou identifikaci dokumentu , kterou lze využít pro další získávání informací o dokumentu a jeho stavu.

Výsledek volání endpointu

Co se děje po volání

Povolání v tomto případě přijde notifikační email pouze zástupci protistrany. Po podepsání všichni zúčastnění obdrží e-mail s podepsaným dokumentem a buď se vyvolá webhook zadaný pří volání endpointu, anebo lze zjišťovat stav dokumentu opakovaným voláním příslušných end pointů.

Výsledný podepsaný dokument

Výsledný dokument může vypadat například takto:

B - Několik dokumentů podepisovaných najednou

Pokud potřebujete poslat několik dokumentů k podpisu najednou, kdy třeba některé dokumenty se podepsují a jiné jen schvalují . např. VOP, je to možné přes sekci Attafements” ve volání Signi API.

Volání v Postmanovi

Více souborů předáno v body při volání end pointu

JSON s podpisovým scénářem

JSON soubory ke stažení

{
    "contract_name": "document name - nonmandatory",
    "number": "document number - nonmandatory",
    "locale": "cs",
    "settings": {
        "signing_order": "all_at_once",
        "missing_positions": "error"
    },
    "people": [
        {
            "is_proposer": true,
            "email": "demo@signi.com",
            "contract_role": "approve"
        },
        {
            "is_proposer": false,
            "email": "demo+zakaznik@signi.com",
            "contract_role": "sign",
            "person_type": "nature",
            "first_name": "John",
            "last_name": "Doe#2",
            "positions": [
              {
               "x": 50,
               "y": 50,
               "page": 0
              } 
            ]
        }
    ],
    "file": "uploaded_file_key",
    "attachments": [
        {
            "people": [
                {
                "is_proposer": true,
                "email": "demo@signi.com",
                "contract_role": "approve"    
                },
                {
                    "is_proposer": false,
                    "email": "demo+zakaznik@signi.com",
                    "contract_role": "approve",
                    "person_type": "nature",
                    "first_name": "John",
                    "last_name": "Doe#2"
                }
                
            ],
            "file": "uploaded_file_key2"
        }
    ]
}

Předání druhého dokumentu v JSON, druhý má klíč uploaded_file_key2

Více dokumentů v jedné sadě pří podepisování

C - Využití polí pro podpis / placeholdery

V DOCX dokumentu je na závěr umístěná tabulka se sloupci pro jednotlivé podepisující strany s tloušťkou čar 0px, aby nebyla tabulka v dokumentu a zacentrováním na střed sloupce.
U každé strany se předpokládá jeden nebo dva podepisující, proto jsou v dokumentu placeholdery signi-signature-0 až signi-signature-3.
Názvy polí pro podpis/placeholdery jsou vloženy bíle, aby nebyly ve finálním dokumentu vidět.
Scénář podepisování níže pro jednoduchost předpokládá, že navrhovatel jen schvaluje a jeden zástupce protistrany podepisuje. Proto je v JSON pouze jedna osoba s polem pro podpis signi_signature_02. Výsledný dokument s jedním podpisem je v příkladu níže. Obdobně je možné k dokumentu poslat v JSON scénář s dvěma, třemi či čtyřmi podepisujícími.
Příkladový DOCX Soubor s polemi pro podpis.

Pozor, zatím Signi v poli pro podpis zobrazí samotný podpis, místo a datum podpisu podepisujícího. Nezobrazuje jméno, funkci, roli či firmu konkrétního podepisujícího. Pokud je to třeba, tyto údaje musí být uvedeny nad či pod polem pro podpis. V cílovém stavu půjde v poli pro podpis zobrazit tyto údaje tj. v dokumentu bude moci být v záhlaví uvedeny jako smluvní strany pouze právnické osoby bez jejich konkrétních zástupců, ti se doplní až při podepisování dokumentu.

Dokument s poli pro podpis

JSON s podpisovým scénářem

JSON soubory ke stažení

Výsledný dokument

D - Podpisy s certifikáty, kvalifikovanými podpisy

Využívá workspace DEMO API s jeho API klíčem a uživateli s právem podpisu viz výše.
Využívá umístění podpisů dle polí pro umístění podpisu viz Příkladový soubor s placeholdery ke stažení.

JSON pro podpisový scénář - Navrhovatel i protistrana podepisuje kvalifikovaně

JSON pro podpisový scénář - Navrhovatel automaticky schvaluje a protistrana podepisuje kvalifikovaně

Příklad 3 - Předání podkladů pro vzor

A - Předání běžných hodnot - text, číslo, datum

Na produkčním prostředí Signi https://api.signi.com je workspace "Demo API" a má API klíč = “71c4123d242bdd38047bee838d17e3367dc3ea6748d0975217ce501e834a224c83cab8afd35c9b0e6ade806b7987fae80f97f5c8253cfbb9089cf21f” , Při svých voláních zaměňte tento API klíč za API klíč svého workspace, který získáte po objednání služby "Integrace API" a Generování API klíče.
Pro předání údajů pro vzor dokumentu v Signi se využije end point Vytvoření smlouvy 2.0 > Ze vzoru.
Za navrhovatele automaticky podepisuje účet demo@signi.com , tvůrce workspace.. Z protistranu v příkladu podepisuje protistrana@firma.cz , změňte při testování na svůj e-mail. Je nastaveno pořadí podepisování proposers_before_counterparties to jest, nejdříve se vloží podpis navrhovatele a pak odchází výzva k podpisu protistraně.
Volá se vzor Testovací smlouva s ID vzoru 7v1 s několika parametry, jejichž ID jsou 112, 131, 411, 421, 431 . Parametry jiných vzorů snadno zjistíte, viz Jak při použití vzorů zjistit, které parametry vzor má?

Popis v dokumentaci

Vytvoření smlouvy 2.0 > Ze vzoru

Volání v Postmanovi

Požadavek je typu POST .
Adresa je https://api.signi.com/api/v1/contract/ , na záložce Param je zadán parametr Type s hodnotou ”template” tj. výsledná adresa je volání je https://api.signi.com/api/v1/contract/?type=template .
Na záložce Autorization je jako typ autorizace zvolen jako typ autorizace API Key a jako hodnota klíče x-api-key je uveden API klíč workspace a umístění API klíče je zvoleno Header.
Na záložce Body je jako typ volání zvoleno multipart/form-data a je uveden jeden klíč - data se souborem JSON , v kterém jsou parametry volání endpointu

Klíče na záložce Body jsou typu “File”,
soubor k zaslání v požadavku se vybere z vašeho disku a nahraje přes “Select Files”.

JSON soubor s podpisovým scénářem

JSON soubory ke stažení

Výsledný dokument zaslaný k podpisu

Uživateli s e-mailem protistrana@firma.cz je zaslána výzva k podpisu dokumentu.

B - Předávání hodnoty z výčtu hodnot

Parametr 221 typu výběr variant (ve vzoru <con-options>) má dvě možné hodnoty (ve vzoru <con-option... label="..."...>) : “Příjemce není osobou povinnou ke zveřejnění smlouvy v registru smluv nebo výše plnění nedosahuje zákonného limitu pro zveřejnění v registru” a “Příjemce je osobou povinnou ke zveřejnění smlouvy v registru smluv a výše plnění dosahuje zákonného limitu pro zveřejnění v registru”
Pří předávání parametru 221 se pak předává název konkrétní hodnoty z výčtu hodnot.

Příklad kódu vzoru

Příklad předání volby v JSON

C - Zobrazování a schovávání částí obsahu vzoru

Typicky ve znění smluv jsou situace, kdy při třeba celý oddíl je třebe ve smlouvě uvést a někdy zase vynechat.
Takové části dokumentu jsou uvedeny do samostatného obsahového bloku ( ve vzoru <con-part> , která má vlastnost hidable).
Pří volání API je třeba v přílusšném parametru uvést textovou hodnotou show či hide.

Příklad kódu vzoru

Příklad předání volby v JSON

Příklad 4 - Získání informací o dokumentu

Na produkčním prostředí Signi https://api.signi.com je workspace "Demo API" a má API klíč = “71c4123d242bdd38047bee838d17e3367dc3ea6748d0975217ce501e834a224c83cab8afd35c9b0e6ade806b7987fae80f97f5c8253cfbb9089cf21f” , při svých voláních zaměňte tento API klíč za API klíč svého workspac, který získáte po objednání služby "Integrace API" a Generování API klíče.
V demo workspace Demo API je i uzavřený dokument s contract_id=83166 .

Popis v dokumentaci

Popis enpointu Smlouva > Detail smlouvy

Volání v Postmanovi

Požadavek je typu GET .
Adresa je https://api.signi.com/api/v1/contract/83166 .
Na záložce Autorization je jako typ autorizace zvolen jako typ autorizace API Key a jako hodnota klíče x-api-key je uveden API klíč workspace a umístění API klíče je zvoleno Header.

Výsledný dokument v Signi

Výsledek volání

Příklad 5 - Získání informací o stavu podepisování jednotlivými podepisujícími

Na produkčním prostředí Signi https://api.signi.com je workspace "Demo API" a má API klíč = “71c4123d242bdd38047bee838d17e3367dc3ea6748d0975217ce501e834a224c83cab8afd35c9b0e6ade806b7987fae80f97f5c8253cfbb9089cf21f” , při svých voláních zaměňte tento API klíč za API klíč svého workspac, který získáte po objednání služby "Integrace API" a Generování API klíče.
V demo workspace Demo API je i uzavřený dokument s contract_id=83166 .

Popis v dokumentaci

Popis enpointu Smlouva > Smlouva > Seznam smluv pro daného podepisovatele

Volání v Postmanovi

Požadavek je typu GET .
Adresa je https://api.signi.com/api/v2/contract/83166/signIdentities/list .
Na záložce Autorization je jako typ autorizace zvolen jako typ autorizace API Key a jako hodnota klíče x-api-key je uveden API klíč workspace a umístění API klíče je zvoleno Header.

Dokument v Signi

Výsledek volání

Příklad 6 - Podpis v integrované aplikaci

Jednou z možností jak propojit Signi s vaší aplikací je vyvolání stránky podpisu přímo z integrované aplikace viz Předání podkladů > Podpis v integrované aplikaci .
Jde o obdobu Podpis na jednom zařízení přes uživatelském rozhraní Signi.
Signi jako odpověd na požadavek na podepsání vrací URL stránky/nek pro podpis dokumentu, kterou/é může přímo uživateli zobrazit.
Pokud jsou stránky pro podepisování obrandované dle integrované aplikace viz funkce Signi Vlastní branding , nemusí uživatel vůbec poznat, že někde v pozadí je použito Signi. Jednoduše ve “své” aplikaci podepíše dokument.
Pokud se zároveň při volání Signi API použije příznak "one_device":true:
- Signi neodešle podepisujícím výzvy k podpisu emailem a SMS tj. nemohou je podepsat vzdáleně,
- Signi jim zašle až výsledný podepsaný dokument.
- v Kontrolním listě bude záznam o tom, že proběhl “podpis na jednom zařízení” tj. nedoručoval se podepsaný dokument na dálku. To například splňuje legislativní požadavek na předání podepsaného pracovněprávního dokumentu přímo na pracovišti viz Elektronické podepisování v HR s využitím Signi.

JSON soubor s podpisovým scénářem

Odpověď na požadavek

URL stránek k podpisu k zobrazení v integrované aplikaci vrací enpointy pro vtvoření dokumentu ze souborů či z údajů pro vzor a v odpovědi (http response) vypadá následovně.

Příklad 7 - Vyvolání vzdálené identifikace

Na produkčním prostředí Signi https://api.signi.com je workspace "Demo API" a má API klíč = “71c4123d242bdd38047bee838d17e3367dc3ea6748d0975217ce501e834a224c83cab8afd35c9b0e6ade806b7987fae80f97f5c8253cfbb9089cf21f” , při svých voláních zaměňte tento API klíč za API klíč svého workspace, který získáte po objednání služby "Integrace API" a Generování API klíče.

Vyvolání vzdálené identifikace se děje ve 3 krocích:

Založení dokumentu ze souboru či vzoru ve stavu draft,
Získání Signi ID jednotlivých osob v rámci workspace,
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, 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.
Pokud daná osoba již někdy identifikována byla, odchází jí při vyvolání rovnou výzva k podpisu.

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

Zavoláme end point Vytvoření dokumentu 2.0 > Z dokumentu nebo Vytvoření dokumenty 2.0 > Ze vzoru,

v JSON s parametry je přitom uvedeno "state": "draft":

Ve výsledku volání je mimo jiné identifikační číslo dokumentu idContract, které použijeme pro další volání.

2. Získání ID jednotlivých osob

Zavoláme endpoint Dokument > Seznam podepisujících pro daný dokument . Jde o požadavek typu GET na adrese https://api.signi.com/api/v2/contract/<idContract>/signIdentities/list

Ve výsledku volání jsou identifikační čísla jednotlivých osob id , které použijeme v dalším volání. Id je jednoznačné v rámci e-mailu a workspace Signi.

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

Zavoláme endpoint Dokument > Vyvolání identifikace. Jde o požadavek typu POST na adrese https://api.signi.com/api/v2/contract/{idContract}/auth/group .

V JSON s parametry je uvedeno, pro ID jaké osoby chceme jakou metodu ověření.

Na základě volání end pointu jsou rozeslané odpovídající výzvy k identifikaci. Zároveň end point vrací URL pro provedení identifikace jednotlivých osob. Je tak možné po zavolání end pointu rovnou otevřít stránku pro provedení identifikace přímo v integrované aplikaci např. na webových stránkách pro prodej nového produktu.