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.
| Table of Contents |
|---|
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.
...
| Code Block |
|---|
{
"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.
...
| Info |
|---|
|
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ý.
...
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.
...
| Code Block |
|---|
{
"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í.
...
| Code Block |
|---|
{
"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_counterpartiesto 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
...
| Code Block |
|---|
{
"settingscontract_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.5.2021V šíření zpráv"
},
{
"id": "431421",
"value": "v Praze27.5.2021"
},
{
] } } |
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
| Code Block |
|---|
<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
| Code Block |
|---|
... { "id": "221", "value": "V.2 Tato "id": "431", "value": "v Praze" }, { "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
| Code Block |
|---|
<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." }, ... |
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
| Code Block |
|---|
<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
| Code Block |
|---|
...
{"id": "5","value": "hide"},
... |
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ě.
| Code Block |
|---|
{
"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..."
}
}
]
} |
<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
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í
| Code Block |
|---|
"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>
</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
| Code Block |
|---|
...
{
"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
| Code Block |
|---|
<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
| Code Block |
|---|
...
{"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 .
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í
| Code Block |
|---|
"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 .
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.
...
| Code Block |
|---|
[
{
"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
...
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":
...
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
| Code Block |
|---|
{ "settings":{ "signing_order": "one_at_a_time", "contractone_namedevice":true "Dokument ve stavu draft"}, "statepeople":[ { "draft", "is_proposer":true, "localeemail": "cstest@signi.com", .... |
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 .
| Info |
|---|
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í.
| Code Block |
|---|
[
{
"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.
| Code Block |
|---|
{ "links": [ "contract_role":"sign", "positions":[ { "x":15, "y":50, "page":0 } ] }, { "fullis_nameproposer":false, "Tomáš Johanovský", "linkparty_order": "https:\/\/app.test.signi.tech\/dashboard\/workspace\/597\/documents\/12291"1, }, "email":"unregistered+1@example.com", { "fullcontract_namerole": "John Doe#1sign", "linkpositions": "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í.
| Code Block |
|---|
{ "view_order": 2, "settings": { "signing_order": "all_at_once" }, "people": "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":[ { "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":truepříznak.
| Code Block |
|---|
{ "settings":{ "x":50, "y":80, "page":0 } ], "signingfirst_ordername": "one_at_a_time"John", "onelast_devicename":true"Doe#2", }, "peopleperson_type":["legal" {} ], "is_proposer":true, "email":"test@signi.com"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ě.
| Code Block |
|---|
{ "contract_id": "1234", "attachments": [], "contract_rolestate": "signpending", "positions"notifications": [ { "email": {"unregistered+1@example.com", "links": { "xcontract":15, "https://app.signi.com/contract/received/67ecf33b..." } "y":50}, { "pageemail":0 "unregistered+2@example.com", "links": { } "contract": ]"https://app.signi.com/contract/received/b4fe4d95..." }, } { "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", ] } |
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":
| Code Block |
|---|
{
"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 .
| Info |
|---|
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í.
| Code Block |
|---|
[
{
"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.
| Code Block |
|---|
{ "links": [ { "lastfull_name": "Doe#2Tomáš Johanovský", "person_typelink":"legal "https:\/\/app.test.signi.tech\/dashboard\/workspace\/597\/documents\/12291" }, } { ], "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"
...
"full_name": "John Doe#1",
"link": "https:\/\/app.test.signi.tech\/auth\/FGDYDLF7jp6xqcf4ID6xHg6Hi4fjMNGUrtf42PL8dPbVjJRZn8IfFtE3pR6fpVJBEjVWB5FyVl2j6qFv11E0Jb7qpjM1HMdyeFXxZHMMHllXx5YKrl4NeKcC"
}
]
}
|