Node.js SDK Integration

Integrate IgniSign with your Node.js backend using our official SDK

The IgniSign Node.js SDK provides a convenient way to integrate IgniSign's digital signature capabilities into your Node.js applications. It handles authentication, API calls, and response parsing, allowing you to focus on your business logic.

tip

If you're looking for the quickest way to integrate digital signatures, check out our API Integration Quick Win guide. It covers the simplest implementation path that satisfies 80% of common use cases with minimal code.

Key Advantages

Why use the Node.js SDK over direct API integration:

TypeScript Support

Full TypeScript definitions for better intellisense and type safety

Simplified API

Abstracts complex API interactions into simple method calls

Error Handling

Standardized error handling and meaningful error messages

Webhooks Support

Built-in mechanisms for handling webhook events

Installation

To get started with the IgniSign Node.js SDK, install it via npm or yarn:

npm install @ignisign/public @ignisign/sdk

yarn add @ignisign/public @ignisign/sdk

pnpm add @ignisign/public @ignisign/sdk

Basic Setup

Initialize the SDK with your API key to start using it:

import { IgnisignSdk } from '@ignisign/sdk';
import { IGNISIGN_APPLICATION_ENV } from '@ignisign/public';

// Initialize the SDK
const ignisignSdk = new IgnisignSdk({
apiKey: 'skv2_YOUR_API_KEY',
displayWarning: true
});

// Initialize the SDK (required before using other methods)
async function initializeSDK(): Promise<void> {
try {
  await ignisignSdk.init();
  console.log('IgniSign SDK initialized successfully');
} catch (error) {
  console.error('Failed to initialize IgniSign SDK:', error);
}
}

initializeSDK();

Core Functionality

Working with Documents

Before creating a signature request, you need to upload the documents to be signed:

import * as fs from 'fs';
import * as path from 'path';
import { IgnisignDocument_InitializationDto, IgnisignSdkFileContentUploadDto } from '@ignisign/public';

async function uploadDocument(signatureRequestId: string): Promise<string> {
try {
  // Initialize a document for the signature request
  const initDto: IgnisignDocument_InitializationDto = { 
    signatureRequestId,
    // Optional properties you can set:
    // externalId: "your-external-id",
    // label: "Contract Document",
    // description: "Legal contract for services",
    // templateDisplayerId: "template-id",
    // templateDisplayerVersion: 1
  };
  const { documentId } = await ignisignSdk.initializeDocument(initDto);
  
  // Create a file stream
  const fileStream = fs.createReadStream(path.resolve('./path/to/document.pdf'));
  
  // Upload the document content
  const uploadDto: IgnisignSdkFileContentUploadDto = {
    fileStream,
    fileName: 'contract.pdf',
    contentType: 'application/pdf'
  };
  
  await ignisignSdk.provideDocumentContent_File(documentId, uploadDto);
  
  console.log('Document uploaded successfully:', documentId);
  return documentId;
} catch (error) {
  console.error('Error uploading document:', error);
  throw error;
}
}

Creating a Signature Request

To create a signature request, follow these steps:

import { IgnisignSignatureRequest_UpdateDto, IgnisignSigner_CreationRequestDto } from '@ignisign/public';

async function createSignatureRequest(): Promise<string> {
try {
  // Step 1: Initialize a signature request
  const { signatureRequestId } = await ignisignSdk.initSignatureRequest();
  console.log('Signature request initialized:', signatureRequestId);
  
  // Step 2: Upload document(s)
  const documentId = await uploadDocument(signatureRequestId);
  
  // Step 3: Create signer(s)
  // First create the signer(s) and get their IDs
  const signerDto: IgnisignSigner_CreationRequestDto = {
    signerProfileId: 'your-signer-profile-id', // Get this from getSignerProfiles()
    email: '[email protected]',
    firstName: 'John',
    lastName: 'Doe'
  };
  
  const { signerId } = await ignisignSdk.createSigner(signerDto);
  
  // Step 4: Configure the signature request
  const updateDto: IgnisignSignatureRequest_UpdateDto = {
    title: 'Contract for Services',
    description: 'Please review and sign this contract',
    expirationDate: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // 7 days from now
    expirationDateIsActivated: true,
    documentIds: [documentId], // Include document IDs you've uploaded
    signerIds: [signerId],     // Use the signer IDs you've created
    // Optional properties:
    // externalId: 'your-reference-id',
    // language: 'en',
    // diffusionMode: IGNISIGN_SIGNATURE_REQUEST_DIFFUSION_MODE.EMAIL_ONLY,
  };
  
  await ignisignSdk.updateSignatureRequest(signatureRequestId, updateDto);
  
  // Step 5: Publish the signature request
  const publishResult = await ignisignSdk.publishSignatureRequest(signatureRequestId);
  console.log('Signature request published:', publishResult);
  
  return signatureRequestId;
} catch (error) {
  console.error('Error creating signature request:', error);
  throw error;
}
}

Retrieving Signature Request Status

You can check the status of a signature request at any time:

import { IgnisignSignatureRequest_Context } from '@ignisign/public';

async function getSignatureRequestStatus(signatureRequestId: string): Promise<IgnisignSignatureRequest_Context> {
try {
  const context = await ignisignSdk.getSignatureRequestContext(signatureRequestId);
  console.log('Signature request status:', context.status);
  console.log('Signers status:', context.signers.map(signer => ({
    email: signer.email,
    status: signer.status
  })));
  return context;
} catch (error) {
  console.error('Error getting signature status:', error);
  throw error;
}
}

