...
Table of Contents | ||||
---|---|---|---|---|
|
Upload a file
First, you will need a PDF document which you want to upload.
...
Expand | ||
---|---|---|
| ||
After the authorization you need to BASE64 the PDF which you want to upload. If the call was successful you get a file Id which we will need for sending an envelope. |
Workstep configuration
The workstep configuration is the core of the envelope. Within the workstep configuration you can define following settings:
- AdditionalClientWorkstepInformation
- Viewer preferences
- Policy
- Sender and receiver information
- Workstep tasks
- Signature template
- Authentication
- PdfForms
Empty workstep
Lets start with an empty workstep first and then fill it step by step with the settings above. In the next collapse you can find an empty workstep (change ##EMAIL## to the email-address and ”NAME## to the name of the recipient you want to send the envelope):
...
With this empty workstep configuration we can now add the settings which are mentioned above. First, let us start with the viewer preferences.
Prepare envelope
With the api call: basicURL/envelope/prepare in REST and PrepareSendEnvelopeSteps_v1 in SOAP you can also create a workstep configuration. For this api call you need the FileId and a prepare configuration. You can find a sample configuration in the next section:
...
Expand | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||
For the api call in SOAP you also need the following configuration:
In REST you already have this configuration:
|
AdditionalClientWorkstepInformation
This field is used to provide additional information. Note: Must be written in XML form. See the code below:
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Viewer preferences
Following lines of code show some viewer preferences configurations:
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Policy
The following list shows the policy configurations:
...
As you can see on the right screenshot the recipient of the envelope can now print the document as well as reject the envelope and more.
Client Actions
In this section you can define client actions. For detailed information please have a look at the configuration below.
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Sender and receiver information
Sender information:
Code Block | ||||
---|---|---|---|---|
| ||||
"SenderInformation": { "UserInformation": { "FirstName": "##NAME##", "LastName": "##NAME##", "EMail": "##EMAIL##" } }, }, |
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Receiver information:
Code Block | ||||
---|---|---|---|---|
| ||||
"ReceiverInformation": { "UserInformation": { "FirstName": "##NAME##", "LastName": "##NAME##", "EMail": "##EMAIL##" } }, |
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Workstep task
Every task you add to the envelope you have to add also in the section Tasks in REST and in the following section if you create the envelope with SOAP: <WorkstepTasks>##TASK##</WorkstepTasks>. Furthermore you have to define the signature in the section signature template (only in SOAP):
Signatures
Note: In the StampImprintConfiguration you can define which data should be displayed after signing. So you could set, for example, that the IP address and the name should not be displayed after signing. Please see the next sample for a configuration in which all data is displayed. This is followed by a configuration in which only the date, the transaction token and the transaction id should be displayed.
...
Result (Transaction token, Transaction ID, Signing time):
Click2Sign
This is the simplest signature type, the signer has just to click on the signature field to sing it.
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Draw2Sign
This type allows the signer to draw a signature by mouse, finger or pen. Just an image of the signature is created and embedded into the document.
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Type2Sign
With this type of signature the signer has to type in his/her name to sign the signature field.
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Biometric
Code Block | ||||
---|---|---|---|---|
| ||||
"WorkstepTasks": { "PictureAnnotationMinResolution": 0, "PictureAnnotationMaxResolution": 0, "PictureAnnotationColorDepth": "Color16M", "SequenceMode": "NoSequenceEnforced", "PositionUnits": "PdfUnits", "ReferenceCorner": "Lower_Left", "Tasks": [ { "PositionPage": 1, "Position": { "PositionX": 67.0, "PositionY": 521.92 }, "Size": { "Height": 80.0, "Width": 190.0 }, "AdditionalParameters": [ { "Key": "enabled", "Value": "1" }, { "Key": "positioning", "Value": "intersectsWithField" }, { "Key": "req", "Value": "1" }, { "Key": "fd", "Value": "" }, { "Key": "fd_dateformat", "Value": "dd-MM-yyyy HH:mm:ss" }, { "Key": "fd_timezone", "Value": "datetimeutc" } ], "AllowedSignatureTypes": [ { "IsBio": false, "AllowSkipBiometricVerification": false, "AllowBiometricStoringOnly": false, "SignedResponseWithoutBioData": false, "Id": "6fa90b47-847f-47b1-b73a-9c3802aa077d", "DiscriminatorType": "SigTypeBiometricSignature", "Preferred": true } ], "UseTimestamp": false, "IsRequired": true, "Id": "1#XyzmoDuplicateIdSeperator#Signature_532f40e1-0583-8285-fc50-c2a76dc2fa44", "DisplayName": "", "DocRefNumber": 1, "DiscriminatorType": "Signature" } ] } } }, |
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
After adding the signature fields in the signature template you have to add these signatures in the workstep task section. Following lines of code shows an example configuration of a workstep task.
The Id in the code within the workstep Id must be the same as the Id of the signature field |
Disposable certificate
Code Block | ||||
---|---|---|---|---|
| ||||
{ "SspFileIds": [ "##FILE_ID##" ], "SendEnvelopeDescription": { "Name": "test", "EmailSubject": "Please sign the enclosed envelope", "EmailBody": "Dear #RecipientFirstName# #RecipientLastName#\n\n#PersonalMessage#\n\nPlease sign the envelope #EnvelopeName#\n\nEnvelope will expire at #ExpirationDate#", "DisplayedEmailSender": "", "EnableReminders": true, "FirstReminderDayAmount": 5, "RecurrentReminderDayAmount": 3, "BeforeExpirationDayAmount": 3, "DaysUntilExpire": 28, "CallbackUrl": "", "StatusUpdateCallbackUrl": "", "LockFormFieldsAtEnvelopeFinish": true, "Steps": [ { "OrderIndex": 1, "Recipients": [ { "Email": "##EMAIL##", "FirstName": "##NAME##", "LastName": "##NAME##", "LanguageCode": "en", "EmailBodyExtra": "", "DisableEmail": false, "AddAndroidAppLink": false, "AddIosAppLink": false, "AddWindowsAppLink": false, "AllowDelegation": false, "AllowAccessFinishedWorkstep": false, "SkipExternalDataValidation": false, "AuthenticationMethods": [], "DisposableCertificateData": { "CountryResidence": "AT", "IdentificationCountry": "AT", "IdentificationType": "PASSPORT", "PhoneMobile": "##PHONENUMBER##", "DocumentType": "PASS", "DocumentIssuedBy": "Namirial", "DocumentIssuedOn": "2020-07-07T00:00:00Z", "DocumentExpiryDate": "2020-07-29T00:00:00Z", "SerialNumber": "1234", "DocumentNumber": "123", "OverrideHolderInCaseOfMismatch": false } } ], "EmailBodyExtra": "", "RecipientType": "Signer", "WorkstepConfiguration": { "WorkstepLabel": "test", "SmallTextZoomFactorPercent": 100, "FinishAction": { "ServerActions": [], "ClientActions": [ { "RemoveDocumentFromRecentDocumentList": false, "CallClientActionOnlyAfterSuccessfulSync": true, "ClientName": "SIGNificant SignAnywhere", "CloseApp": false, "Action": "https://www.esignanywhere.net/" } ] }, "ReceiverInformation": { "UserInformation": { "FirstName": "##NAME##", "LastName": "##NAME##", "EMail": "##EMAIL##" }, "HolderInformation": "<recognitionType>PASS</recognitionType><documentIssuedOn>07/07/2020</documentIssuedOn><documentExpiryDate>29/07/2020</documentExpiryDate><documentIssuedBy>Namirial</documentIssuedBy><documentNumber>123</documentNumber><countryResidence>AT</countryResidence><firstName>##NAME##</firstName><lastName>##NAME##</lastName><email>##EMAIL##</email><phoneMobile>##PHONENUMBER##</phoneMobile><identificationType>PASSPORT</identificationType><identificationCountry>AT</identificationCountry><passport>1234</passport>", "TransactionCodePushPluginData": [] }, "SenderInformation": { "UserInformation": { "FirstName": "##NAME##", "LastName": "##NAME##", "EMail": "##EMAIL##" } }, "TransactionCodeConfigurations": [ { "Id": "smsAuthTransactionCodeId", "HashAlgorithmIdentifier": "Sha256", "Texts": [ { } ] } ], "SignatureConfigurations": [], "ViewerPreferences": { "FinishWorkstepOnOpen": false, "VisibleAreaOptions": { "AllowedDomain": "*", "Enabled": false } }, "ResourceUris": {}, "AuditingToolsConfiguration": { "WriteAuditTrail": false, "NotificationConfiguration": {} }, "Policy": { "GeneralPolicies": { "AllowSaveDocument": true, "AllowSaveAuditTrail": true, "AllowRotatingPages": false, "AllowEmailDocument": true, "AllowPrintDocument": true, "AllowFinishWorkstep": true, "AllowRejectWorkstep": true, "AllowRejectWorkstepDelegation": false, "AllowUndoLastAction": true, "AllowAdhocPdfAttachments": false, "AllowAdhocSignatures": false, "AllowAdhocStampings": false, "AllowAdhocFreeHandAnnotations": false, "AllowAdhocTypewriterAnnotations": false, "AllowAdhocPictureAnnotations": false, "AllowAdhocPdfPageAppending": false }, "WorkstepTasks": { "PictureAnnotationMinResolution": 0, "PictureAnnotationMaxResolution": 0, "PictureAnnotationColorDepth": "Color16M", "SequenceMode": "NoSequenceEnforced", "PositionUnits": "PdfUnits", "ReferenceCorner": "Lower_Left", "Tasks": [ { "PositionPage": 1, "Position": { "PositionX": 89.0, "PositionY": 575.0 }, "Size": { "Height": 80.0, "Width": 190.0 }, "AdditionalParameters": [ { "Key": "enabled", "Value": "1" }, { "Key": "positioning", "Value": "onPage" }, { "Key": "req", "Value": "1" }, { "Key": "fd", "Value": "" }, { "Key": "fd_dateformat", "Value": "dd-MM-yyyy HH:mm:ss" }, { "Key": "fd_timezone", "Value": "datetimeutc" }, { "Key": "spcId", "Value": "padesSigningId" } ], "AllowedSignatureTypes": [ { "TrModType": "RemoteSignatureDisposableCertificate", "TrValidityInSeconds": 300, "Ly": "remoteCertificate", "TrConfIdIssueCertificate": "disposableCertificateEnrolAndSignSmsText", "TrConfId": "remoteCertificateSignSmsText", "IsPhoneNumberRequired": false, "Id": "180c4201-4146-4161-baf8-cb5a607eec62", "DiscriminatorType": "SigTypeTransactionCode", "Preferred": false, "StampImprintConfiguration": { "DisplayExtraInformation": true, "DisplayEmail": true, "DisplayIp": true, "DisplayName": true, "DisplaySignatureDate": true, "FontFamily": "Times New Roman", "FontSize": 11.0 } } ], "UseTimestamp": false, "IsRequired": true, "Id": "1#XyzmoDuplicateIdSeperator#Signature_b58c192b-47c0-5339-cb18-4fe77c3d1812", "DisplayName": "", "DocRefNumber": 1, "DiscriminatorType": "Signature" } ] } }, "Navigation": { "HyperLinks": [], "Links": [], "LinkTargets": [] } }, "DocumentOptions": [ { "DocumentReference": "1", "IsHidden": false } ], "UseDefaultAgreements": true }, { "OrderIndex": 2, "Recipients": [ { "Email": "##EMAIL##", "FirstName": "##NAME##", "LastName": "##NAME##", "LanguageCode": "en", "EmailBodyExtra": "", "DisableEmail": false, "AddAndroidAppLink": false, "AddIosAppLink": false, "AddWindowsAppLink": false, "AllowDelegation": false, "SkipExternalDataValidation": false, "AuthenticationMethods": [] } ], "EmailBodyExtra": "", "RecipientType": "Cc", "DocumentOptions": [], "UseDefaultAgreements": false } ], "AddFormFields": { "Forms": {} }, "OverrideFormFieldValues": { "Forms": {} }, "AttachSignedDocumentsToEnvelopeLog": false } } |
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
P7M Signers
Info |
---|
It is possible to define P7M signers in eSignAnyWhere (version 3.1+). This allows you to define at the end of a signing workflow to define signers with P7M. Due technical reasons it is not possible to add non-P7M signers after the first P7M signer. P7M is an advanced feature and must be enabled for you, so please contact your Namirial Sales |
...
Code Block | ||||
---|---|---|---|---|
| ||||
<WorkstepTasks SequenceMode="SequenceOnlyRequiredTasks"> <Task enabled="1" completed="0" required="0" id="pkcs1" displayName="" DocRefNumber="1" type="SignPkcs7" finishPercentage="0" /> </WorkstepTasks> EnvelopeDocumentInforamtion <WorkStepInformation> ... <EnvelopeInformation> <EnvelopeDocumentInformation numberOfPages="1" DocRefNumber="1" name="" isOptionalDocument="0" isPkcs7="0" enabled="1" /> <EnvelopeDocumentInformation numberOfPages="1" DocRefNumber="2" name="" isOptionalDocument="0" isPkcs7="0" enabled="1" /> <EnvelopeDocumentInformation numberOfPages="1" DocRefNumber="3" name="" isOptionalDocument="0" isPkcs7="0" enabled="1" /> </EnvelopeInformation> ... </WorkStepInformation> |
Automatic Remote Signature Recipient via API
Via API you have to use a new recipient type (“Automatic”). Moreover the workstepConfiguration must contain information about the automatic remote signature. As additional option, you can use more than one profile for the workstep configuration at once via API. Note: this leads to a missing information in eSAW UI!
...
Code Block | ||||
---|---|---|---|---|
| ||||
<Policy version="1.1.0.0"> <FinalizeActions> <AutomaticSignature sigId="GENERIC_SIG_IDENTIFIER" /> </FinalizeActions> </Policy> |
A-Trust
Info |
---|
Note: For the A-Trust signature configuration you need an A-Trust Signaturbox first. For more information please contact us. |
...
If you enter the phone number then the recipient can not enter another number. However, if you do not define a phone number then the recipient is free to choose a phone number of their choice.
BankID
In this section you can find the configuration for the bankID signature. First we have to upload a PDF. After uploading the document we can now send the document with the following workstep configuration to define the bankID signature:
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Generic Signing Plugin
In this section you can find the configuration for the generic signing plugin signature. First we have to upload a PDF. After uploading the document we can now send the document with the following workstep configuration to define the plugin signature:
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Generic Signing Plugin (automatic)
In this section you can find the configuration for an automatic generic signing plugin signature. Please see the following workstep configuration for more information:
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Generic Signing Plugin (Batch-Signature)
In this section you can find the configuration for a batch generic signing plugin signature. Please see the following workstep configuration for more information:
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Authentication
You can add different authentications for the recipient to ensure that only the one who has the code/phone number can open the envelope. Following list shows the different authentications:
...
In the next two collapses you can find the configuration for the Pin-authentication and for the SMS-authentication:
Pin-authentication
Code Block | ||||
---|---|---|---|---|
| ||||
{ "Method": "Pin", "Parameter": "1234" } |
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
SMS-authentication
Code Block | ||||
---|---|---|---|---|
| ||||
{ "Method": "Sms", "Parameter": "+0123456789" } |
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
PdfForms
The following list shows you all different form fields which can be placed on the document:
...
Info |
---|
There are two configurations to do:
This applies to all form fields. |
Textfield
Code Block | ||||
---|---|---|---|---|
| ||||
"Forms": [ { "Id": "TextBox_3daf9a88-bf45-70af-99d0-c077bcb48245", "PositionPage": 1, "DocRefNumber": 1, "Position": { "PositionX": 77.0, "PositionY": 590.0 }, "Size": { "Height": 20.0, "Width": 124.0 }, "DiscriminatorType": "TextBox" } ], "IsRequired": false, "Id": "f390ebd3-4b9c-4554-ab61-4d1234bad681", "DisplayName": "", "DocRefNumber": 1, "DiscriminatorType": "FormGroup" }, |
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Radiobutton
Code Block | ||||
---|---|---|---|---|
| ||||
{ "RadioButtonGroupId": "RadioButton_942fca6a-5e0e-7694-b858-b5ded711ed0b", "Id": "0", "PositionPage": 1, "DocRefNumber": 1, "Position": { "PositionX": 77.0, "PositionY": 553.0 }, "Size": { "Height": 20.0, "Width": 20.0 }, "DiscriminatorType": "RadioButton" }, |
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Checkbox
Code Block | ||||
---|---|---|---|---|
| ||||
{ "IsRequired": false, "RequiredEvalPolicy": "None", "Id": "CheckBox_41371eaf-6e1a-0d9a-58a9-0705fd8d08d1", "PositionPage": 1, "DocRefNumber": 1, "Position": { "PositionX": 77.0, "PositionY": 520.0 }, "Size": { "Height": 20.0, "Width": 20.0 }, "DiscriminatorType": "CheckBox" }, |
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Listbox
Code Block | ||||
---|---|---|---|---|
| ||||
{ "Items": [], "Id": "ListBox_d51c4e55-2497-8ab4-f2c8-6f60ac6a2cfd", "PositionPage": 1, "DocRefNumber": 1, "Position": { "PositionX": 79.0, "PositionY": 475.0 }, "Size": { "Height": 30.0, "Width": 150.0 }, "DiscriminatorType": "ListBox" }, |
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Listbox (Multiselect)
In the workstep configuration you can also define to select multiple items in the listbox. To define a multiselect of items you have to have at least two items in the listbox and you have to activate multiselect for this listbox. Please see the configurations below for more information:
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Combobox
Code Block | ||||
---|---|---|---|---|
| ||||
{ "IsRequired": false, "Items": [], "Id": "ComboBox_67a8d39f-3a49-65e0-0d5d-88ac97b387ea", "PositionPage": 1, "DocRefNumber": 1, "Position": { "PositionX": 79.0, "PositionY": 424.0 }, "Size": { "Height": 30.0, "Width": 150.0 }, "DiscriminatorType": "ComboBox" } |
...
After the configuration of the section “PdfForms” you can add these form fields in the section “addFormFields”.
AddFormFields
Textfield:
Code Block | ||||
---|---|---|---|---|
| ||||
{ "Value": "", "MaxLength": -1, "IsMultiline": false, "IsPassword": false, "IsComb": false, "TextColor": "0, 0, 0", "FontSize": 11.0, "FontName": "Times New Roman", "Bold": false, "Italic": false, "TextAlign": "Left", "Name": "TextBox_3daf9a88-bf45-70af-99d0-c077bcb48245", "ReadOnly": false, "Required": false, "X": 77.0, "Y": 590.92, "Width": 124.0, "Height": 20.0, "Page": 1, "DiscriminatorType": "AddTextBoxFormFieldDescriptor" }, |
...
Expand | ||
---|---|---|
| ||
Please do not forget to add a workstep task for the form fields. |
TypeWriterAnnotation
The following lines of code show you how to write the configuration. First, you have to define the task:
...
For all placeholder with the additional “*” you need either the sender information or the receiver information which are both explained in the section “sender and receiver information”.
Reading Tasks
...
With the reading task a recipient must confirm reading the document to have the evidence that he/she was reading it.
Generally there are 3 basic ways concerning the range of the reading task:
- Reading task for one page
- Reading task for all pages
- Reading task for a section
Reading task for one page
Note: The reading task must be the first task and it must be required!)
...
As you can see, just the first page needs a reading confirmation.
Reading task for all pages
The following lines of code shows you the reading task configuration for all pages:
...
The result should look like the following screenshot:
Reading task for a section
The following lines of code shows you how to configure the reading task for a section:
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Sending envelope
After you have added all form fields and signatures you can send the envelope to recipients. Therefore, add the file Id and the workstep configuration to the REST call basicURL/envelope/send or in SOAP to the API call SendEnvelope_v1 and send the envelope to the recipients.
Get the envelope
After sending the envelope you can call the api call (basicURL/envelope{envelopeId}) in REST and GetEnvelopeById_v1 in SOAP.
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Download the document(s)
With the following URI you can download the documents: basicURL/envelope/downloadCompletedDocument/{documentId} in REST and DownloadCompletedDocument_v1 in SOAP.
...