AlphaTrust e-SignAppearance
Creating a Simple Transaction
When creating a transaction (i.e. getting a document signed), there are four main objects that need to be defined: the Transaction, the Participant, the Document, and the Task.
Transaction
The main object that encapsulates all the other objects
Document
A PDF or HTML file that is getting signed by, approved by, or delivered to the Participant.
Participant
The user that is participating in the transaction (i.e. the person signing the document)
Task
What the Participant is doing in the document (e.g. signing, approving, delivering, etc.)Transaction
The first step would be to set up the Transaction which is done through the TransactionCreateModel.
csharp
var t = new TransactionCreateModel();
t.IsTest = true;
t.Description = "My First Transaction Test";
t.ProntoID = "Default";Participant
Next we'll need to define and add in the Participant to the Transaction using the ParticipantInsertModel.
csharp
var participant = new ParticipantInsertModel();
participant.FullName = "John Smith";
participant.EmailAddress = "testing@alphatrust.com";
participant.SendRequestViaEmail = true;
// if you have more than one Participant, you can add them all into the array here
t.Participants = new List<object> { participant };Document
Next we'll need to define and add in the Document to the Transaction using the DocumentInsertModel.
csharp
var document = new DocumentInsertModel();
document.Title = "My Test Document";
var src = new SourceModel();
//point this path to a value PDF
src.FileBytes = System.IO.File.ReadAllBytes(@"C:\MyDocument.pdf");
document.Source = src;
// if you have more than one Document, you can add them all into the array here
t.Documents = new List<object> { document };Task
Next we'll need to define the Task using the TaskInsertModel along with the SignatureBlockModel, the SignatureModel, and the PdfSignaturePlacementModel. The latter three are optional for refined signature placement and configurations. However, it is highly recommended that you use these additional configurations for most scenarios.
csharp
// initialize all of the necessary Task objects
var task = new TaskInsertModel();
var sigBlock = new SignatureBlockModel();
var sig = new SignatureModel();
var placement = new PdfSignaturePlacementModel();
// define what type of task to use in the document
task.Type = TaskInsertModel.TypeEnum.Signature;
// define the how the signature is applied on the document
sig.ApplicationType = SignatureModel.ApplicationTypeEnum.FontStamped;
sig.IsBold = true;
sig.IsItalic = true;
// define where in the document the signature is placed
placement.PageCoordinatesPageNumber = 1;
placement.XOffset = 20;
placement.YOffset = 20;
// assign all of the properties back up into the task
sig.PdfPlacement = placement;
sigBlock.Signature = sig;
task.SignatureBlock = sigBlock;
// then we need to assign the Task to the Document and the Participant
document.Tasks = new List<object> { task };
participant.Tasks = new List<object> { task };Finalizing the Service Request
As described here in more detail, all service methods require the Service Authentication values to be included.
csharp
var apiKey = "MyCompanyInc";
var apiSecret = "4dda426f-134f-4a55-9dff-40f4c227e1a0";
var apiUsername = "my-api-user";
var apiPassword = "17334bae-5eff-4ee1-9a96-fa5dde6cbfc9";Most service methods allow an array of objects to be passed in which enables you, in this instance, to create multiple transactions with one call. In this demo, we will just be creating one transaction. However, we will still need to pass that one transaction into an array before we pass it into the service method.
csharp
var transactionList = new List<object> { t };Now that we have all of the required objects defined, we just need to wrap them up in the request object. When creating new transactions, that request object is the TransactionCreateRequestModel. This request object allows you to include additional features to be include with the request and the response that are outside the Transaction object's responsibility. The properties are EnableLogging and the ResponseIncludes. The latter property will allow fine-grained control as to what gets returned in the response to the service call using, in this scenario, the TransactionIncludesModel.
DANGER
Do not set EnableLogging=true when your code is in a production environment as your account may be deactivated until it's disabled.
csharp
var req = new TransactionCreateRequestModel();
req.EnableLogging = true;
req.Transactions = transactionList;
// If you need additional properties returned (i.e. ParticipantID or signing URL),
// you can define those to be included in the response as well here:
// req.ResponseIncludes = DefineIncludes();Include these properties in the CreateTransactions() service method and handle the results as detailed in the Default Service Return Properties section.
csharp
var myRestEndpointUrl = "https://my-esign-domain.com/rest";
var api = new TransactionsApi(myRestEndpointUrl);
var results = await api.CreateTransactionsAsync(req, apiKey, apiSecret, apiUsername, apiPassword);
if (results.IsSuccessful.Value)
{
// do work...
}
else
{
// handle error
}Putting it all together
Now that we've described each piece in detail, below is the full source code for the example.
csharp
var t = new TransactionCreateModel();
t.IsTest = true;
t.Description = "My First Transaction Test";
t.ProntoID = "Default";
var participant = new ParticipantInsertModel();
participant.FullName = "John Smith";
participant.EmailAddress = "testing@alphatrust.com";
participant.SendRequestViaEmail = true;
// if you have more than one Participant, you can add them all into the array here
t.Participants = new List<object> { participant };
var document = new DocumentInsertModel();
document.Title = "My Test Document";
var src = new SourceModel();
// point this path to a value PDF
src.FileBytes = System.IO.File.ReadAllBytes(@"C:\MyDocument.pdf");
document.Source = src;
// if you have more than one Document, you can add them all into the array here
t.Documents = new List<object> { document };
// initialize all of the necessary Task objects
var task = new TaskInsertModel();
var sigBlock = new SignatureBlockModel();
var sig = new SignatureModel();
var placement = new PdfSignaturePlacementModel();
// define what type of task to use in the document
task.Type = TaskInsertModel.TypeEnum.Signature;
// define the how the signature is applied on the document
sig.ApplicationType = SignatureModel.ApplicationTypeEnum.FontStamped;
sig.IsBold = true;
sig.IsItalic = true;
// define where in the document the signature is placed
placement.PageCoordinatesPageNumber = 1;
placement.XOffset = 20;
placement.YOffset = 20;
// assign all of the properties back up into the task
sig.PdfPlacement = placement;
sigBlock.Signature = sig;
task.SignatureBlock = sigBlock;
// then we need to assign the Task to the Document and the Participant
document.Tasks = new List<object> { task };
participant.Tasks = new List<object> { task };
// The values below will vary for your server's configuration
var apiKey = "MyCompanyInc";
var apiSecret = "4dda426f-134f-4a55-9dff-40f4c227e1a0";
var apiUsername = "my-api-user";
var apiPassword = "17334bae-5eff-4ee1-9a96-fa5dde6cbfc9";
var transactionList = new List<object> { t };
var req = new TransactionCreateRequestModel();
req.EnableLogging = true;
req.Transactions = transactionList;
// If you need additional properties returned (i.e. ParticipantID or signing URL),
// you can define those to be included in the response as well here:
// req.ResponseIncludes = DefineIncludes();
var myRestEndpointUrl = "https://my-esign-domain.com/rest";
var api = new TransactionsApi(myRestEndpointUrl);
var results = await api.CreateTransactionsAsync(req, apiKey, apiSecret, apiUsername, apiPassword);
if (results.IsSuccessful.Value)
{
// do work...
}
else
{
// handle error
}Sample Code