Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 89 Next »

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

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

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í

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

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

{
    "contract_name": "Obě strany podpisují přes kvalifikovaný podpis, není autopodpis, 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"
    },
    "people": [
        {
            "is_proposer": true,
            "email": "demo@signi.com",
            "contract_role": "sign_certificate",
                  "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"
}

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

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

  • 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

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í

{
    "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@firma.cz",
        "contract_role": "sign",
        "person_type": "nature",
        "first_name": "John",
        "last_name": "Doe2"

      }
    ],
    "template": {
        "id": "7v1",
        "parameters": [
          {
            "id": "112",
            "value": "Hnutí za digitalní revoluci"
          },
          {
            "id": "131",
            "value": "Chci"
          },
          {
            "id": "411",
            "value": "V šíření zpráv"
          },
          {
            "id": "421",
            "value": "27.5.2021"
          },
          {
            "id": "431",
            "value": "v Praze"
          }
        ]
    }
  }

Výsledný dokument zaslaný k podpisu

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

Příklad 4 - Získání URL pro otrevření stránky podpisu v integrované aplikaci

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

{
  "contract_id": "1234",
  "attachments": [],
  "state": "pending",
  "notifications": [
    {
      "email": "unregistered+1@example.com",
      "links": {
        "contract": "https://app.signi.com/contract/received/67ecf33b..."
      }
    },
    {
      "email": "unregistered+2@example.com",
      "links": {
        "contract": "https://app.signi.com/contract/received/b4fe4d95..."
      }
    }
  ]
}

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

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

Volání v Postmanovi

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"
        },
        "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 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 .

Pozor - Smysl má volat požadavek na identifikaci pouze u protistran tj. “doc_role”:”counterparty”, nikoliv u navrhovatelů tj. “doc_role”:”proposer“. Pokud je požadována identifikace navrhovatelů, vrátí API chybu.

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"
    }
  ]
}
  • No labels