Vše /
Admin dokumentace

Integrace

DocuSign

DocuSign

Komunikace s DocuSign předpokládá existenci uživatele v DocuSign, který přidělí TASu (aplikaci) oprávnění (grant), na jehož základě může TAS vystupovat jeho jménem a vystavovat dokumenty k podpisu.

Proces přidělení oprávnění není v tuto chvíli dořešen, z důvodu technických omezení TASu. Nicméně ho lze provést jiným kanálem a pokud ho uživatel v rozhraní DocuSign neodvolá, mělo by oprávnění zůstat platné.

Pro komunikaci s Docusign z výpočtů je potřeba definovat endpoint pro autorizaci a pro API. Tím je možné přepínat práci mezi produkčním nebo testovacím DocuSign prostředím.

Autorizační endpoint pro testovací prostředí je: https://account-d.docusign.com/oauth/API endpoint pro testovací prostředí je: https://demo.docusign.net/restapi

Pro testování je možné založit účet https://developers.docusign.com/platform/account/

Dále je nutné znát:

id uživatele (userId), pod kterým má TAS vystupovat
integrační klíč (integrationKey) unikátní pro každou napojovanou aplikaci
vlastnit privátní klíč sloužící k podepisování JWT během přihlášení k API (vzniká spolu s integrationKey během přidání aplikace do DocuSign)

Všechny operace s API vyžadují:

access token - vzniká při přihlášení aplikace na autorizačním portálu. Má platnost hodinu, ale navrhoval bych vytvořit si nový pro každý vzniklý případ, než hodnotu sdílet.
API account ID - uživatel DocuSign může mít pod sebou více “účtů”. Tento účet bude pravděpodobně v našem případě jen jeden a ID se tedy nebude měnit, ale opět bych na začátku každého případu stáhnul jeho hodnotu.

DocuSign nastavení

Založení DEMO účtu v DocuSign je možné https://developers.docusign.com/platform/account/

V editaci aplikace v DS je potřeba přidat Redirect URL: https://neworigin.teamassistant.cz/docusign/authorization-code/callback
Otevřít v privátním okně URL:
TEST:
https://account-d.docusign.com/oauth/auth?redirect_uri=https%3A%2F%2Fneworigin.teamassistant.cz%2Fdocusign%2Fauthorization-code%2Fcallback&scope=signature impersonation&client_id=INTEGRATION-ID&state=d733c43856&response_type=code
PROD:
https://account.docusign.com/oauth/auth?redirect_uri=https%3A%2F%2Fneworigin.teamassistant.cz%2Fdocusign%2Fauthorization-code%2Fcallback&scope=signature impersonation&client_id=INTEGRATION-ID&state=d733c43856&response_type=code
V URL je potřeba nahradit INTEGRATION-ID za Intagration Key té aplikace, kterou v DS napojuješ
Otevře se rozhraní DocuSign kam se přihlásíš a kde potvrdíš, že tato aplikace (TAS) má právo se za tebe vydávat, aby TAS mohl generovat žádosti o podpis.
Když to vše projde správně, mělo by tě to hodit na adresu https://neworigin.teamassistant.cz/docusign/authorization-code/callback, kde bude napsáno "DocuSign authorization completed"

//Ideálně to od začátku implementuj s secured = true a někam klidně dopiš, že chyba Secret 'XYZ123' not found. Znamená, že je potřeba do local.js přidat příslušný integrační privátní klíč pod název XYZ123

Pro žádost o přístup TAS do klientovho DocuSign použi šablonu e-mailu

EMLPT nebo EML

API - Přihlášení a zjištění Account ID

https://developers.docusign.com/platform/auth/jwt/jwt-get-token/

DSCreateAuthJWT(endpoint, integrationKey, userId, secureKey, algorithm, secured = false)

Funkce vygeneruje JWT token, nutný pro přihlášení k DocuSign

endpoint – definice endpointu, account-d.docusign.com = test, account.docusign.com = produkce
integrationKey - integreční klíč aplikace
userId – id uživatele, pod kterým vystavit dokument k podpisu
secureKey – heslo nebo privátní klíč k podpisu, případně identifikátor z sails.config.secrets, pokud je secured = true
true - název klíče, který je zapsaný v security v local.js
false - skutečný obsah klíče, který máš vygenerovaný v rozhraní DS pro danou integraci
algorithm – algoritmus podpisu. Pro privátní klíč bude RS256
secured - přepíná význam parametru secureKey

