Page Comparison

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.

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.

...

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

...

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.

...

{
    "contract_name": "Document with placeholders - just counterparty",
    "number": "2022000001",
    "locale": "cs",
    "settings": {
        "signing_order": "all_at_once"
    },
    "people": [
        {
            "is_proposer": true,
            "email": "demo@signi.com",
            "contract_role": "approve"
        },
        {
            "is_proposer": false,
            "email": "zakaznik@seznam.cz",
            "contract_role": "sign",
            "person_type": "nature",
            "first_name": "John",
            "last_name": "Doe#2",
            "positions": [
              {
                "anchor": "signi-signature-0"
              } 
            ]
        }
    ],
    "file": "uploaded_file_key"
}

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

...

{
    "contract_name": "Navrhovatel schvaluje automaticky, protistrana kvalifikovaný podpis, podpisy přes placeholdery, použijte Signi API - Testovací dokument - Placehodery 2.pdf",
    "number": "document number - 000001",
    "state": "pending",
    "locale": "cs",
    "settings": {
        "signing_order": "proposers_before_counterparties",
        "autosign_proposers": "V Praze"
    },
    "people": [
        {
            "is_proposer": true,
            "email": "demo@signi.com",
            "contract_role": "approve",
                  "positions": [
              {
                "anchor": "signi-signature-0"
              } 
            ]
  },
        {
            "is_proposer": false,
            "email": "demo+protistrana-neregistrovana01@signi.com",
            "contract_role": "sign_certificate",
	    "person_type": "nature",
            "first_name": "John",
            "last_name": "Doe#2",

            "positions": [
              {
                "anchor": "signi-signature-2"
              } 
            ]

        }
    ],
    "file": "uploaded_file_key"
}

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á?

...

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.

...

...
{
"id": "221", 
"value": "V.2  Tato Smlouva nabývá účinnosti okamžikem jejího podpisu oběma Smluvními stranami."
},
...

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.

...

...
 {"id": "5","value": "hide"},
 ...

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 .

...

 "contract_id": "83166",
    "signer_data": {
        "firstname": "Roman",
        "surname": "Řípa",
        "address": "Praha",
        "birthdate": "06-08-1970"
    },
    "state": "completed",
    "modified": "23-06-2021",
    "file": " <style>\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 .

...

[
    {
        "docs_person": {
            "email": "demo@signi.com",
            "firstname": "Kapitán",
            "lastname": "Demo",
            "docs_role": "proposer",
            "mobile": ""
        },
        "contract_role": "sign",
        "state": "signed",
        "contract_first_shown_date": "2021-06-22T15:21:18+02:00",
        "signature_field_show_date": "2021-06-22T15:21:18+02:00"
    },
    {
        "docs_person": {
            "email": "roman.ripa@signi.com",
            "firstname": "Roman",
            "lastname": "Řípa",
            "docs_role": "counterparty",
            "mobile": "+420605202397"
        },
        "contract_role": "sign",
        "state": "signed",
        "contract_first_shown_date": "2021-06-22T15:22:06+02:00",
        "signature_field_show_date": "2021-06-23T09:52:46+02:00"
    }
]

6. Podpis v integrované aplikaci

• Jednou z možností jak propojit Signi s aplikací je vyvolání stránky podpisu přímo z integrované aplikace viz Předání podkladů > Podpis v integrované aplikaci . Pokud se při volání použije příznak “Podpis v integrované aplikaci” tj "one_device":true :

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

  • b) v Kontrolním listě bude záznam o tom, že proběhl “podpis na jednom zařízení” což například splňuje legislativní požadavek na předání podepsaného dokumentu přímo na pracovišti viz např. Elektronické podepisování v HR s využitím Signi.

• Jde o obdobu Podpis na jednom zařízení přes uživatelském rozhraní Signi.

• Pokud jsou stránky podepisování obrandované dle integrované aplikaci viz 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.

• Při předání dokumentu k podpisu Signi vrací URL pro podpis dokumentu, který následně integrovaná aplikace zobrazí. Pří volání je třeba do podpisového scénáře uvíst v sekci settings "one_device":true příznak.

...

Tuto stránku resp. tyto stránky zobrazí přímo integrovaná aplikace.

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.

...

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.

...

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 .

...