| Table of Contents |
|---|
Jak si nastavit prostředí Signi pro integraci?
1.Založit jediný hlavní účet na Signi, který je Vlastníkem všech workspace
Založení účtu na Signi - viz postup na Vytvoření účtu a první přihlášení do aplikace. Hlavní účet Signi doporučujeme založit pod e-mailem nikoliv konkrétního člověka, ale na e-mail typu info@firma.cz či signi@firma.cz s tím, že pošta zaslaná na tento e-mail musí být přístupná zřizovateli účtu. Ten musí potvrdit registrační e-mail zaslaný ze Signi.
Přes tento účet se následně řeší i veškeré objednávání a placení služeb Signi, zakládání workspace, nastavování jejich parametrů, přidávání lidí do týmu, generování API klíčů apod. pro vaši firmu.
2. Založit workspace pro testování integrace
Při založení účtu na Signi se automaticky vytvoří pracovní prostor - workspace pro zřizovatele účtu.
Pro integraci se pod hlavním účtem vytvoří typicky ještě další 2-3 workspace např. Agenda X - PRODUKCE / Agenda X - TEST / Agenda X - DEVELOPMENT, viz Vytvoření více workspace . Nemíchají se tak provozní data s vývojovými či testovacími.
Každý workspace má svůj API klíč, každé prostředí na straně integrované aplikace používá API klíč pro "svůj" workspace. Při přechodu z vývoje na test či produkci tedy stačí prohazovat API klíče.
3. Zpřístupnění API a získání API klíčů
Pro vývojový / demonstrační workspace je přístup API zdarma, aktuálním řešením je napsat na help@signi.com žádost “Integrační balíček”s uvedeným hlavním e-mailem a názvem workspace, které chcete v totmo režimu používat. My vám přístup přes API povolíme.
Následně si pro workspace pod svým hlavním účtem vygenerujete API klíče svých workspace, viz Generování API klíče.
4. Využití workspace pro agendy mimo integraci
Ve vaší organizaci můžete mít i workspace pro používání Signi napřímo přes uživatelské rozhraní, kdy uživatelé vkládají dokumenty k podpisu přes uživatelské rozhraní Signi.
Více viz Kombinace obou přístupů.
| Info |
|---|
Pokud se nastavováním nechcete probírat sami, rádi vás celým procesem provedeme v rámci zprovozňování Signi ve vaší firmě. Osvědčilo se vám něco jiného? Narazili jste na situace, kdy vám toto uspořádání nevyhovuje? Dejte nám vědět. |
Předání podkladů k podepisování
Jak se předávají podklady k podepisování?
Předání souborů
Do Signi se z vaší Aplikace předá soubor k podpisu, formát viz V jakých formátech se předávají soubory k podpisu? a informace o umístění podpisů v dokumentu.
Protistraně je pak při schvalování dokumentu zobrazen dokument včetně polí k podpisu.
Dokument včetně podpisů je ze Signi zaslán zpět do aplikace jako soubor PDF.
Více viz Vytvoření smlouvy / dokumentu 2.0 > Z dokumentu a “Jak při předávání dokumentů k popisu předat informaci o umístění podpisů?” níže.
Předání parametrů pro vzor
V Signi je připraven vzor dokumentu se značkami odpovídajícími jednotlivým parametrům dokumentu na vhodná místa ve dokumentu.
Konkrétní hodnoty parametrů, například jméno klienta, se předají jako podklady při vyvolání požadavku na vytvoření smlouvy.
Dokument včetně podpisů je ze Signi zaslán zpět do aplikace v PDF .
Více k tématu Vytvoření smlouvy / dokumentu 2.0 > Ze vzoru a odstavec níže Jak při použití vzorů při podepisování předat parametry k vyplnění do vzoru.
Jaké parametry jsou při volání nepovinné a k čemu se používají?
Pro zaslání dokumentu k podpisu je nutný jen e-mail a telefon, nicméně mezi parametry jsou i další identifikační údaje.
Některé údaje jsou nutné při předávání podkladů pro vzor, kdy ve vzoru dokumentu není žádná identifikace smluvních stran a vyplňují se z parametrů předaných při volání.
I zde je třeba povinné jméno, datum narození má smysl zadávat tehdy, kdy zákazník chce, aby pro přesnější identifikaci smluvní strany bylo uvedeno.
Při předání dokumentů nejsou nutné, nicméně pro zachování stejné struktury parametrů tam zůstávají.
Ve zprávách podepisujícím přes SMS a e-mail se použije Jméno, Příjmení či Organizace coby identifikace odesílatele dokumentu. Stejně jako ve jménu odesílajícího v hlavičce e-mailu.
Pokud se předají údaje o podepisujících ve strukturované podobě, bylo by možné po jejich následné registraci jim zobrazit i jejich dokumenty podepsané bez registrace. Vzhledem ke GDPR a potenciálnímu riziku omylu tato funkce zřejmě nebude dostupná.
Jaký je nejjednodušší scénář podepisování?
Při propojování je dobré začít nejjednodušším scénářem podepisování a pak ho případně zesložiťovat dle potřeb uživatelů. Jak vypadá:
Autorem / navrhovatelem dokumentů (is_proposer=true při volání API ) je e-mail zakladatele pracovního prostoru / workspace v Signi, do kterého se přes API dokumenty posílají, tj. typicky e-mail hlavního účtu na Signi pro firmu navrhovatele dokumentu. Dokument pouze schvaluje (contract_role=true), tj. není na dokumentu vidět jeho podpis. Při volání přes API proběhne jeho schválení automaticky.
Všichni podepisující či schvalující bez ohledu na to, zda jsou z firmy navrhovatele či nikoliv, jsou označeni jako protistrany (is_proposer=false). Díky tomu vůbec nemusí mít zavedený účet v Signi, pouze v integrované aplikaci. Přijdou jim všem výzvy k podpisu a oni mohou dokument podepsat. Nevýhodou je pouze to, že fyzicky musí podepsat každý dokument.
| Code Block |
|---|
{
"name": "Document name - XXXXX",
"number": "Document number - YYYYY",
"locale": "cs",
"settings": {
"signing_order": "proposers_before_counterparties",
"autosign_proposers": "V Praze"
},
"people": [
{
"is_proposer": true,
"email": "vlastnikworkspace@firma.cz",
"contract_role": "approve"
.....
},
{
"is_proposer": false,
"party_order": 2,
"email": "podepisujicizanavrhovatele@firma.cz",
"contract_role": "sign"
....
}
{
"is_proposer": false,
"party_order": 3,
"email": "podepisujicizaprotistranu@jinafirma.cz",
"contract_role": "sign"
....
}
],
.... template a parametry či soubor a přílohy apod. |
Lze se vyhnout tomu, aby zástupce navrhovatele musel podepisovat každý dokument?
Ano, lze viz scénář B v Musí mít podepisující za navrhovatele dokumentů účet na Signi?
Jak vhodně určit název dokumentu?
Název dokumentu je zároveň název souboru PDF podepsaného dokumentu, který se předává zpět do integrovaného systému anebo při stažení dokumentu z uživatelského rozhraní. Zároveň PDF soubor kontrolního list se jmenuje stejně jako PDF podepsaného dokumentu, jen v názvu je prefix KL_ .
Je tedy vhodné při integraci posílat do API v názvu dokumentu, tj. contract_name, nějakou unikátní hodnotu zároveň srozumitelnou pro podepisující. Půjde pak snadno dohledat jednoznačně jak dokument, tak jeho kontrolní list. Zároveň je třeba myslet na to, že název dokumentu se ukazuje podepisujícím v e-mailových a SMS notifikacích, tj. není úplně vhodné posílat např. číslo samotné. Příklad správného názvu: “Čestné prohlášení k reklamaci č. 6493543”.
Jak se předávají identifikační čísla dokumentu?
Nyní se pro identifikaci používá číslo dokumentu v Signi - Contract_ID, které je výsledkem vyvolání podpisu a je i součástí volání webhooku (v HEAD sekci).
Pokud si chcete předávat i identifikaci dokumentu v integrovaném systému, jako workaround je možné tuto identifikaci vložit do adresy webhooků.
PŘIPRAVUJEME: Předání identifikace dokumentu v integrovaném systému v logice “vaše číslo/naše číslo” do parametrů vyvolání podpisu i webhooků.
Jdou změnit texty zasílaných e-mailů a SMS?
Ano, lze - je to nastavení platné pro celý workspace/pracovní prostor a může je měnit jakýkoli uživatel s přístupem do prostoru.
Lze určit i jméno odesílatele, resp. jméno adresáta odpovědi (REPLY TO).
Parametry v textech k záměně dle aktuálního stavu:
{CONTRACTNAME} - Doplní název dokumentu, pokud není vyplněn název souboru nebo použitého vzoru
{NAME} - Doplní celé jméno vlastníka pracovního prostoru
{CLIENTNAME} - Doplní celé jméno klienta - u osob jméno a příjmení??, u firem??
Jak odeslat několik dokumentů v jedné sadě?
Posloupnost volání
endpoint template {.... Last_document:false… }
endpoint template attachment {.... Last_document:false… }
endpoint template attachment {.... Last_document:false… }
endpoint template attachment {.... Last_document:true… }
Dokument může mít neomezené množství příloh, podpis každého je účtován jako samostatný podpis.
Pokud má člověk podepsat více dokumentů v jedné dávce, dojde mu pouze jedna SMS a e-mail. Pak se mu ukáží jednotlivé dokumenty, které musí podepsat jeden po druhém.
PŘIPRAVUJEME: Výsledek podpisu každého z dokumentů se nyní předává samostatným voláním příslušného webhooku pro daný dokument. Chceme přidat volbu, kdy se webhook bude volat jen jednou pro celou odeslanou sadu.
Jak získám výsledek předání podkladů pro podpis
Okamžitý výsledek předání podkladů pro podpis zjistíte synchronně jako “Response” na volání příslušného endpointu.
Pokud jsou podklady kompletní a validní, kód odezvy je 200. Chybové kódy začínají 400 , kde v body je popis chyby. Občas můžete narazit na univerzální chybu 500, snažíme se ji minimalizovat.
V BODY odpovědi získáte i hodnotu proměnné Contract_ID, což je identifikace dokumentu v Signi. Tento údaj je pak použit ve webhooku (viz dále), lze ho použít pro stažení Kontrolního listu s průběhem podpisování dokumentu apod.
Součástí odezvy jsou i URL unikátních adres stránek pro podpis dokumentu konkrétními podepisujícími/schvalujícími, které lze použít při integraci.
Jaké jsou způsoby podepsání z integrované aplikace?
Jsou 3 základní cesty :
Distanční podepsání přes API
Po vyvolání podpisu v integrované aplikaci se po zavolání end pointu Signi API odešle e-mailová zpráva s odkazem na stránky pro podepsání. Pokud je uvedeno telefonní číslo, může odcházet i SMS notifikace. Je to obdoba standardního odeslání dokumentu k podpisu přes uživatelské rozhraní Signi. Uživatel vůbec Signi nevidí, pracuje výhradně s integrovanou aplikací.
Podpis přímo v integrované aplikaci přes API
V uživatelském rozhraní Signi je volba Podpis na jednom zařízení, kdy navrhovatel i všechny protistrana/y jsou na jednom místě a podepisují v Signi v jednom okamžiku na jednom zařízení.
Při integraci s jinou aplikací lze toto zrealizovat obdobně s tím, že se podepisuje v integrované aplikaci. Signi při předání dokumentů či podkladů pro vzor vrací URL pro podpis jednotlivých podepisujících - viz Jak získám výsledek předání podkladů pro podpis. Integrovaná aplikace pak zobrazí stránky s těmito adresami pro podpis jednoho či více podepisujících. Pozor, pokud je podepisujících více, musí mít všichni svůj prostor k podpisu. Pokud se podepisuje více dokumentů najednou v sadě, pořád je vše pod jedním URL, jen vidí uživatel v levém panelu několik záložek s jednotlivými dokumenty.
Signi jako fronta práce k podepisování na tabletu/mobilu
V tomto režimu integrovaná aplikace pošle dokument do Signi tak, aby se v Signi ukázal pracovníkovi navrhovatele pracujícího s tabletem či mobilem jako dokument ke zpracování.
Obchodník jednající s klientem na provozovně nebo u klienta, řidič předávající zboží, servisní technik zasahující u zákazníka podepíše dokument na svém zařízení - typicky tabletu či mobilu.
Dokumenty
V jakých formátech se předávají soubory k podpisu?
V aktuální verzi lze přes API posílat výhradně PDF, podpora dalších formátů DOC, DOCX, XLS, XLSX, HTML se bude doplňovat resp. vracet.
V HTTP requestu se soubory k podpisu s předávají ve formátu - multipart/form-data.
PŘIPRAVUJEME:
Vrácení podpory DOC, DOCX, XLS, XLSX, HTML při nahrávání přes API.
Ve variantě End Pointů Full RestAPI budou binární soubory překódovány do textu.
Jak předávat informaci o umístění podpisů při předávání souborů?
Umísťování podpisů se řeší v případě, že posíláte k podpisu své dokumenty. V případě využití vzorů Signi jsou pozice podpisů dány vzorem.
Dynamické umístění podpisu
Nejjednodušším způsobem, jak umístit podpisy do dokumentů pří předávání přes API, je připojení samostatného podpisového archu s podpisy na závěr dokumentu. Pří volání endpointu Vytvoření smlouvy 2.0 > Z dokumentu se jako jeden z parametrů v sekci settings uvede "missing_positions": "append_to_the_end" viz níže nebo celý příklad Hello World 2 .
| Code Block |
|---|
"settings": {
"signing_order": "all_at_once",
"autosign_proposers": "V Praze",
"missing_positions": "append_to_the_end"
}, |
Příklad uvedení parametru misssing_positions
Přiklad dynamického umístění podpisu
Statické umístění podpisů
Pří volání endpointu Vytvoření smlouvy 2.0 > Z dokumentu lze i přesně určit, kde má být podpis umístěn v poli positions u každé osoby. Tím se pokryjí typicky formuláře, kde je místo k podpisu vždy stejné.
Určuje se parametry X, Y, sign_proposer[position][x] sign_proposer[position][y] sign_proposer[position][page] a sign_negotiator[position][x] sign_negotiator[position][y] sign_negotiator[position][page]
Jde o vzdálenost horního levého rohu podpisu od horního levého rohu dokumentu, bráno k rozměrům nahrávaného dokumentu v %, tj. hodnota je v rozmezí 0 - 100.
Doporučená velikost podpisů pro nahrání do profilu podepisujícího: od 2034 x 792 do 646 x 298.
Určuje se umístění každého podepisujícího a podpisu zvlášť, tj. na dokumentu může být libovolný počet podpisů, např. u vícestranných smluv či více podepisujících statutářů.
Pří více záznamech v poli positions je naopak podpis jednoho podepisujícího vyžadován na více místech jednoho dokumentu. To se hodí např. v případech, kdy je v jednom PDF sloučeno více dokumentů a podepisující se má podepsat na několik z nich.
| Code Block |
|---|
{
"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": "zakaznik@seznam.cz",
"contract_role": "sign",
"person_type": "nature",
"first_name": "John",
"last_name": "Doe#2",
"positions": [
{
"x": 50,
"y": 50,
"page": 0
}
]
}
],
"file": "uploaded_file_key"
}
|
Příklad souřadnic a stránky u osoby
V příkladu podepisuje pouze protistrana, proto je u navrhovatele (“is_proposer”: true) uvedeno "contract_role": "approve", kdy schválení přitom proběhne při volání přes API automaticky
PŘIPRAVUJEME
velikost podpisu se vždy přizpůsobuje velikosti zařízení
pokud je velikost podpisu nadstandardní, půjde ovlivnit vhodným parametrem
využití “placeholderů” v dokumentu obdobně jako např. při hromadné korespondenci
Vzory
Jak při použití vzorů zjistit, které parametry vzor má?
End point https://api.signi.com/api/v1/contract/templates vám vrátí všechny vzory přístupné pro workspace s API klíčem použitým pří volání, ve vráceném seznamu vzorů jsou ve formě JSON uvedeny parametry volání jednotlivých vzorů - viz např. níže.
| Code Block |
|---|
{
"templates": [
{
"id": 396,
"name": "Pohybový doklad ",
"parameters": [
{
"id": "111",
"name": "Typ dokladu",
"type": "con-options",
"values": [
"Příjemka",
"Výdejka",
"Objednávka vydaná",
"Objednávka přijatá",
"Rezervace vydaná",
"Rezervace přijatá",
"Příjemka",
"Vratné obaly"
]
}
...
]
}
]
} |
Jak předávat informaci o umístění podpisů při použití vzorů?
Při použití vzorů dokumentů spravovaných přímo v Signi není třeba umístění podpisů řešit. Umístění i velikost podpisů je daná vzorem.
Jeden podpis lze umístit ve vzoru vícekrát, v kódu vzoru se pouze uvede vícekrát pole pro dané pořadí podpisu. Podepisující se ale fyzicky musí podepisovat pouze jednou.
Více o zajištění návaznosti mezi volání API a kódu vzoru viz níže.
Jak sladit vzory a volání API, aby se podpisy ukazovaly na správných místech ?
Pole pro podpisy ve vzorech je třeba mít přizpůsobené scénáři podepisování předávaném přes API. Pokud záleží na pořadí podepisujících, musí být vzory přizpůsobené i tomu. Dva základní scénáře jsou následující.
Pokud je scénář podepisování s podepisujícím navrhovatelem,
"people": [ { "is_proposer": true, "party_order": 1, "email": "me@example.com", "contract_role": "sign" }, { "is_proposer": false, "party_order": 2, "email": "unregistered+1@example.com", "contract_role": "sign",
odpovídající pole pro podpisu ve vzoru jsou:
<tr> <td> <p> <con-sign con-id="16" party-type="proposer"></con-sign> </p> </td> <td> <p> <con-sign con-id="17" party-type="counterparty" party-order="2"></con-sign> </p> </td> </tr>
Pokud je scénář podepisování bez podepisujícího navrhovatele,
"people": [ { "is_proposer": true, "party_order": 1, "email": "zakladatelworkspace@firmanavrhovatele.cz", "contract_role": "approve" }, { "is_proposer": false, "party_order": 2, "email": "me@example.com", "contract_role": "sign" }, { "is_proposer": false, "party_order": 3, "email": "unregistered+1@example.com", "contract_role": "sign",
odpovídající pole pro podpisu ve vzoru jsou:
<tr> <td> <p> <con-sign con-id="16" party-type="counterparty" party-order="2"></con-sign> </p> </td> <td> <p> <con-sign con-id="17" party-type="counterparty" party-order="3"></con-sign> </p> </td> </tr>
Pokud záleží na pořadí podepisujících, je součástí volání endpointů v API i přepínač signing_order": "one_at_a_time", což odpovídá zaškrtnutí “Záleží na pořadí” v uživatelském rozhraní Signi. Při předávání podpisů přes API u jednotlivých osob / person odpovídá parametr “party_order” 1,2 3… pořadí podepisování a těmto číslům pak musí odpovídat příslušná umístění podpisů ve vzorech.
| Code Block |
|---|
"settings": {
"signing_order": "one_at_a_time"
}, |
Jak si zobrazím celý kód vzoru vzoru?
Vzor dokumentu je uložen v rozšířené verzi HTML.
Přístupný je na endpointu https://signi.docs.apiary.io/#reference/smlouva/smlouva/detail-smlouvy
Obsahuje pole pro nahrazení reálnými hodnotami (placeholder), typu CON_TEXT a další.
Jak při použití vzorů při podepisování předat parametry k vyplnění do vzoru?
Při předávání údajů pro vzor se využije endpoint Vytvoření smlouvy / dokumentu 2.0 > Ze vzoru. V sekci Parameters jsou předány jednotlivé parametru vzoru s tím, že “id” odpovídá id parametru ve vzoru.
| Code Block |
|---|
BODY {
“number:”
... další standardní parametry dokumentů….
"parameters": [
{
"id": "12",
"value": "neurčito"
… další volitelné parametry pro daný vzor...}
"webhooks"
... další části volání
} |
Část volání Endpointu “Vytvoření ze vzoru” v Signi API
| Code Block |
|---|
<con-section con-id="12">:
Datum pohybu: <con-date con-id="1201" name="Datum pohybu" label="[Datum pohybu]" placeholder="Datum pohybu" description="Datum pohybu."></con-date>.<br>
Zakázka: <con-textarea con-id="1202" name="Zakázka" label="[Zakázka]" placeholder="Zakázka" description="Zakázka "></con-textarea><br>
Středisko:
<con-textarea con-id="1203" name="Středisko" label="[Středisko]" placeholder="Středisko" description="Středisko "></con-textarea>
</con-section> |
Část kódu vzoru
jak při použití vzorů přes API skrývat a zobrazovat sekce ve vzoru ?
Ve vzorech lze definovat sekce, jejichž zobrazení lze následně přes API zapínat a vypínat. Ve vzoru k tomu slouží položka con-part .
| Code Block |
|---|
<con-part con-id="6" hideable=true>
<div class="part1">
<div>
<h4>ADRESA PRE ZASIELANIE KOREŠPONDENCIE</h4>
<con-section con-id="61">
<span class="col-2">Ulica: <con-textarea con-id="611" name="Ulica" label="[Doplňte]" placeholder="" description="Uveďte ulicu" style="color:#004085 !important;"></con-textarea></span>
<span class="col-1">| Súpisné číslo: <con-textarea con-id="612" name="Súpisné číslo" label="[Doplňte]" placeholder="" description="Uveďte súpisné číslo" style="color:#004085 !important;"></con-textarea></span>
<span class="col-1">| Orientačné č.: <con-textarea con-id="613" name="Orientačné číslo" label="[Doplňte]" placeholder="" description="Uveďte orientačné číslo" style="color:#004085 !important;"></con-textarea></span>
<span class="col-2">Obec: <con-textarea con-id="614" name="Obec" label="[Doplňte]" placeholder="" description="Uveďte obec" style="color:#004085 !important;"></con-textarea></span>
<span class="col-1">| PSČ: <con-textarea con-id="615" name="PSČ" label="[Doplňte]" placeholder="" description="Uveďte PSČ" style="color:#004085 !important;"></con-textarea></span>
<span class="col-1">| Číslo bytu: <con-textarea con-id="616" name="Číslo bytu" label="[Doplňte]" placeholder="" description="Uveďte číslo bytu" style="color:#004085 !important;"></con-textarea></span>
</span>
</p>
</con-section>
</div>
</div>
</con-part> |
Zobrazení nebo skrytí celé sekce lze řídit tak, že mezi parametry předávanými přes API přidáme i ID parametru odpovídající sekci con-part, kdy hodnota je buď hide, či show.
Kód v JSON souboru pro vytvoření dokumentu ze vzoru pak v poli parameters obsahuje následující pro případ, že sekce con-part=2 má být skryta.
| Code Block |
|---|
....
"parameters": [
{
"id": "2",
"value": "hide"
},
... |
| Info |
|---|
Pozor! Identifikátory sekcí con-part se NEukazují v seznamu parametrů vzoru - viz Jak při použití vzorů zjistit, které parametry vzor má? Jedna z možností, jak je zjistit, je stáhnout si celý kód vzoru pomocí Jak si zobrazím celý kód vzoru vzoru? a tam si příslušné identifikátory sekcí con-part najít. |
Výsledky podepisování
Jak získat výsledky podepisování?
Vyvoláním zpětného webhooku
Součástí předávání podkladů pro podpis jsou i 3 URL adresy tzv. “webhooků” pro každou hodnotu výsledku:
podepsáno - signed,
odmítnuto - rejected,
neověřeno - expired.
URL adresy typicky obsahují volání integrované aplikace.
Zavolán je vždy jen jeden webhook z těchto tří podle výsledku. Pokud se parametr url ponechá prázdný, web hook se nevyvolá.
Ve vzoru volání na apiary.io je třeba text “your_webhook_url\” nahradit reálnou URL.
Nyní se volá webhook pro každý dokument zvlášť včetně příloh.
Při volání webhooku předáváme stejný API klíč jako byl použit pro volání Signi, tj. zabezpečení je stejné jako směrem do Signi. Typ autorizace je tedy API Key, jako hodnota klíče x-api-key je uveden API klíč workspace, do kterého byl dokument k podpisu poslán, a hodnota se předává v Header.
Výsledný podepsaný dokumentse do integrované aplikace při vyvolání webhooku předává následovně:
{
"contract_id": 3359,
"state": "completed",
"attachments": []
}
který je platný pouze 10 minut po vyvolání webhooku, později je při pokusu o stažení vrácena chyba.
Později lze stáhnout dokumentpřeshttps://api.signi.com/api/v1/contract/id/download
Soubor ve webhooku a end pointu download se předává ve formátu - Application/pdf .
PŘIPRAVUJEME: Volbu, kdy půjde pouze podepsat všechny dokumenty v jednom volání a zpět se bude volat pouze jeden webhook. Hodí se např. tehdy, pokud je v integrovaném workflow systému možné jedno větvení podmínek pro jeden případ, který ale zahrnuje více dokumentů.
Průběžným ověřováním stavu
Někdy lze webhooky v integrovaném systému obtížně implementovat. Nebo není z bezpečnostních důvodů vystavit přístup do systému z internetu.
Při odeslání dokumentu k podpisu v odpovědi získáte identifikátor dokumentu v Signi Contract_id, viz např. Response 200 HEADERS Content-Type:application/json BODY { "contract_id": "1234", "attachments": []
Stav příslušného dokumentu získáte přes End Point Detail smlouvy, tj. https://api.ismlouva.cz/api/v1/contract/id, kde id je Contract_id. S ním pak můžete volat např. end pointy: Stav dokumentu Stažení dokumentu Stažení auditní stopy / kontrolního listu dokumentu.
End pointy se volají ve vhodný okamžik, buď přes nějaký časovač/cron pravidelně, při otevírání formuláře, zmáčknutím tlačítka “Aktualizace stavu” apod.
V jakém formátu se předávají výsledné dokumenty?
Soubor ve webhooku a end pointu download se předává ve formátu - Application/pdf
PŘIPRAVUJEME: Ve variantě End Pointů Full RestAPI budou binární soubory překódovány do textu.
Pokročilé funkce
Je možné mít vlastní branding?
Vlastní branding se hodí :
v rámci prodejního procesu - kdy ukážeme zákazníkovi “jeho design” na prvcích komunikace = mailech a stránkách pro schválení dokumentů,
při skutečném nasazení.
Zatím nelze “naklikat”, lze zaslat požadavek.
Možnosti brandingu jsou popsány v Kroky podpisu dokumentu a možnosti brandingu - PUBLIC.
PŘIPRAVUJEME: Cílově půjde o jeden z úkonů, které mohou připravovat a účtovat pro koncové zákazníky ve svém rozhraní partneři.
Musí mít podepisující za navrhovatele dokumentů účet na Signi?
Při integraci Signi umožňuje dva režimy účtů pracovníků organizace v Signi, typicky statutáře, zplnomocněné obchodníky apod. :
A - Pracovníci organizace v Signi nemají účet, pouze přes něj podepisují stejně jako protistrany.
B - Pracovníci organizace v Signi mají účet, mohou se jejich podpisy vkládat automaticky.
Klíčovým faktem přitom je, že každý dokument v Signi musí mít svého jednoznačného navrhovatele, autora dokumentu
Ve scénáři A
Výhodou scénáře je jednoduchost na zprovoznění. Nevýhodou je, že podepisující pracovníci organizace, typicky statutáři, musí podepsat či schválit každý jednotlivý dokument.
Pracovníci organizace nemusí mít účet v Signi, podepisují stejně jako protistrany - dostanou e-mail s výzvou k podpisu, otevřou si z něho stránku podpisu a dokument podepíší či schválí.
Pří integraci lze jako navrhovatele/autora dokumentu uvést e-mail zakladatele pracovního prostoru / workspace na Signi, kam se dokument odesílá, a říci, že on dokument bude pouze (přes API automaticky) schvalovat.
Pracovníci organizace i protistrany mohou dokumenty podepisovat (smlouvy) nebo pouze schvalovat (např. Všeobecné obchodní podmínky).
Scénář podepisování předaný přes API pak bude obsahovat například toto:
| Code Block |
|---|
{
"settings": {
"signing_order": one_at_a_time",
}
{
"people": [
{
"is_proposer": true,
"email": "zakladatelworkspace@firmanavrhujicidokument.cz",
"contract_role": "approve"
},
{
"is_proposer": false,
"party_order": 1,
"email": "podepisujiciobchodnik@firmanavrhujicidokument.cz",
"contract_role": "sign"
},
{
"is_proposer": false,
"party_order": 2,
"email": "podepisujícizakazník@firmaprotistrana.cz",
"contract_role": "sign"
}
], |
Ve scénáři B
Pokud pracovníci organizace:
mají vytvořený účet na Signi,
byli vlastníkem workspace pozváni do workspace s nastaveným právem podepisovat a pozvánku příjali,
může být jejich podpis vložen do dokumentu automaticky. Podle EIDAS je to v pořádku, podpis probíhá v kontrolovaném prostředí Signi, které zajistí, že podpis bude neoodělitelně přípojen k odpovídajícím dokumentům, a volající aplikace (vaše) daného člověka autentifikovala a autorizovala ho k vytvoření, podepsání a předání dokumentu k podpisu dalším protistranám.
Scénář podepisování předaný přes API pak bude obsahovat například takto , autorem / navrhovatelem dokumentu, jehož podpis může být za podmínek výše vložen automaticky je podepisujiciobchodnik@firmanavrhujicidokument.cz :
| Code Block |
|---|
{
"settings": {
"signing_order": "one_at_a_time",
"autosign_proposers": "V Praze"
},
"people": [
{
"is_proposer": true,
"email": "podepisujiciobchodnik@firmanavrhujicidokument.cz",
"contract_role": "sign"
},
{
"is_proposer": false,
"party_order": 1,
"email": "podepisujícizakazník@firmaprotistrana.cz",
"contract_role": "sign"
}
], |
| Info |
|---|
Souhlas vs. Podpis Volba "contract_role = sign / approve" říká, zda bude fyzicky nějaký podpis na dokumentu, či zda ho má nějaký člověk pouze schválit.
|
Jak je zachycena vazba uživatel integrované aplikace a workspace a uživatel v Signi
Vazba uživatelé integrované aplikace - Signi workspace
Workspace v Signi slouží pro ukládání dokumentů, do jeho týmu může být přiřazeno více lidí. Více lidí naopak může mít přístup do více workspace.
Při volání Signi API se pro autentizaci používá API klíč, tj. jasně se určuje, do kterého workspace bude dokument uložen. Více viz Generování API klíče.
Pokud jsou ve vaší aplikaci evidováni:
a) pouze uživatelé - musí být u každého uživatele uveden API klíč.
b) také firmy či pobočky uživatelů - k nimž jsou pak přiřazení jednotliví uživatelé ukládající dokumenty v jednom workspace v Signi, může být Signi API klíč uveden u firmy či pobočky a využívat se při volání všech "jejích" uživatelů
Vazba uživatelé integrované aplikace - Signi uživatelé
V režimu účtu A viz výše, je to jednodušší. Stačí mít
u všech uživatelů zadaný e-mail hlavního účtu zákazníka v Signi,
u firmy/pobočky zadaný e-mail hlavního účtu zákazníka v Signi.
V režimu účtu B je třeba u všech uživatelů zadaný jejich e-mail, kterým se přihlašují do Signi
Proč není API Signi striktně RestAPI?
Signi je integrovaná s různě vyspělými aplikacemi.
Tomu odpovídá současná podoba API, kterou lze nazvat “Essential” a lze snadno použít jednoduše i při základním volání z jednoduchého webu na PHP či CURL utilitu přes HTTP.
PŘIPRAVUJEME: Paralelní verzi fundamentálně pojatého RestAPI, kde například binární soubory jsou překódované do textového řetězce.
Jak testovat chování Signi pro neregistrované uživatele?
Signi se chová odlišně pro ty, kteří jsou a nejsou zaregistrovaní v Signi. U prvních Signi pro podepsání dokumentu vyžaduje jejich přihlášení do Signi. Jim doručené dokumenty k podpisu mají pak přístupné v jejich privátním workspace. Druhým se nabízí anonymní unikátní stránky pro identifikaci a podpisy.
Pro testování Signi pro neregistrované uživatele je vhodné :
Pokud používáte Google emailové účty, lze využít jejich funkci, kdy do schránky neco@firmanagoogle.cz přijdou i emaily odeslané na neco+cokoliv@firmanagoogle.cz . do Do schránky jarda.ripa@signi.com tedy přijdou i emaily odeslané na jarda.ripa+test@signi.com. Pokud odešleme k podpisu dokument na adresu jarda.ripa+test@signi.com , dojdou notifikační emaily do existující schránky jarda.ripa@signi.com. Signi přitom pracuje s tím, že jde o neregistrovaného zákazníka.
V jiných případech má smysl založil firemní e-mailovou skupinu neregistrovanivsigni@firma.cz , zařadit do ní všechny testovače Signi a používat tento email jako adresu podepisujícího neregistrovaného v Signi.
Jaké jsou nejčastější chyby pří volání Signi API
Chybové kódy začínající 400 jsou specifické chyby Signi, kde z chybového hlášení má být zřejmé, co je příčinou a jak ji odstranit.
“Invalid JSON” znamená, že je skutečně někde syntaktická chyba v JSON, což se vzhledem k jeho složitosti snadno stane. Pomoci mohou různé JSON validátory, např. https://jsonformatter.curiousconcept.com/.
Občas můžete narazit na univerzální chybu 500, snažíme se ji minimalizovat.