Working with Signers

Creating a Signer

For some use cases, you may need to create signers in advance:

import { IgnisignSigner_CreationRequestDto, IgnisignSigner_CreationResponseDto } from '@ignisign/public';

async function createSigner(signerProfileId: string, externalId: string = null): Promise<string> {
try {
  const dto: IgnisignSigner_CreationRequestDto = {
    signerProfileId,
    email: '[email protected]',
    firstName: 'John',
    lastName: 'Doe',
    // Optional parameters based on your signer profile requirements:
    // phoneNumber: '+1234567890',
    // birthDate: '1990-01-01',
    // country: 'US',
    // address: '123 Main St',
    // city: 'New York',
    // postalCode: '10001',
    ...(externalId && { externalId })
  };
  
  const result = await ignisignSdk.createSigner(dto);
  console.log('Signer created:', result);
  return result.signerId;
} catch (error) {
  console.error('Error creating signer:', error);
  throw error;
}
}

Getting Signer Profiles

Retrieve available signer profiles to determine what information is required:

import { IgnisignSignerProfile } from '@ignisign/public';

async function getAvailableSignerProfiles(): Promise<IgnisignSignerProfile[]> {
try {
  const profiles = await ignisignSdk.getSignerProfiles();
  console.log('Available signer profiles:', profiles);
  return profiles;
} catch (error) {
  console.error('Error getting signer profiles:', error);
  throw error;
}
}

Advanced Features

Webhooks Integration

Register webhook handlers to receive real-time notifications:

import { 
IGNISIGN_WEBHOOK_ACTION_SIGNATURE_REQUEST,
IGNISIGN_WEBHOOK_MESSAGE_NATURE,
IgnisignWebhook_CallbackParams,
IgnisignWebhookDto_SignatureRequest,
IgnisignWebhook_ActionDto
} from '@ignisign/public';

async function registerWebhookHandlers(): Promise<void> {
// Register a webhook for signature request events
await ignisignSdk.registerWebhookCallback_SignatureRequest(
  // Callback function that will be called when a webhook is received
  async ({ content, error, msgNature, action, topic }: IgnisignWebhook_CallbackParams<IgnisignWebhookDto_SignatureRequest>): Promise<void> => {
    // Handle errors from webhook processing
    if (msgNature === IGNISIGN_WEBHOOK_MESSAGE_NATURE.ERROR) {
      console.error("Webhook error:", error);
      return;
    }
    
    // Process the webhook content
    const { 
      signatureRequestId, 
      signatureRequestExternalId,
      appId,
      appEnv,
      status,
      signers
    } = content as IgnisignWebhookDto_SignatureRequest;
    
    console.log("Signature request launched:", { 
      signatureRequestId, 
      signatureRequestExternalId,
      status
    });
    
    // Your business logic here...
  },
  // Only listen for the LAUNCHED action
  IGNISIGN_WEBHOOK_ACTION_SIGNATURE_REQUEST.LAUNCHED
);

console.log('Webhook handlers registered');
}

// Function to consume webhook events from your API endpoint
async function consumeWebhook(webhookData: IgnisignWebhook_ActionDto): Promise<void> {
await ignisignSdk.consumeWebhook(webhookData);
}

Downloading Signature Proofs

Retrieve signature proofs when signing is complete:

import * as fs from 'fs';
import { Readable } from 'stream';
import { IGNISIGN_SIGNATURE_PROOF_TYPE } from '@ignisign/public';

async function downloadSignatureProof(documentId: string): Promise<string> {
try {
  // Get the signature proof as a readable stream
  const proofStream = await ignisignSdk.downloadSignatureByType(
    documentId, 
    IGNISIGN_SIGNATURE_PROOF_TYPE.PDF_WITH_SIGNATURES
  );
  
  // Save the proof to a file
  const writeStream = fs.createWriteStream('./signature-proof.pdf');
  proofStream.pipe(writeStream);
  
  return new Promise<string>((resolve, reject) => {
    writeStream.on('finish', () => {
      console.log('Signature proof downloaded successfully');
      resolve('./signature-proof.pdf');
    });
    writeStream.on('error', (err) => {
      console.error('Error saving signature proof:', err);
      reject(err);
    });
  });
} catch (error) {
  console.error('Error downloading signature proof:', error);
  throw error;
}
}

Common Issues & Troubleshooting

Here are some common issues developers encounter when working with the IgniSign Node.js SDK:

SDK Initialization Errors

If you encounter issues during initialization:

• Verify that you have called the init() method after creating the SDK instance
• Check that your API key is correct and from the right environment
• Ensure you have installed both @ignisign/public and @ignisign/sdk packages

Request Validation Errors

If you receive validation errors:

• Check all required fields are provided in your requests
• Verify email addresses are in a valid format
• Ensure dates are properly formatted
• Make sure IDs (documentId, signatureRequestId, etc.) are valid

Handling Large Files

When uploading large documents:

• Use streams instead of loading the entire file into memory
• Ensure your network connection is stable
• Consider that very large files may require extended timeouts

Next Steps

Now that you understand how to integrate IgniSign using the Node.js SDK, you might want to explore:

• Webhooks Integration for more details on real-time notifications
• Advanced Integration Patterns for more complex signature workflows
• Node.js SDK GitHub Repository for the complete SDK documentation