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 v Apiary, 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 |
|---|
"Hello World"
...
Example 1 -
...
Na produkčním prostředí je workspace "iSmlouva - Marketing" a má API klíč = “fI7BbxOiGPrgrk8HHrhOyuoTw0Ld6L38uFVktIdzLgneRMFaoIbDaslDEtpRNu97” , 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.
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 .
...
Gathering the information about workspace
There is a workspace "Demo API" with the API key “71c4123d242bdd38047bee838d17e3367dc3ea6748d0975217ce501e834a224c83cab8afd35c9b0e6ade806b7987fae80f97f5c8253cfbb9089cf21f” and Signi production environment https://api.signi.com. Use the API key of your workspace for your calls.
End Point Description
End Point Call
Request - GET
Address - https://api.ismlouvasigni.czcom/api/v1/me .
Na záložce Autorization je jako typ autorizace zvolen jako typ autorizace API Key a jako hodnota klíče Autorization - Type: API Key , Placement in: Header, variable name: 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
...
, value: see API key above.
...
End Point Result
| Code Block |
|---|
{
"user": {
"email": "aplikace@signi.com"
},
"workspace": {
"name": "iSmlouva marketing"
},
"token": {
"expiration_date": "2030-08-07"
},
"links": {
"tokens": "https://app.ismlouva.cz/api"
}
}
|
"Hello World"
...
Example 2 -
...
Na produkčním prostředí je workspace "iSmlouva - Marketing" a má API klíč = “fI7BbxOiGPrgrk8HHrhOyuoTw0Ld6L38uFVktIdzLgneRMFaoIbDaslDEtpRNu97” , 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.
...
| Info |
|---|
|
Popis v dokumentaci
Volání v Postmanovi
...
Požadavek je typu POST .
...
Issuing the PDF file for the Signature
There is a workspace "Demo API" with the API key “71c4123d242bdd38047bee838d17e3367dc3ea6748d0975217ce501e834a224c83cab8afd35c9b0e6ade806b7987fae80f97f5c8253cfbb9089cf21f” and Signi production environment https://api.signi.com . Use the API key of your workspace for your calls.
End Point Description
End Point Call
Request - POST
Address - 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 with parameter Type with the value “doc”.
Autorization - Type: API Key , Placement in: Header, variable name: 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 , value: see API key above.
Body - type request multipart/form-data a jsou uvedeny dva klíče and two keys- data a uploaded_file_key , které jsou typu file. 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
JSON soubor s parametry volání
V příkladu:
je použito takzvané Dynamické umístění podpisů, kdy podpisy jsou umístěny 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 navrhovateea 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.
...
of File type . The first contains the JSON file with end point parameter the second one is PDF file to be signed.
...
Section Params
...
Section Autorization
...
Section Body
The keys in the Points section are of type "File", the file to be sent in the request is selected from your disk
and uploaded via "Select Files"
End Point JSON File with Parameters
| Code Block |
|---|
{
"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"
}
|
| Info |
|---|
...
Yes, |
...
we know, such parameter passing is not a pure REST API, |
...
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:
...
we will improve the API in future versions. |
End Point Result
It contains:
contract_id - unique identification of the document useful for future calls regarding this document
the URLs for signing the documents by each signer.
Final Document Example
...
“Hello World” Example 3 - Issuing the Data Into the Template in Signi
There is a workspace "Demo API" with the API key “71c4123d242bdd38047bee838d17e3367dc3ea6748d0975217ce501e834a224c83cab8afd35c9b0e6ade806b7987fae80f97f5c8253cfbb9089cf21f” and Signi production environment https://api.signi.com . Use the API key of your workspace for your calls.
The proposer of the document is demo@signi.com . The signing counterparty is protistrana@firma.cz , you can change it to your e-mail to test the signing . The order of signing is set to
proposers_before_counterpartiesi.e. the proposer signs the first (automatically in this case) and couterparty afterwards.There is used the template Testovací smlouva with the ID template 7v1 and several parameters with ID 12, 131, 411, 421, 431 .
End Point Description
End Point Call
Request - POST
Address - https://api.signi.com/api/v1/contract/ , with parameter Type with the value “template”.
Autorization - Type: API Key , Placement in: Header, variable name: x-api-key , value: see API key above.
Body - type request multipart/form-data and one key - data of File type . It contains the JSON file with end point parameter.
...
The keys in the Points section are of type "File", the file to be sent in the request is selected from your disk
and uploaded via "Select Files"
End Point JSON Parameters
| Code Block |
|---|
{
"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"
}
],
"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"
}
]
}
}
|
Final Document Example
An invitation to sign the document is sent to the user with the email counterparty@company.com.
...