Aller au contenu principal

Implémentation Node.js du SDK API Ignisign

Cette documentation vous guide à travers l'implémentation Node.js du SDK API Ignisign, simplifiant l'intégration de l'API Ignisign avec votre backend.

Pré-requis​

Avant de commencer, assurez-vous d'avoir une clé API et des points de terminaison webhook définis. Des instructions détaillées pour les configurer sont disponibles dans la section Intégrer Ignisign avec votre Backend.

Installation​

Installez la bibliothèque via npm :

npm install @ignisign/sdk

En outre, envisagez d'installer le package @ignisign/public, qui inclut tous les types utilisés par la bibliothèque. Bien qu'il s'agisse d'une dépendance transitive de @ignisign/sdk et non obligatoire, l'installer directement peut améliorer votre expérience de développement, notamment pour les mécanismes d'importation IDE.

npm install @ignisign/public

Exemple d'Intégration​

Trouvez un exemple d'intégration dans ce répertoire GitHub.

Initier la Classe IgnisignSdk​

Commencez par initier la classe IgnisignSdk :

import { IgnisignSdk } from "@ignisign/sdk"

const ignisignSdkInstance = new IgnisignSdk({
  appId: IGNISIGN_APP_ID,
  appEnv: (<IGNISIGN_APPLICATION_ENV>IGNISIGN_APP_ENV),
  appSecret: IGNISIGN_APP_SECRET,
  displayWarning: true,
});

Trouvez votre appId, appEnv, et appSecret dans la section "API Keys" de la Console Ignisign. L'environnement d'application doit être l'un des suivants :

enum IGNISIGN_APPLICATION_ENV {
  DEVELOPMENT = "DEVELOPMENT",
  STAGING = "STAGING",
  PRODUCTION = "PRODUCTION",
}

Appels API Faciles​

La classe IgnisignSdk expose tous les points de terminaison API sous forme de méthodes pour un accès facile.

  • Un exemple d'implémentation est disponible ici,
  • Et une description complète des points de terminaison API se trouve dans la Documentation API Ignisign.

Exemple d'Implémentation​

async function createNewSigner(
  signatureProfileId, 
  inputs: { [key in IGNISIGN_SIGNER_CREATION_INPUT_REF] ?: string } = {}, 
  externalId: string = null): Promise<IgnisignSigner_CreationResponseDto> {  

  const dto: IgnisignSigner_CreationRequestDto = {
    signatureProfileId,
    ...inputs,
    ...(externalId && {externalId})
  };

  try {
    return await ignisignSdkInstance.createSigner(dto);
  } catch (error) {
    console.error(error.toString());
    throw error;
  }
}

Lier Votre Point de Terminaison Webhook au SDK Ignisign​

Connectez facilement votre point de terminaison webhook au SDK Ignisign :

router.post('/v1/ignisign-webhook', async (req, res, next) => {
  try {
    const result = await IgnisignSdkManagerSignatureService.consumeWebhook(req.body);
    jsonSuccess(res, result);
  } catch (e) {
    next(e);
  }
});

Le SDK gère la vérification de la signature du webhook et appelle la méthode de rappel appropriée en fonction du type de webhook.

Enregistrement des Callbacks Webhook​

Vous pouvez enregistrer des callbacks pour divers événements webhook, comme décrit dans la Documentation des Événements Webhook.

Exemple d'Enregistrement de Callback Webhook :​

const exampleWebhookCallback = async (
  webhookContext: IgnisignWebhookDto,
  error: IgnisignError = null,
  msgNature?: IGNISIGN_WEBHOOK_MESSAGE_NATURE,
  action?: IGNISIGN_WEBHOOK_ACTION_SIGNATURE_REQUEST,
  topic?: IGNISIGN_WEBHOOK_TOPICS  
): Promise<boolean> => {

  console.log("Received webhook", webhookContext, topic, action, msgNature);
  return true;
};