DSGetAccessToken(authorizationEndpoint, JwtData)

Funkce získá access token potřebný pro volání API operací

authorizationEndpoint - autorizační endpoint, https://account-d.docusign.com/oauth/ = test
JwtData – JWT token získaný funkcí DSCreateAuthJWT()

DSGetDefaultApiAccountId(authorizationEndpoint, accessToken)

Funkce zjistí výchozí account Id vybraného uživatele

authorizationEndpoint - autorizační endpoint, https://account-d.docusign.com/oauth/ = test
accessToken – access token získaný funkcí DSGetAccessToken()

DSListSignatureProviders (DSEndpoint, accessToken, apiAccountId)

Funkce zjistí seznam poskytovatelů podpisu dostupných pro použitý účet.

DSEndpoint – endpoint DocuSign API, https://demo.docusign.net/restapi = test
accessToken – access token získaný funkcí DSGetAccessToken()
apiAccountId – account Id získané funkcí DSGetDefaultApiAccountId()

Odeslání dokumentů k podpisu e-mailem

DSCreateEnvelope(DSEndpoint, accessToken, apiAccountId, subject = '', documents = [], signers = [], copies = [], comment ‘null)

Vytvoří obálku obsahující dokumenty k podpisu a odešle e-mail podepisujícím. Dokumentů lze do obálky vložit více, ale podepisuje se pouze obálka, nikoli každý dokument zvlášť.

DSEndpoint – endpoint DocuSign API, https://demo.docusign.net/restapi = test
accessToken – access token získaný funkcí DSGetAccessToken()
apiAccountId – account Id získané funkcí DSGetDefaultApiAccountId()
subject - předmět odeslaného e-mailu
documents – pole objektů definujících dokumenty k podpisu. Struktura objektu:
filename - název podepisovaného dokumentu, včetně koncovky
payload – obsah podepisovaného dokumentu jako base64
signers – pole objektů definujících osoby, které musí dokumenty v obálce podepsat.

Struktura objektu:

