All for Joomla All for Webmasters

Tutorial: Hello World

eSignAnyWhere can be easily implemented. This tutorial will show you how to send your first envelope via API and will use this demo document (PDF) via the SOAP webservice of eSignAnyWhere.

For this tutorial you can use your desired programming language (with SOAP support) or any SOAP tool (e.g. SoapUI). Moreover you will need for authorization an active eSignAnyWhere Account (even a trial account will work). If you want to use SoapUI we have a special eSignAnyWhere API with SoapUI Sample for you and if you are using JAVA you may be interested in our Java Library.

The SOAP endpoint of eSignAnyWhere is: https://www.significant.com/api.asmx

What the tutorial is about


The tutorial will show you the following basic use-case:

 

eSAW Tutorial Use CaseFirst we will have the first API Call and then to implement the above shown use case. Basically you simply upload a document. After the upload you will receive a document id, which you need for creating an envelope with a XML configuration. This configuration contains information about the envelope itself, workflow steps, signer information, policies and many more. After the envelope is created successful the workflow start automatically. The eSignAnyWhere system will use callbacks (you can configure them in the envelope XML configuration) to notify you if the envelope status was changed.

Your first API Call


First we will try the SOAP connection with a version request. So we will call GetVersion_v1(), which doesn’t need any authorization.

The response should be the following:

<apiResult version="2.2.458.6616">
  <baseResult>ok</baseResult>
</apiResult>

Authorization


Almost all API calls are expecting an authorizsationXML. Therefore your organization key and your email-adress is required. You can find this under Settings/Organization/Application in eSignAnyWhere. This authorizsation XML has to be encoded via HTML special charaters (“<” in “&lt;” and “>” in “&gt;”). If this encoding is not done you will receive a HTTP 400 Bad Request error. Higher programming languages takes automatically care of the conversion, so just in lower languages it is required (or also SoapUI).

XML:

<authorization>
   <organizationKey>4647688a-xxxx-xxxx-xxxx-xxxxxxxx</organizationKey>
   <userLoginName>your@email.address</userLoginName>
</authorization>

Inline-XML (with HTML special characters):

&lt;authorization&gt;
   &lt;organizationKey&gt;4647688a-xxxx-xxxx-xxxx-xxxxxxxx&lt;/organizationKey&gt;
   &lt;userLoginName&gt;your@email.address&lt;/userLoginName&gt;
&lt;/authorization&gt;

Errors


In case of errors, the error message is part of the response of the SOAP call. In baseResult you see the state of the call (ok/failed) and in errorInfo or okInfo the response. The following you see an authorization error:

<apiResult version="2.2.458.6616">
  <baseResult>failed</baseResult>
  <errorInfo>
    <error>ERR0011</error>
    <errorMsg>ERR0011: Parameter apiAuthorizationXml is incorrect: Failed to parse</errorMsg>
  </errorInfo>
</apiResult>

Upload Document


First we have to upload a document. This will return a documentid, to use the document for creating an envelope. Therefore we will use the UploadTemporarySspFile_v1 function. The function requires the authorization and a Base64 encoded file. Details how you can converting a PDF to a Base64 encoded string you can find in the tools section of Demo, Testlab and Tools page.

For this tutorial we just use a simple PDF document. You can download it here or use your own PDF document.

The uploading call requires the following XML data structure for uploading. Define the file name and the base64 encoded file.

<file>
  <name>eSignAnyWhere_Tutorial.pdf</name>
  <data>##BASE64-FILE-CONTENT##</data>
</file>

This XML also has to be encoded via HTML special charaters (“<” in “&lt;” and “>” in “&gt;”).

The Response after a successfull upload of the file with the document id (SspFileId). The document id you need for creating your first envelope.

<apiResult version="2.2.458.6616">
  <baseResult>ok</baseResult>
  <okInfo>
    <sspFileId>caa5274f-xxxx-xxxx-xxxx-xxxxxxxxxxxx</sspFileId>
  </okInfo>
</apiResult>

After uploading the file it is just temporary on the server. After 10 minutes it will be deleted and you are not able to use it again. The moment you are creating an envelope with the file it gets the time-to-live of the envelope.

Workstep Configuration


A workstep configuration is required for each signing step in your workflow. To receive an adhoc workstep configuration you can call GetAdHocWorkstepConfiguration_v1 with an AdHoc-Configuration (to define the AdHoc generation). The default AdHoc configuration of the sample code you can download here (AdHocConfig as ZIP). If you already have your workstep configuration you can skip this step. Moreover you can generate a workstep configuration with the SIGNificant Workstep Designer. The SIGNificant Workstep Designer allows you as a developer to configure a SignAnyWhere workstep, set signature fields and types and many more. More information about the SIGNificant Workstep Designer you can find in Demo, Testlab and Tools.

The GetAdHocWorkstepConfiguration_v1 will response the adhoc workstep configuration as result:

<apiResult version="2.2.458.6616">
  <baseResult>ok</baseResult>
  <okInfo>
    <workstepConfiguration>
	  ...
    </workstepConfiguration>
  </okInfo>
</apiResult>

You can download the tutorial AdHocWorkstep here (AdHocWorkstep as ZIP).

Send Envelope


For sending an envelope we are using the SendEnvelope_v1 call. This call requires the authorization, the file id(s) and the envelope configuration. A sample envelope configuration you can download here (Envelope Config as ZIP). You just have to change the recipient email adresses for the Hello World example.

