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.

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.

...

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

...

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

...

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

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

...

JSON soubory ke stažení

{
    "contract_name":"Testovací smlouva 2022",
    "number": "000001",
    "locale": "cs",
    "settings": {
      "signing_order": "proposers_before_counterparties",
      "autosign_proposers": "V Praze"
    },
    "people": [
      {
        "is_proposer": true,
        "email": "demo@signi.com",
        "contract_role": "sign"
      },
      {
        "is_proposer": false,
        "party_order": 1,
        "email": "protistrana@firmademo+API@signi.czcom",
        "contract_role": "sign",
        "person_type": "nature",
        "first_name": "John",
        "last_name": "Doe2Doe´"

      }
    ],
    "template": {
        "id": "7v1",
        "parameters": [
          {
            "id": "112",
            "value": "Hnutí za digitalní revoluci"
          },
          {
            "id": "131122",
            "value": "ChciHnutí za digitalní revoluci"
          },
          {
            "id": "411131",
            "value": "V šíření zprávChci"
          },
          {
            "id": "421411",
            "value": "27.V šíření zpráv"
          },
          {
            "id": "421",
            "value": "27.5.2021"
          },
          {
            "id": "431",
            "value": "v Praze"
          },
        ]  {
         }
  }

Výsledný dokument zaslaný k podpisu

...

   "id": "5",
            "value": "true"
          }
        ]
    }
  }

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

<con-section con-id="22">
            <con-options con-id="221" bind="selection-221" name="" description="" placeholder="vyberte">
                <con-option con-id="2211" 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">
                    <p class="odsazeni"><span>V.2</span>Tato Smlouva nabývá účinnosti okamžikem jejího podpisu oběma Smluvními stranami.</p>
                </con-option>
                <con-option con-id="2212" label="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 class="odsazeni"><span>V.2</span>Smluvní strany berou na vědomí, že tato Smlouva ke své účinnosti vyžaduje uveřejnění v registru smluv podle zákona č. 340/2015 Sb., zákon o registru smluv a s tímto uveřejnění souhlasí. Zaslání Smlouvy do registru smluv provede Příjemce neprodleně po uzavření této Smlouvy. Tato Smlouva nabývá platnosti dnem podpisu poslední Smluvní stranou a účinnosti dnem uveřejnění prostřednictvím registru smluv.</p>
                </con-option>
            </con-options>
        </con-section>

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

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

Příklad kódu vzoru

<con-part hideable=true con-id=“5”>
.... text, který  někdy je a není zobrazen
</con-part>

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

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

Příklad 4 - Získání

...

• Pokud předáde k podpisu PDF nebo údaje pro vzor viz příklady výše, můžete si otevřít stránky podpisu pro jednotlivé podepisující přímo ve vaší aplikaci. Tam ji mohou podepisující rovnou podepsat.

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

• URL stránek k podpisu vrací End Pointy pro vytvoření smlouvy a v odpovědi (http response) vypadá následovně.

...

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í

 "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

...

<con-section con-id="22">
            <con-options con-id="221" bind="selection-221" name="" description="" placeholder="vyberte">
                <con-option con-id="2211" 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">
                    <p class="odsazeni"><span>V.2</span>Tato Smlouva nabývá účinnosti okamžikem jejího podpisu oběma Smluvními stranami.</p>
                </con-option>
                <con-option con-id="2212" label="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 class="odsazeni"><span>V.2</span>Smluvní strany berou na vědomí, že tato Smlouva ke své účinnosti vyžaduje uveřejnění v registru smluv podle zákona č. 340/2015 Sb., zákon o registru smluv a s tímto uveřejnění souhlasí. Zaslání Smlouvy do registru smluv provede Příjemce neprodleně po uzavření této Smlouvy. Tato Smlouva nabývá platnosti dnem podpisu poslední Smluvní stranou a účinnosti dnem uveřejnění prostřednictvím registru smluv.</p>
                </con-option>
            </con-options>
        </con-section>oni volají v JSON :
{
                "value": "V.2  Tato Smlouva nabývá účinnosti okamžikem jejího podpisu oběma Smluvními stranami.",
                "id": "221"
            },

Příklad 5 - 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í

...

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

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

...

Příklad 6 - 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í

[
    {
        "docs_person": {
            "email": "demo@signi.com",
         "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"
    }
]

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

{
   "settings":{
      "firstnamesigning_order": "Kapitánone_at_a_time",
      "one_device":true
   },
   "lastnamepeople": "Demo",[
      {
         "docsis_roleproposer": "proposer",
  true,
         "mobileemail": "test@signi.com",
        },         "contract_role": "sign",
         "statepositions":[
"signed",         "contract_first_shown_date": "2021-06-22T15:21:18+02:00",  {
      "signature_field_show_date": "2021-06-22T15:21:18+02:00"     },   "x":15,
 {         "docs_person": {    "y":50,
               "emailpage": "roman.ripa@signi.com",0
            }
 "firstname": "Roman",       ]
     "lastname": "Řípa", },
      {
         "docsis_roleproposer": "counterparty"false,

           "mobileparty_order":1,
"+420605202397"         }"email":"unregistered+1@example.com",
         "contract_role": "sign",
         "statepositions": "signed",[
           "contract_first_shown_date": "2021-06-22T15:22:06+02:00" {
               "x":15,
        "signature_field_show_date": "2021-06-23T09:52:46+02:00"       "y":80,
               "page":0
            }
]

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:

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, 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":

{
  "number": "RU21001
         ],
         "first_name":"John",
         "last_name":"Doe#1",
         "person_type":"legal"
      },
      {
         "is_proposer":false,
         "email":"unregistered+2@example.comm",
         "contract_role":"sign",
    "contract_name     "positions": "Dokument ve stavu draft",[
            {
               "statex":50,
               "drafty":80,
   "locale            "page": "cs",
  ....

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

[
	{
		"signIdentityId": 116,
		"enabledAuths": [
			"aml", "bankId"
		]
	}
]

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.

{
  "links": [0
            }
         ],
         "first_name":"John",
         "last_name":"Doe#2",
         "person_type":"legal"
      }
   ],
   "file":"uploaded_file_key"
}

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

{
  "contract_id": "1234",
  "attachments": [],
  "state": "pending",
  "notifications": [
    {
      "email": "unregistered+1@example.com",
      "links": {
        "contract": "https://app.signi.com/contract/received/67ecf33b..."
      }
    },
    {
      "full_nameemail": "Tomáš Johanovský",unregistered+2@example.com",
      "links": {
        "linkcontract": "https:\/\/app.test.signi.tech\com/dashboard\contract/workspace\/597\/documents\/12291received/b4fe4d95..."
    },  }
  {  }
    "full_name": "John Doe#1",
      "link": "https:\/\/app.test.signi.tech\/auth\/FGDYDLF7jp6xqcf4ID6xHg6Hi4fjMNGUrtf42PL8dPbVjJRZn8IfFtE3pR6fpVJBEjVWB5FyVl2j6qFv11E0Jb7qpjM1HMdyeFXxZHMMHllXx5YKrl4NeKcC"
    }
  ]
}

Příklad 8 - Skrytí některých dokumentů v sadě některým podepisujícím

• Skrytí některých dokumentů v sadě se může hodit v různých případech.

• Prvním příkladem může být trojstranná dohoda o financování, která zahrnuje několik dokumentů podepisovaných mezi zákazníkem , dodavatelem a financujícím, kdy některá ze stran nemá vidět některé dokumenty, např. zákazníkovi může být jedno, co si přesně dohodl financující a dodavatel a podobně.

• Jiným příkladem je např. Košilka/Krycí list, který zachycuje interní komentáře jednotlivých pracovníků navrhovatele , aby statutář měl podklady pro své rozhodunutí a mohl případně následně dokázat, že jednal s péčí řádného hospodáře.

• V příkladu níže se podepsují 2 dokumentu a jeden z podepisujících test+unregistered@signi.com nemá vidět 2. dokument v sadě . Nastaví se příznakem "is_visible": false u první přílohy v sadě.