name - jméno podepisujícího
email – e-mailová adresa podepisujícího
smsAuthentication – telefonní číslo pro autentizaci pomocí SMS (může obsahovat pole více čísel), ve formátu +XXXAAABBBCCC
fixedTabs – nepovinná definice fixního umístění podpisu. Jde o pole objektů s následující strukturou (více info https://developers.docusign.com/docs/esign-rest-api/esign101/concepts/tabs/fixed/):

[{
  "documentId": "1",
  "name": "SignHereTab",
  "pageNumber": "1",
  "recipientId": "1", #This value represents your {RECIPIENT_ID}
  "tabLabel": "SignHereTab",
  "xPosition": "75",
  "yPosition": "572"
}]

routingOrder - nepovinný parametr definující pořadí podepisujících. Pokud není vyplněno, použije se pořadí, jak jsou přijemci uvedeni v seznamu. Pokud je parametr null, může adresát podepsat kdykoli (respektive může jich několik dostat výzvu k podpisu současně).
signatureProvider - nepovinný výběr poskytovatele (TSP) pro Standards-based Signing pomocí osobního certifikátu. Může obsahovat pole více objektů. Struktura objektu poskytovatele je následující a hodnoty musí odpovídat dokumentaci https://developers.docusign.com/docs/esign-rest-api/esign101/concepts/standards-based-signatures/ . Seznam dostupných poskytovatelů je uveden v sekci Signature provider options.

{
  "signatureProviderName": "UniversalSignaturePen_OpenTrust_Hash_TSP",
  "signatureProviderOptions": {
    "sms": "+AAAXXYYZZ"
  }
}

signatureProviderName - výběr poskytovatele podpisů. UniversalSignaturePen_OpenTrust_Hash_TSP je autorita spravovaná DocuSign
signatureProviderOptions – objekt s parametry daného poskytovatele. Výše zmíněný UniversalSignaturePen_OpenTrust_Hash_TSP má jako povinný parametr jeden z atributů sms nebo oneTimePassword pro zadání telefonního čísla podepisujícího, pro jeho autentizaci, respektive přímo pro zapsání jednorázového hesla, které musí být podepisujícímu předáno jiným kanálem.
emailSubject - předmět notifikačního e-mailu, specifický pro daného příjemce
emailComment - text obsažený v těle e-mailu s notifikací, specifický pro daného příjemce

POZOR - parametry emailSubject a emailComment musí být pro daného příjemce vyplněny oba, nebo ani jeden z nich

Zneplatnění obálky

DSVoidEnvelope(DSEndpoint, accessToken, apiAccountId, envelopeId, message = '')

Označí obálku jako zneplatněnou. Další akce a podepisování s touto obálkou nebudou možné.

DSEndpoint – endpoint DocuSign API, https://demo.docusign.net/restapi = test
accessToken – access token získaný funkcí DSGetAccessToken()
apiAccountId – account Id získané funkcí DSGetDefaultApiAccountId()
envelopeId – ID obálky získané funkcí DSCreateEnvelope()
message - zpráva objasňující důvod zrušení obálky

DSQueueForPurgeEnvelopeDocuments (DSEndpoint, accessToken, apiAccountId, envelopeId, includeMetadata = false)

Zařadí dokumenty z obálky do fronty ke smazání z DocuSign.

DSEndpoint – endpoint DocuSign API, https://demo.docusign.net/restapi = test
accessToken – access token získaný funkcí DSGetAccessToken()
apiAccountId – account Id získané funkcí DSGetDefaultApiAccountId()
envelopeId – ID obálky získané funkcí DSCreateEnvelope()
includeMetadata – false = smazat pouze dokumenty, true = smazat i přílohy a podpisy

Informace o existujících obálkách v DocuSign

DSListEnvelopeStatusChanges (DSEndpoint, accessToken, apiAccountId, fromDate = null, toDate = null, fromToStatus = '', statuses = ['any'], envelopeIds = null, additionalOptions = {})

Vrátí seznam obálek, u nichž došlo v daném čase ke sledované změně, případně jsou v definovaném stavu. Seznam stavů viz dokumentace https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/liststatuschanges/

DSEndpoint – endpoint DocuSign API, https://demo.docusign.net/restapi = test
accessToken – access token získaný funkcí DSGetAccessToken()
apiAccountId – account Id získané funkcí DSGetDefaultApiAccountId()
fromDate – čas od (ideálně ve formátu ISO 8601 včetně časové zóny
toDate – čas do, pokud se vynechá, je výchozí aktuální čas
fromToStatus – stav, do kterého se obálka měla v časovém období dostat
statuses – pole statusů, ve kterých mají obálky být v tento okamžik
envelopeIds – pole identifikátorů sledovaných obálek
additionalOptions – objekt, ve kterém lze definovat další filtry podle dokumentace https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/liststatuschanges/

DSGetEnvelope(DSEndpoint, accessToken, apiAccountId, envelopeId, includeAttributes = [])

Stáhne informace o vybrané obálce.

DSEndpoint – endpoint DocuSign API, https://demo.docusign.net/restapi = test
accessToken – access token získaný funkcí DSGetAccessToken()
apiAccountId – account Id získané funkcí DSGetDefaultApiAccountId()
envelopeId – ID obálky získané funkcí DSCreateEnvelope()
includeAttributes - pole s výběrem rozšířených atributů pro zahrnutí do odpovědi, viz dokumentace

Práce s dokumenty v obálce

DSListEnvelopeDocuments(DSEndpoint, accessToken, apiAccountId, envelopeId)

Vrátí seznam dokumentů vložených do obálky, plus “certifikát” o aktivitě(podepsání) obálky.

DSEndpoint – endpoint DocuSign API, https://demo.docusign.net/restapi = test
accessToken – access token získaný funkcí DSGetAccessToken()
apiAccountId – account Id získané funkcí DSGetDefaultApiAccountId()
envelopeId – ID obálky získané funkcí DSCreateEnvelope()

DSGetEnvelopeDocument(DSEndpoint, accessToken, apiAccountId, envelopeId, documentId)

Stáhne vybraný dokument z obálky. Data jsou předána jako base64.

DSEndpoint – endpoint DocuSign API, https://demo.docusign.net/restapi = test
accessToken – access token získaný funkcí DSGetAccessToken()
apiAccountId – account Id získané funkcí DSGetDefaultApiAccountId()
envelopeId – ID obálky získané funkcí DSCreateEnvelope()
documentId – ID dokumentu ze seznamu vráceného funkcí DSListEnvelopeDocuments(), případně string “certificate” pro stažení shrnutí aktivity, nebo string “archive” pro stažení všech dokumentů spolu se shrnutím v jednom ZIP souboru

Updated 17/2/25 by Anna Gernát

ISDOC.PDF

(opens in a new tab)