Digital Signature API

General Description

Digital Signature (DS) API purpose to facilitate using DocuSign API for signing and delivering PDF documents.

Authentication and authorization

Only authorized users or applications can use this API.

There are two scopes of authorization:

DigitalSignature.Sign
DigitalSignature.Admin

User in first scope can perform all actions, except managing DocuSign users.

You should have Admin scope otherwise.

First you need to get bearer token:

IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create({ClientId}).WithTenantId({TenantId}).WithClientSecret({ClientSecret}).Build();
var token = await app.AcquireTokenForClient(new string[] {$"api://{ClientId"]}/.default"}).ExecuteAsync();

Where ClientId and ClientSecret you can get in application Azure registration. (In this case your application should be added to application list, which have access to DS).

Or you can use DS ClientId and ClientSecret instead, which we can provide for you.

After getting the token, we add it to HttpClient header:

HttpClient _client;
_client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

After this HttpClient can perform Http request to DS endpoints.

Actions

DS API has the following controllers:

Documents: managing and processing documents (certificates and envelops) in DocuSign.

- We can download PDF documents and envelops from DocuSign.
Each document should be wrapped to envelope. Envelope can contain one or several documents.
You need provide EnvelopeId and DocumentId for getting document:
```
/api/v2/Documents/Document/{EnvelopeID}/{DocumentID}
```
Or you can download envelop with documents inside:
```
/api/v2/Documents/Envelop{EnvelopeID}
```
Example:
```
_httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", GetAuthHeader());
_httpClient.DefaultRequestHeaders.Add("EnvelopeId", envelopeId.ToString());
 return _httpClient.GetStreamAsync(/api/v2/Documents/ + "Documents/Envelope?EnvelopeId=" + envelopeId.ToString());
```
You can also download all signed envelops:
```
/api/v2/Documents/Envelops
```
- Convert Html document to PDF
DocuSign sign only PDF documents. But you can send Html, Jpeg or MS Office document to DocuSign and DocuSign will convert it to pdf for you. Unfortunately, resulting PDF is not completely accessible.
But if you want to have more control you can convert Html to PDF yourself. We use for this Telerik document processing library.
You can use the following POST endpoint to convert Html to PDF:
```
/api/v1/Documents/HTMLToPDF/
```
Example:
```
var json = JsonSerializer.Serialize(html);
HttpContent content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");
return await _httpClient.PostAsync(url, content);
```
We can get portrait or landscape PDF, it depends on LandscapePageOrientation property of SignInfoHtml class. But default it’s false, so resulting PDF is in portrait mode.
EVE: generating QR code for links to EVE
/wiki/spaces/MAR/pages/2577891341 is a website designed for the purpose of allowing users to check the validity of digital documents issued by Transport Canada.
Using DS API, you can generate search result links to EVE or generate QR instead links.
To get link:
```
/api/v2/EVE/URL/
```
Example:
```
var resultData = await _httpClient.GetStringAsync(url);
```
To get QR code:
```
/api/v2/EVE/URL/QRCodeImageForURL/
```
Example:
```
var result = await _httpClient.GetStringAsync(url);
```

Signing: signing documents (Html. PDF, JPG and MS Office docs) in DocuSign

We can sign one or several documents by one request.
You can specify signature position two ways:
- absolution position (X, Y) or
- anchor, marking some text as place where signature should be

There are 3 ways to sign document:

Embedded
In this case you provide required information and get back url for signing ceremony.
You need to provide the following information:
- sender and signer names and emails
- names of the documents
- html content or base64 content (only in version 2) for each document
- signature position (absolute or anchor) for each document
Signing Html (POST):

/api/v2/Signing/HTMLCeremonyUrl/

Example:

 var url = "/api/v2/Signing/HTMLCeremonyUrl/";
var json = JsonSerializer.Serialize(info);
HttpContent content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");  
return await _httpClient.PostAsync(url, content);

Where info is the instance of the following class:

public class SignInfoHtml : SignInfo
    {
        public SignInfoHtml() : base(){}

        public SignInfoHtml(IConfiguration iConfig) : base(iConfig) { }

        public int NumberOfDocuments
        {
            get
            {
                return new int[] { HtmlContent.Length, DocumentName.Length }.Min();
            }
        }
        public string[] HtmlContent { get; set; }
        public bool[] LandscapePageOrientation { get; set; };
        public bool HasAnchorString { get; set; }
        public string[] AnchorString { get; set; }
        public string[] AnchorUnits { get; set; }
        public int[] AnchorXOffset { get; set; }
        public int[] AnchorYOffset { get; set; }
    }

Signing non-Html (only in version 2) (POST):

/api/v2/Signing/Templates/CeremonyUrl/

Difference with HTML signing, that it used other info class:

public class SignInfoBase64 : SignInfo
    {
        public SignInfoBase64() : base(){}

        public SignInfoBase64(IConfiguration iConfig) : base(iConfig) { }

        public int NumberOfDocuments
        {
            get
            {
                return new int[] { Content.Length, DocumentName.Length }.Min();
            }
        }
        public string[] Content { get; set; }     
    }

Email Request
In this case you provide the same information, but get not url, but email to signer email address with request to signer certificate.
Signing Html (POST):

/api/v2/Signing/Signing/HTMLEmailRequest/

Example:

 var url = "/api/v2/Signing/Signing/HTMLEmailRequest/";
 var json = JsonSerializer.Serialize(info);
 HttpContent content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");
 return await _httpClient.PostAsync(url, content);

Where info is information, required for singing (see above).

Signing non-Html (only in version 2) (POST):

/api/v2/Signing/Signing/EmailRequest/

Template
In this case we don’t send document to DocuSign, but use template, uploaded to DocuSign.
We can get templates using the following endpoint (GET):
```
/api/v2/Signing/Templates/
```
Signing (POST):
```
/api/v2/Signing/TemplateCeremonyUrl/
```
Email request (POST):
```
/api/v2/Signing/TemplateEmailRequest/
```

Users: managing DocuSign users (require Admin scope)
- Get list of all signers (GET)
```
/api/v2/Signing/Users/Signers/
```
- Create DocuSign user (POST)
```
/api/v2/Signing/Users/Users/
```
- Update user information (PUT)
```
/api/v2/Signing/Users/Users
```
- Delete user (DELETE)
```
/api/v2/Signing/Users/Users/
```

Versioning

There are two version of DS API.

Current version is 2.

Digital Signature API

General Description

Authentication and authorization

Actions

Versioning

References