DigiSign je API-driven aplikace, celkem má přes 150 endpointů. Tento článek se zaměřuje na postup odeslání obálky k podpisu a následné stažení podepsaných dokumentů.
Pomocné odkazy pro práci s API
OpenAPI dokumentace | https://api.digisign.org/api/docs.json (lze využít k importu do Postman kolekce) |
API server | https://api.digisign.org produkce https://api.digisign.digital.cz testing (sandbox, pro zřízení test účtu si napište na podpora@digisign.cz) |
PHP SDK knihovna pro zjednodušení práce s API
|
|
Stav služeb a incidenty |
|
Poznámka: API bere rozdílně, pokud atribut v objektu vynecháte a pokud jej pošlete s hodnotou "null".
Vynechání atributu v objektu znamená že hodnotu nechcete upravovat tzn. zůstane tak jak byla. V případě vytvoření to pak znamená že se hodnoty nastaví podle výchozího nastavení.
Poslání atributu s hodnotou "null" vyjadřuje že hodnotu přímo chcete vynulovat. Pokud atribut není nulovatelný tak API vrátí Bad Request.
tl;dr (ve zkratce)
# | Krok | Endpoint |
1 | Autentizace | /api/auth-token |
2 | Vytvoření obálky | /api/envelopes |
3 | Přidání dokumentů | /api/files /api/envelopes/{envelope}/documents |
4 | Přidání příjemců | /api/envelopes/{envelope}/recipients |
5 | Přidání podpisových značek | /api/envelopes/{envelope}/tags |
6 | Odeslání obálky | /api/envelopes/{envelope}/send |
7 | Získání podepsaných dokumentů | /api/envelopes/{envelope}/download |
Vytvoření API klíče
Pro práci s DigiSign API je třeba si nejprve vygenerovat API klíč. Toto provedete v selfcare Nastavení> Pro vývojáře> API klíče. Kliknutím na tlačítko Nový API klíč se otevře dialogové oko pro zadání údajů a práv klíče.
U klíče je možné nastavit různá oprávnění, podle toho, jaké akce mu chcete povolit provádět:
Provolávání pod registrovaným API klíčem je také možné omezit na konkrétní IP adresy či rozsahy. Pokud by tedy zkoušel provolat endpoint pod jinou IP, volání by skončilo chybou.
Po kliknutí na Vytvořit API Klíč se zobrazí hodnoty:
accessKey
secretKey
Tyto hodnoty si uložte, jelikož je nebude možné již znovu zobrazit a slouží pro autentizaci viz následující krok.
Autentizace
DigiSign API používá bearer autentizační schéma (RFC 6750).
Na endpointu /api/auth-token vyměňte accessKey/secretKey za token.
POST /api/auth-token
{
"accessKey": "ETy2b51BU2g7bQLuum",
"secretKey": "2C4lorbh0kw5zUVcPiGdK8EFLBPDYHC0brpzOsba1hNUKnQW93aeAIwzU0"
}
Odpověď:
{
"token": "eyJ0eXAi...Keeq-bJVYmQ",
"exp": 1682572132,
"iat": 1682485732
}Token poté posílejte ve všech následných voláních v hlavičce Authorization.
Authorization: Bearer eyJ0eXAi...Keeq-bJVYmQ
Vytvoření obálky
Pro vytvoření konceptu obálky nejsou povinná žádná data, nicméně pro její odeslání je potřeba definovat name a emailBody.
POST /api/envelopes
{
"name": "Dokumenty k podpisu",
"emailBody": "Dobrý den,<br>posílám vám dokumenty k podpisu.",
"emailBodyCompleted": "Posílám vám podepsané dokumenty ke stažení."
}
emailBody - text může obsahovat následující HTML tagy a[href|title],br,u,em,ul,ol,li,strong,i,b ...pokud text žádné html tagy neobsahuje převádí se newline (\n) znaky na <br>
V odpovědi získáme ID obálky, které budeme potřebovat v následujících krocích.
{
"id": "3974d252-b027-46df-9fd8-ddae54bc9ab9",
"status": "draft",
"name": "Dokumenty k podpisu",
"emailBody": "Dobrý den,<br>posílám vám dokumenty k podpisu."
// ...
}Odpověď zároveň obsahuje i klíče _actions a _links (HATEOAS) - tj odkazy a akce, které jsou na daném zdroji možné. Lze je použít k získání URL pro následující kroky.
Přidání dokumentů
Nahrání souborů
Pro přidání dokumentu do obálky je potřeba nejprve nahrát soubor.
Endpoint /api/files je obecný pro jakýkoliv typ souboru a předpokládá mulitipart/form-data request s částí file.
POST /api/files
Content-Type: multipart/form-data; boundary=----foobar
Content-Length: 834
----foobar
Content-Disposition: form-data; name="file" filename="doc.pdf"
Content-Type: application/pdf
61 CF 89 62 // file binary data
----foobar
V odpovědi získáme ID souboru nebo přímo IRI (identifikátor zdroje) který je v objektu _links pod klíčem self.
{
"originalName": "doc.pdf",
"id": "fc5ecf5a-2d91-463a-91cc-c9bc4b11b371",
"_links": {
"self": "/api/files/fc5ecf5a-2d91-463a-91cc-c9bc4b11b371"
}
}
Přidání dokumentů
Nově nahraný soubor poté přidáme do obálky jako Dokument společně s názvem, který se bude zobrazovat uživateli.
POST /api/envelopes/3974d252-b027-46df-9fd8-ddae54bc9ab9/documents
{
"file": "/api/files/fc5ecf5a-2d91-463a-91cc-c9bc4b11b371",
"name": "Smlouva o smlouvě minulé"
}Z odpovědi budeme potřebovat IRI dokumentu pro další kroky.
Přidání příjemců
Příjemce může mít jednu z rolí:
role | úloha | popis |
signer | Podepisující | Dostane email s žádostí o podpis, podepisuje na svém vlastním zařízení. |
in_person | Podepisující osobně | Provede podepisující relaci osobně s uživatelem DigiSign účtu (zprostředkovatelem) například přes naši mobilní aplikaci. |
cc | V kopii pro čtení | Po dokončení mu přijde kopie hotové obálky. |
approver | Schvalovatel | Dostane email s žádostí o schválení. Obálku následně může schválit, či zamítnout. |
autosign | Automatický podpis | Příjemce je automaticky podepsán, ihned jakmile je na řadě. Podmíněno vlastní firemní pečetí, typem podpisu simple a žádným ověřením. |
semi_autosign | Poloautomatický podpis | Totožné jako autosign s rozdílem, že k provedení podpisu dojde na základě provolání endpointu /api/envelopes/{envelope}/recipients/{recipient}/autosign |
Pro odeslání obálky je nutné přidat alespoň jednoho podepisujícího příjemce.
POST /api/envelopes/3974d252-b027-46df-9fd8-ddae54bc9ab9/recipients
{
"role": "signer",
"name": "John Doe",
"email": "john.doe@example.com",
"mobile": "+420111222333"
}
Z odpovědi nás zase bude zajímat IRI příjemce pro další krok.
Podpisové/schvalovací značky
Podpisová značka definuje místo na dokumentu, kam se má podepisující podepsat.
Lze ji přidat pouze pro podepisujícího příjemce na podepisovatelný dokument.
Podepisující příjemce: příjemce s rolí signer, in_person, autosign, semi_autosign
Podepisovatelný dokument: soubor dokumentu je PDF
Schvalovací značka definuje místo na dokumentu, kam bude vloženo schvalovací razítko.
Lze ji přidat pouze pro schvalovatele na podepisovatelný dokument.
Schvalovatel: příjemce s rolí approver
Podepisovatelný dokument: soubor dokumentu je PDF
Pozici značky lze definovat dvěma způsoby:
Umístění zástupným slovem (placeholder)
Pro určení umístění značky se použije slovo (dále placeholder), které DigiSign v celém PDF vyhledá a určí si podle něj stránku a souřadnice. Hodí se pro případy, kdy je dokument generovaný a není předem jasné přesné umístění značky.
Značka se umístí na první výskyt tohoto placeholderu. Je proto v případě více podpisů nutné myslet na unikátnost. Placeholder může obsahovat pouze malé a velké znaky bez diakritiky, čísla, pomlčku, podtržítko a závorky. (regex ^[\w\-\{\}\[\]\(\)=\,`]*$)
Příklady validních placeholderů:
podpis-123456
{signature897}
[sign_tag_654654]
{sign.tag=`2312}
Lze použít text libovolné velikosti a barvy, takže placeholder může být klidně bílý na bílém pozadí - pro podepisujícího tedy neviditelný.
Placeholder je poté potřeba poslat při vytváření pole do dokumentu, stránka a x,y souřadnice v takovém případě musí být null, ty si API doplní samo. Pokud se placeholder nepodaří v dokumentu najít API vrátí validační chybu.
POST /api/envelopes/3974d252-b027-46df-9fd8-ddae54bc9ab9/tags
{
"document": "/api/envelopes/3974...9ab9/documents/91e7...6de7",
"recipient": "/api/envelopes/3974...9ab9/recipients/9ab9...3974",
"type": "signature",
"placeholder": "podpis-123456",
"positioning": "top_left"
}
Umístění na více výskytů zástupných slov
Pokud potřebujeme vložit podpisové značky na všechny výskyty placeholderu, využíváme následující endpoint:
POST /api/envelopes/3974d252-b027-46df-9fd8-ddae54bc9ab9/tags/by-placeholder
{
"document": "/api/envelopes/3974...9ab9/documents/91e7...6de7",
"recipient": "/api/envelopes/3974...9ab9/recipients/9ab9...3974",
"type": "signature",
"placeholder": "podpis-123456",
"positioning": "top_left"
}
Pozicování značky
Klíčem positioning lze při vytváření značky určit jakým způsobem se značka umístí vůči placeholderu. Může nabývat devíti hodnot. Příklad:
top_left | Levý horní roh značky bude umístěn na levý horní roh slova. |
center | Střed značky bude umístěn na střed slova. |
bottom_center | Střed spodní strany značky bude umístěn na střed spodní strany slova. |
Obdobně pro všechny ostatní hodnoty:
top_left, bottom_left, middle_left, top_right, bottom_right, middle_right, top_center, bottom_center, center
Umístění souřadnicemi
Pro určení pozice souřadnicemi se používají tyto atributy:
page | Stránka dokumentu (začíná od 1) |
xPosition | Horizontální odsazení od levého horního rohu stránky |
yPosition | Vertikální odsazení od levého horního rohu stránky |
Souřadnice jsou definovány v jednotkách “points” v přepočtu 72 points/inch.
Narozdíl od výchozího souřadnicového systému PDF je pozice počítána od levého horního rohu.
Na definované pozici bude ve výsledném dokumentu levý horní roh podpisové značky, která má velikost 55x21mm
type určuje typ značky. U podepisujících je povinná podpisová značka:
POST /api/envelopes/3974d252-b027-46df-9fd8-ddae54bc9ab9/tags
{
"document": "/api/envelopes/3974...9ab9/documents/91e7...6de7",
"recipient": "/api/envelopes/3974...9ab9/recipients/9ab9...3974",
"type": "signature",
"page": 2,
"xPosition": 250,
"yPosition": 375
}
signature | podpisová značka |
approval | schvalovací značka |
text | input pro text |
document | značka pro vložení fotek dokladu |
attachment | značka pro vložení přílohy |
checkbox | zaškrtávací pole |
radio_button | přepínač |
date_of_signature | datum podpisu |
Odeslání obálky
Pro odeslání obálky musí být splněna následující kritéria:
stav obálky musí být koncept (draft)
musí mít alespoň jeden podepisovatelný dokument
musí mít alespoň jednoho podepisujícího nebo schvalujícího příjemce
musí být definovaný předmět a tělo emailu (name, emailBody)
všichni podepisující příjemci musí mít definovanou podpisovou značku na nějakém dokumentu
expirace musí být v budoucnosti (pro případ, že byla manuálně nastavena)
Pokud je vše v pořádku, tak odeslání rozešle všem podepisujícím email s žádostí o podepsání
POST /api/envelopes/3974d252-b027-46df-9fd8-ddae54bc9ab9/send
Získání podepsaných dokumentů
Ve chvíli kdy poslední podepisující v obálce dokončí podpisovou relaci se obálka dokončí a tím se všem příjemcům rozesílá kopie podepsaných dokumentů ke stažení.
Pro získání podepsaných dokumentů přes API lze použít endpoint
GET /api/envelopes/3974d252-b027-46df-9fd8-ddae54bc9ab9/download?output=separate
Výstup je konfigurovatelný pomocí query parametrů:
parametr | hodnota | popis |
output | separate | vrátí ZIP se všemi soubory |
| combined | vrátí všechny PDF soubory spojené do jednoho |
| only_log | vrátí pouze Auditní log |
include_log | true | Auditní log bude součástí |
| false | Auditní log nebude součástí |
document_name_id | true | názvy souborů budou dle ID dokumentu př: fe6603a5-3f85-49af-a961-7617002926cb.pdf |
| false | názvy souborů podle názvu dokumentu př: smlouva-o-smlouve-minule.pdf |
Dokumenty lze získat i jednotlivě pomocí volání konkrétních endpointů:
GET /api/envelopes/3974...9ab9/documents/91e7...6de7/download
Webhooky
Webhooky umožňují nastavit si vlastní URL, kterou DigiSign provolá ve chvíli, kdy nastane určitá událost. Toto stačí nastavit jednou a URL bude volána pro všechny následné události. Webhooky tedy využijete zejména pro získávání informací o aktualizaci stavů entit.
Více k použití webhooků viz samostatný článek.