The envelope configuration defines the envelope and the steps in the workflow. For each signing step you need to define a workstep configuration, which defines what the signer has to do in his/her signing task.

<envelope>
  <name>eSignAnyWhere Tutorial</name>
  <eMailSubject>Hello World</eMailSubject>
  <eMailBody>Dear #RecipientFirstName#! Please sign this document.</eMailBody>
  <enableReminders>True</enableReminders>
  <firstReminderDayAmount>1</firstReminderDayAmount>
  <recurrentReminderDayAmount>1</recurrentReminderDayAmount>
  <beforeExpirationReminderDayAmount>1</beforeExpirationReminderDayAmount>
  <daysUntilExpire>2</daysUntilExpire>
  <!-- callbackUrl: e.g. http://yourserver.com/default.aspx?EnvelopeId=##EnvelopeId##&amp;myParamForMe=1234 -->
  <callbackUrl />
  <steps>
    <step>
      <emailBodyExtra />
      <orderIndex>1</orderIndex>
      <recipientType>Signer</recipientType>
      <recipients>
        <recipient>
          <languageCode>en-us</languageCode>
          <eMail>recipient1@email.com</eMail>
          <firstName>First</firstName>
          <lastName>Signer</lastName>
          <!-- optional authentication methods for this recipient -->
        </recipient>
      </recipients>
      <workstepConfiguration>...</workstepConfiguration>
    </step>
    <!-- define a copy receiver -->
    <step>
      <emailBodyExtra />
      <orderIndex>2</orderIndex>
      <recipientType>CC</recipientType>
      <recipients>
        <recipient>
          <languageCode>en-us</languageCode>
          <eMail>copyReceiver@somewhere.com</eMail>
          <firstName>Copy Receiver Name</firstName>
          <lastName>Thunderbolt</lastName>
        </recipient>
      </recipients>
    </step>
  </steps>
</envelope>

In the sample XML above the workstep configuration is missing and two steps are defined in the workflow. Step 1 as a signing task and step 2 as a receives copy task.

If the creation of the envelope was successful, you will get the envelope id as response.

<apiResult version="2.2.458.6616">
  <baseResult>ok</baseResult>
  <okInfo>
    <envelopeId>56db6133-xxxx-xxxx-xxxx-xxxxxxxxxxxx</envelopeId>
  </okInfo>
</apiResult>

After the successful creation the enveolpe, it is sent to the first recipient. The envelope id is used for managing the envelopes (send reminders; cancel, delete, reject envelope; …).

Envelope Status & Callback


The envelope id can be used any time to receive the envelope status. Therefore you simply call the GetEnvelopeById_v1 with the envelope id.

The following is showing the status response:

<apiResult version="2.2.458.6616">
  <baseResult>ok</baseResult>
  <okInfo>
    <envelopeStatus>
      <id>13ad0518-xxxx-xxxx-xxxx-xxxxxxxxxxx</id>
      <name>eSignAnyWhere Tutorial</name>
      <status>Completed</status>
      <sendDate>2017-03-15T12:13:13.453Z</sendDate>
      <expirationDate>2017-03-17T12:13:13.453Z</expirationDate>
      <bulkRecipients>
        <bulkRecipient eMail="">
          <status>Completed</status>
          <recipients>
            <recipient>
              <orderIndex>1</orderIndex>
              <eMail>first.signer@email.com</eMail>
              <status>Signed</status>
              <signedDate>2017-03-15T12:13:42.717Z</signedDate>
              <recipientType>Signer</recipientType>
              <workstepRedirectionUrl></workstepRedirectionUrl>
            </recipient>
            <recipient>
              <orderIndex>2</orderIndex>
              <eMail>cc@email.com</eMail>
              <status>NotSigned</status>
              <signedDate>2017-03-15T12:13:43.183Z</signedDate>
              <recipientType>Cc</recipientType>
              <workstepRedirectionUrl></workstepRedirectionUrl>
            </recipient>
          </recipients>
          <completedDocuments>
            <logDocumentId>52cba71e-xxxx-xxxx-xxxx-xxxxxxxxxxx</logDocumentId>
            <completedDocument>
              <documentId>77851da5-xxxx-xxxx-xxxx-xxxxxxxxxxx</documentId>
              <fileName>eSignAnyWhere_Tutorial.pdf</fileName>
              <fields />
            </completedDocument>
          </completedDocuments>
        </bulkRecipient>
      </bulkRecipients>
    </envelopeStatus>
  </okInfo>
</apiResult>

Callback

The configured callback URL are used to notify your system if the state of an envelope or workstep is changing. So you can track the status of envelopes, without polling the eSignAnyWhere server regulary.

Download a finished document


To download a finished document you simply call the function DownloadCompletedDocument_v1. You have to use the envelope id and the document id to download the file from the server. The document id you can receive from the response of the GetEnvelopeById_v1 call.

Download response:

<apiResult version="2.2.458.6616">
  <baseResult>ok</baseResult>
  <okInfo>
    <file>
      <name>eSignAnyWhere_Tutorial.pdf</name>
      <data>##BASE64_FILE##</data>
    </file>
  </okInfo>
</apiResult>

Helpful Features and Resources


In this section you find some helpful features or hints you may use after the tutorial.

Print Friendly