Mekari eSign API JS SDK (Unofficial)

Note: This is an unofficial SDK and is not affiliated with or supported by Mekari.

The esign-api-js SDK is a JavaScript library that provides a convenient way to interact with the Mekari eSign API. It simplifies the process of integrating eSign functionality into your JavaScript/Node.js applications.

With this SDK, you can easily manage documents, signatures, e-meterai, eKYC, and user profiles.

Installation

Install the SDK via npm:

npm install esign-api-js

Initialization

You can initialize the SDK with either OAuth2 (for user-based apps) or HMAC (for server-to-server integration).

Option 1: OAuth2 Authentication (Default)

Suitable for applications where users log in to Mekari eSign to grant access.

const { eSignAPi } = require('esign-api-js');

const client = new eSignAPi({
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
    sandbox: true, // Set to false for production
    // authType: 'oauth' // Default
});

Option 2: HMAC Authentication

Suitable for backend services where you sign requests with your credentials directly.

const { eSignAPi } = require('esign-api-js');

const client = new eSignAPi({
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
    sandbox: true,
    authType: 'hmac' // REQUIRED for HMAC
});

Authentication (OAuth Only)

If using OAuth, you need to obtain an accessToken first.

1. Generate Auth URL: Redirect user to this URL to login.

   const authUrl = client.auth.authUrl();
   console.log('Login URL:', authUrl);

2. Exchange Code for Token: After login, use the returned code to get an access token.

   const response = await client.auth.requestAuthToken('CODE_FROM_CALLBACK');
   const accessToken = response.access_token;

Note: For HMAC, you don't need to manage access tokens manually; authentication headers are generated automatically per request.

Usage Examples

1. User Profile & Quota

Check user information and remaining balance (e-meterai quota).

const profile = await client.profile.getProfile(accessToken);
console.log('Balance:', profile.data.remaining_emeterai_balance);

2. Document Management

Create & Request Sign (Global)

const document = await client.documents.createGlobalDocument(accessToken, {
  doc: 'base64_encoded_pdf_string...', // Base64 string of the PDF
  filename: 'contract.pdf',
  signers: [
    {
      name: 'John Doe',
      email: '[email protected]',
      annotations: [
        {
          page: 1,
          type_of: 'signature',
          position_x: 100,
          position_y: 100,
          canvas_width: 595,
          canvas_height: 842,
          element_width: 100,
          element_height: 50
        }
      ]
    }
  ],
  signing_order: false,
  callback_url: 'https://your-webhook.com/callback'
});

List Documents

const docs = await client.documents.getAll({
  page: 1,
  limit: 10,
  signing_status: 'waiting' // optional: waiting, signed, rejected
}, accessToken);

List Documents in Folder

const folderDocs = await client.documents.getAllInFolder('folder_id_123', {
  page: 1, 
  limit: 10
}, accessToken);

Get Document Detail

const doc = await client.documents.getById('document_id_123', accessToken);

Download Document

const result = await client.documents.downloadDocument('document_id_123', accessToken);
// Returns download URL or content depending on API response

Void, Resend, or Delete

// Void
await client.documents.voidDocument('document_id_123', 'Reason for voiding', accessToken);

// Resend Notification
await client.documents.resendDocument('document_id_123', accessToken);

// Delete
await client.documents.deleteDocument('document_id_123', accessToken);

3. Advanced Features

Bulk Sign

Sign multiple envelopes/documents at once.

await client.documents.bulkSign({
  envelope_ids: ['doc_id_1', 'doc_id_2'],
  signature_base64: 'base64_image_of_signature...'
}, accessToken);

Annotation Placement

Place stamps/signatures on an existing document.

await client.documents.annotationPlacement('document_id_123', {
  base64_doc: 'base64_string...',
  filename: 'stamped.pdf',
  signers: [ ... ] // similar structure to createGlobalDocument
}, accessToken);

4. eKYC (Identity Verification)

Request eKYC

const ekycRequest = await client.ekyc.requestEkyc({
  param1: 'value', // Refer to API docs for required eKYC params
  // ...
}, accessToken);

Check eKYC Status

const status = await client.ekyc.getEkycStatus('[email protected]', 1, 10, accessToken);

5. Stamping (e-Meterai)

Directly stamp a document with e-meterai.

await client.stamping.stamp({
  doc: 'base64_pdf...',
  filename: 'doc.pdf',
  annotation: {
    page: 1,
    position_x: 100,
    position_y: 100,
    canvas_width: 595,
    canvas_height: 842
  }
}, accessToken);

Disclaimer

This SDK is an unofficial library and is not directly supported by or affiliated with Mekari. It is developed by the community for the community. Use it at your own risk.

License

This project is licensed under the MIT License. You are free to use, modify, and distribute this software. Contributions are welcome!