• Přestože podepisující neuvidí dokument, je třeba k němu určit jakoukoliv metodu podepsání, zde je u test+unregistered@signi.com uvedeno "contract_role": "sign_certificate". Důvody jsou dva - Signi vyžaduje u osob mít uvedenou motedu podepsání a zároveň musí být přípraveno na situace, kdy dokument se z integrované aplikace předává ve stavu “Rozpracováno” t,j. "state": "draft": a v Signi zpracovatelé dokumentu pomohou zobrazení dokumentu povolit klepnutím na ikonu oka. Musí být zřejmé, jaká metoda podpisu se má pak nastavit jako výchozí.

{
    "view_order": 2,
    "settings": {
        "signing_order": "all_at_once"
    },
    "people": [
        {
            "is_proposer": true,
            "email": "test@signi.com",
            "contract_role": "sign",
            "positions": [
                {
                    "x": 15,
                    "y": 80,
                    "page": 0
                }
            ]
        },
        {
            "is_proposer": false,
            "first_name": "TestUnreg",
            "last_name": "TestUnreg",
            "email": "test+unregistered@signi.com",
            "contract_role": "sign_certificate",
            "person_type": "nature",
            "positions": [
                {
                    "x": 15,
                    "y": 50,
                    "page": 0
                }
            ]
        }
    ],
    "file": "uploaded_file_key",
    "attachments": [
        {
            "view_order": 1,
            "people": [
                {
                    "is_proposer": true,
                    "email": "test@signi.com",
                    "contract_role": "sign",
                    "positions": [
                        {
                            "x": 15,
                            "y": 80,
                            "page": 0
                        }
                    ]
                },
                {
                    "is_proposer": false,
                    "first_name": "TestUnreg",
                    "last_name": "TestUnreg",
                    "email": "test+unregistered@signi.com",
                    "contract_role": "sign_certificate",
                    "person_type": "nature",
                    "positions": [
                        {
                            "x": 15,
                            "y": 50,
                            "page": 0
                        }
                    ],
                    "is_visible": false
                }
            ],
            "file": "uploaded_attachment_file_key"
        }
    ]
}

Příklad 9 - Podpis na jednom zařízení přes API

• 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 na jednom zařízení”: 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 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.

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

{
   "settings":{
      "signing_order": "one_at_a_time",
      "one_device":true
   },
   "people":[
      {
         "is_proposer":true,
         "email":"test@signi.com",
         "contract_role":"sign",
         "positions":[
            {
               "x":15,
               "y":50,
               "page":0
            }
         ]
      },
      {
         "is_proposer":false,
         "party_order":1,
         "email":"unregistered+1@example.com",
         "contract_role":"sign",
         "positions":[
            {
               "x":15,
               "y":80,
               "page":0
            }
         ],
         "first_name":"John",
         "last_name":"Doe#1",
         "person_type":"legal"
      },
      {
         "is_proposer":false,
         "email":"unregistered+2@example.comm",
         "contract_role":"sign",
         "positions":[
            {
               "x":50,
               "y":80,
               "page":0
            }
         ],
         "first_name":"John",
         "last_name":"Doe#2",
         "person_type":"legal"
      }
   ],
   "file":"uploaded_file_key"
}

Příklad 10 - Na vědomí

...

“Na vědomí “ se hodí, pokud někdo chce být informován o průběhu zpracování dokumentu, ale nijak do procesu nezasahuje tj. ani dokument nepodepisuje a neschvaluje viz “Na vědomí“

...

V roli u člověka je použije misto "contract_role":"sign" nově "contract_role":"notice"

...

]
}

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:

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, 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":

{
  "number": "RU21001",  
  "contract_name": "Dokument ve stavu draft",
  "state": "draft",
  "locale": "cs",
  ....

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

[
	{
		"signIdentityId": 116,
		"enabledAuths": [
			"aml", "bankId"
		]
	}
]

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.

{
  "links": [
    {
      "full_name": "Tomáš Johanovský",
      "link": "https:\/\/app.test.signi.tech\/dashboard\/workspace\/597\/documents\/12291"
    },
    {
      "full_name": "John Doe#1",
      "link": "https:\/\/app.test.signi.tech\/auth\/FGDYDLF7jp6xqcf4ID6xHg6Hi4fjMNGUrtf42PL8dPbVjJRZn8IfFtE3pR6fpVJBEjVWB5FyVl2j6qFv11E0Jb7qpjM1HMdyeFXxZHMMHllXx5YKrl4NeKcC"
    }
  ]
}