await ignisignSdkInstance.registerWebhookCallback(
  exampleWebhookCallback,
  IGNISIGN_WEBHOOK_TOPICS.SIGNATURE,
  IGNISIGN_WEBHOOK_ACTION_SIGNATURE.FINALIZED
);

Enregistrement Simplifié des Callbacks Webhook Communs​

Pour simplifier l'implémentation des callbacks webhook fréquemment utilisés, nous avons introduit une série de fonctions "raccourci". Ces fonctions offrent un moyen plus efficace de gérer les scénarios webhook courants. Voici une liste de ces fonctions :

  registerWebhookCallback_Signature(
    callback: IgnisignWebhook_Callback<IgnisignWebhookDto_Signature>, 
    action?: IGNISIGN_WEBHOOK_ACTION_SIGNATURE
  ): Promise<string>;

  registerWebhookCallback_SignatureSession(
    callback: IgnisignWebhook_Callback<IgnisignWebhookDto_SignatureSession>, 
    action?: IGNISIGN_WEBHOOK_ACTION_SIGNATURE_SESSION
  ): Promise<string>;

  registerWebhookCallback_DocumentRequest(
    callback: IgnisignWebhook_Callback<IgnisignWebhookDto_DocumentRequest>, 
    action?: IGNISIGN_WEBHOOK_ACTION_DOCUMENT_REQUEST
  ): Promise<string>;

  registerWebhookCallback_SignatureRequest(
    callback: IgnisignWebhook_Callback<IgnisignWebhookDto_SignatureRequest>, 
    action?: IGNISIGN_WEBHOOK_ACTION_SIGNATURE_REQUEST
  ): Promise<string>;

  registerWebhookCallback_SignatureProfile(
    callback: IgnisignWebhook_Callback<IgnisignWebhookDto_SignatureProfile>, 
    action?: IGNISIGN_WEBHOOK_ACTION_SIGNATURE_PROFILE
  ): Promise<string>;

  registerWebhookCallback_Signer(
    callback: IgnisignWebhook_Callback<IgnisignWebhookDto_Signer>, 
    action?: IGNISIGN_WEBHOOK_ACTION_SIGNER
  ): Promise<string>;

  registerWebhookCallback_SignatureProof(
    callback: IgnisignWebhook_Callback<IgnisignWebhookDto_SignatureProof>, 
    action?: IGNISIGN_WEBHOOK_ACTION_SIGNATURE_PROOF
  ): Promise<string>;

  registerWebhookCallback_SignatureImageGenerated(
    callback: IgnisignWebhook_Callback<IgnisignWebhookDto_SignatureImage>, 
    action?: IGNISIGN_WEBHOOK_ACTION_SIGNATURE_IMAGE
  ): Promise<string>;

  registerWebhookCallback_Application(
    callback: IgnisignWebhook_Callback<IgnisignWebhookDto_Application>, 
    action?: IGNISIGN_WEBHOOK_ACTION_APPLICATION
  ): Promise<string>;

Exemple d'Implémentation​

Voici un exemple pour illustrer comment ces fonctions raccourci peuvent être implémentées :

const webhookHandler_SignatureRequest = async (
    content: IgnisignWebhookDto_SignatureRequest,
    error: IgnisignError = null,
    msgNature?: IGNISIGN_WEBHOOK_MESSAGE_NATURE,
    action?: IGNISIGN_WEBHOOK_ACTION_SIGNATURE_REQUEST,
    topic?: IGNISIGN_WEBHOOK_TOPICS
  ): Promise<any> => {

    if (msgNature === IGNISIGN_WEBHOOK_MESSAGE_NATURE.ERROR) {
      console.error("handleSignatureRequestWebhookSigners ERROR : ", error);
      return;
    }

    console.log("handleSignatureRequestWebhookSigners : ", content);
};

await ignisignSdkInstance.registerWebhookCallback_SignatureRequest(
    webhookHandler_SignatureRequest,  
    IGNISIGN_WEBHOOK_ACTION_SIGNATURE_REQUEST.LAUNCHED
);