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.
"Hello World" příklad 1 - Získání informací o zakladateli workspace
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 .
Adresa je https://api.ismlouva.cz/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
{
"user": {
"email": "aplikace@signi.com"
},
"workspace": {
"name": "iSmlouva marketing"
},
"token": {
"expiration_date": "2030-08-07"
},
"links": {
"tokens": "https://app.ismlouva.cz/api"
}
}
"Hello World" příklad 2 - Předání PDF dokumentu k podpisu
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.
V tomto scénáři podepisuje zástupce navrhovatele dokumentu a protistrana. Zakladatelem workspace s právem navrhovat, schvalovat i podepisovat je účet aplikace@ismlouva.cz . 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.
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, 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.
{
"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:
