Feature OverviewJava SDK .NET SDK REST API APEX SDK

Présentation des fonctionnalités

L'extraction de balises de texte permet aux intégrateurs d'extraire automatiquement des signatures et des champs en plaçant des balises de texte dans un document. OneSpan Sign analysera le document téléchargé et remplacera chaque texte qui correspond au modèle de balise de texte par la signature ou le champ approprié.

Cette section aborde les points suivants :

• Text Tag Syntax

• Role Names in Text Tags

• Text Tag Types

• Text Tag Parameters

• Signer with Multiple Signatures

Bonnes pratiques pour l'utilisation des balises de texte

Voici quelques bonnes pratiques que vous devez garder à l'esprit lorsque vous utilisez des balises de texte :

• Lorsque vous avez plusieurs attributs spécifiés dans des balises de texte, essayez d'utiliser une virgule pour les séparer, comme ci-dessous :

  • {{esl :Signer1 :textfield :size(40,15),Maxlen(3)}}

  Un exemple plus compliqué pourrait ressembler à :

  • {{esl_checkbox1 :Signer1 :checkbox :offset(0,-15),size(275,25),Maxlen(40)}

• Essayez d'utiliser une police plus petite pour vos balises de texte. Cela vous permettra d'économiser de l'espace et d'éviter d'affecter la mise en page de votre contenu.

• Assurez-vous que votre balise de texte est sur une ligne.

Voici un exemple de code qui intègre ces suggestions :

{{esl_optionA :Signer1 :Radio :Group(« Fréquence »),Valeur(« X »),taille(10,10),décalage(40,-8)}}
{{esl_optionB :Signer1 :Radio :Group(« Fréquence »),Valeur(«  »),taille(10,10),décalage(40,-8)}}
{{esl_optionC :Signer1 :Radio :Group(« Fréquence »),Valeur(«  »),taille(10,10),décalage(40,-8)}}

Dans cet exemple, la taille des balises est définie sur 1 et la taille du texte normal est définie sur 12. Voici ce que vous obtenez après l'extraction dans ces champs :

Pour obtenir une copie du document Word utilisé dans cet exemple, cliquez sur here.

Si vous rencontrez des problèmes pour placer vos balises de texte à leur bon emplacement, essayez d'utiliser l'attribut offset. Ceci est particulièrement utile lors de l'utilisation d'un document Microsoft Word.

Syntaxe de la balise de texte

La ligne suivante illustre la syntaxe d'une balise Text :

• {{Xesl[_fieldName]:roleName:fieldType[:parameter1,parameter2,...]}}

Les noms de champ sont alphanumériques. Ils ne peuvent pas contenir de caractères spéciaux autres que le trait de soulignement (_).

Notez à partir de cette ligne que :

• Le début et la fin d'une balise de texte sont entourés d'accolades doubles. Les accolades ne doivent apparaître nulle part ailleurs dans une balise de texte.

• Le troisième caractère — le — est un X espace réservé pour un caractère facultatif. Ce caractère peut être un point d'interrogation (?) ou un astérisque (*). Un astérisque indique qu'un champ de saisie est requis. Un point d'interrogation indique qu'un champ de saisie est facultatif. Le point d'interrogation est la valeur par défaut, c'est-à-dire que si aucun caractère n'est présent, un champ de saisie sera facultatif. Exemple: {{*esl:Signer1:textfield}}

• fieldName est le nom du champ qui sera créé par la balise de texte (une signature, un champ automatique ou un champ de saisie) — voir Text Tag Types. S'il est spécifié, ce paramètre suivra le préfixe « esl ». Les noms de champ sont alphanumériques. Ils ne peuvent pas contenir de caractères spéciaux autres que le trait de soulignement (_). Si vous prévoyez de récupérer la valeur saisie lors de l'expérience du signataire, entrez un nom unique par champ. Exemple : {{esl_SignerAutograph:Signer1:Signature}}

• roleName est le nom du rôle associé au signataire prévu. Pour trouver le nom de rôle que vous devez utiliser, reportez-vous à la section Role Names in Text Tags.

• fieldType est l'un des types de champs décrits dans la section Text Tag Types.

• parameter1 et parameter2 sont des paramètres décrits dans Text Tag Parameters.

Veuillez tenir compte de ce qui suit :

• Une balise de texte ne peut pas apparaître sur plusieurs lignes.

• Si une liste de paramètres est présente, il doit s'agir d'une liste séparée par des virgules.

La ligne suivante illustre la syntaxe valide la plus courte pour une balise de texte :

{{esl:roleName:fieldType}}

Noms de rôle dans les balises de texte

Si vous créez une transaction à l'aide de l'interface utilisateur Web de OneSpan Sign, le nom de rôle de l'expéditeur est toujours Propriétaire.

Si vous créez un signataire « Destinataire » ou un signataire de groupe à l'aide de OneSpan Sign, le nom de rôle du signataire est Signataire#, où # commence à 1 et augmente d'une unité pour chaque signataire. Le # le plus bas disponible est utilisé pour chaque nouveau signataire. Ainsi, si vous supprimez le signataire avec le nom de rôle Signataire1 , puis ajoutez un nouveau signataire, le nom de rôle du nouveau signataire sera Signataire1.

Si vous créez un signataire d'espace réservé et que vous le nommez Client, Client sera le nom du rôle. Le client restera le nom de rôle lorsque cet espace réservé sera remplacé ultérieurement par un destinataire ou un groupe spécifique.

Si vous créez un signataire à l'aide du SDK et que vous attribuez un ID personnalisé à ce signataire, cet ID sera le nom de rôle du signataire. Si vous n'attribuez pas d' ID personnalisé au signataire, celui-ci est généré à l'aide des mêmes règles que lors de l'utilisation de l'interface utilisateur Web de OneSpan Sign.

Types de balises de texte

Il existe trois principaux types de balises de texte :

• Signatures

• Autofields

• Input Fields

Signatures

Une balise de texte de signature particulière peut être l'un des types de champs suivants :

• Signature — Ce bloc de signature est la option Cliquer pour signer. Le nom du signataire sera tamponné sur le bloc cliqué.

• Initiales : ce bloc de signature est Click-to-Initial. Les initiales du signataire seront estampillées sur le bloc cliqué.

• Capture : le signataire clique sur ce bloc de signature et dessine sa signature à l'aide d'une souris ou d'un autre périphérique d'entrée. Le signataire peut également choisir de signer sur un appareil mobile tel qu'un smartphone si l'expéditeur a activé la capture mobile sur son compte. Le dessin est ensuite estampillé sur le bloc de signature. Notez que l'utilisation d'un stylet n'est pas prise en charge dans l'interface utilisateur classique.

• Mobile_Capture — Pour signer électroniquement ce bloc de signature, le signataire recevra un lien par e-mail qui le redirigera vers l'ouverture du document sur son téléphone portable. Ils doivent ensuite dessiner leur signature à l'aide de leur doigt ou d'un stylet. Le dessin de la signature est ensuite tamponné sur le bloc. Notez que l'utilisation d'un stylet n'est pas prise en charge dans l'interface utilisateur classique.

Champs automatiques

Une balise de texte de champ automatique particulière peut être de l'un des types de champ suivants :

• SignerName : au moment de la signature, le système remplit automatiquement ce champ avec le nom complet du signataire.

• SignerTitle : si le titre du signataire est disponible, le système remplit automatiquement ce champ avec ce titre au moment de la signature. Sinon, le champ est laissé vide.

• SignerCompany — Si le nom de l'entreprise du signataire est disponible, le système remplit automatiquement ce champ avec ce nom au moment de la signature. Sinon, le champ est laissé vide.

• SigningDate — Au moment de la signature, le système remplit automatiquement ce champ avec la date du jour.

Champs de saisie

Une balise de texte de champ de saisie particulière peut être l'un des types de champ suivants :

• TextField — Cette zone accepte tout texte saisi par le signataire avant la signature.

• TextArea : il est similaire au type TextField , en ce sens qu'il fournit une zone où le texte libre peut être saisi par les signataires. Cependant, contrairement aux champs de texte, il fournit un retour automatique à la ligne. Chaque zone de texte peut accepter jusqu'à 4000 caractères.

• Liste — Ce menu déroulant permet de sélectionner l'une des nombreuses options.

• Radio — Les boutons radio permettent également de sélectionner l'une des nombreuses options.

• Case à cocher : avant de signer, le signataire peut sélectionner ou décocher cette simple case à cocher.

• Étiquette : l'expéditeur du package peut ajouter un champ d'étiquette pour incorporer du texte dans un document. Il s'agit d'un champ en lecture seule avec une valeur qui sera simplement tamponnée sur le PDF. Pendant l'expérience du signataire, le champ d'étiquette s'affiche sous forme de texte non modifiable.

Paramètres de balise de texte

Lors de la création d'une balise de texte, le système utilise les paramètres décrits dans le tableau suivant.

• Le décalage et la taille sont utilisés pour les trois types de balises de texte.

• Les autres paramètres de la table sont utilisés uniquement pour les types de champs d'entrée .

• Tous les paramètres du tableau suivant sont facultatifs.

Si des guillemets sont obligatoires dans n'importe quel paramètre du tableau suivant, vous devez utiliser des guillemets droits. Vous ne pouvez pas utiliser de guillemets bouclés.

Vous ne pouvez pas ajouter de champs personnalisés ou de champs notariaux via des balises de texte.

Signataire avec plusieurs signatures

Supposons qu'une extraction de document utilise des balises de texte et que le document comporte plusieurs champs de signature pour un signataire donné. Cela nécessite la spécification de métadonnées appropriées, comme l'expliquent les sections suivantes :

• Signatures

• Autofields

• Input Fields

Signatures

Les métadonnées suivantes permettent à un document d'avoir deux signataires, chacun avec deux champs de signature :

Signer1: {{esl_signer1Sig1:Signer1:Signature}}

Signer1: {{esl_signer1Sig2:Signer1:Signature}}

Signer2: {{esl_signer2Sig1:Signer2:Signature}}

Signer2: {{esl_signer2Sig2:Signer2:Signature}}

Champs automatiques

Si l'un des champs automatiques SignerName, SignerTitle, SignerCompany ou SigningDate est lié à l'un des multiples champs de signature d'un signataire, les métadonnées du champ automatique doivent être mises à jour pour le champ de signature spécifique auquel il est lié (pas nécessairement lié au premier champ de signature du signataire).

Les métadonnées suivantes permettent aux multiples signatures d'un signataire d'avoir des horodatages différents dans le même document :

{{esl :Signer1 :SigningDate :signature(« signer1Sig2 »)}}

{{esl :Signer1 :SigningDate :signature(« signer1Sig1 »)}}

{{esl :Signer2 :SigningDate :signature(« signer2Sig1 »)}}

{{esl :Signer2 :SigningDate :signature(« signer2Sig2 »)}}

{{esl :Signer1 :SignerName :signature(« signer1Sig2 »)}}

{{esl :Signer1 :SignerName :signature(« signer1Sig1 »)}}

{{esl :Signer2 :SignerName :signature(« signer2Sig1 »)}}

{{esl :Signer2 :SignerName :signature(« signer2Sig2 »)}}

Champs de saisie

Si un champ de saisie est lié à l'un des multiples champs de signature d'un signataire, les métadonnées de ce champ de saisie doivent être mises à jour pour le champ de signature spécifique auquel il est lié (pas nécessairement lié au premier champ de signature du signataire).

Les métadonnées suivantes permettent aux multiples signatures d'un signataire d'avoir des liaisons de champ de texte et de zone de texte différentes dans le même document :

{{esl:Signer1:TextField:signature("signer1Sig2")}}

{{esl:Signer1:TextField:signature("signer1Sig1")}}

{{esl:Signer2:TextField:signature("signer2Sig1")}}

{{esl:Signer2:TextField:signature("signer2Sig2")}}

{{esl :Signer1 :TextArea :signature(« signer1Sig2 »)}}

{{esl :Signer1 :TextArea :signature(« signer1Sig1 »)}}

{{esl :Signer2 :TextArea :signature(« signer2Sig1 »)}}

{{esl :Signer2 :TextArea :signature(« signer2Sig2 »)}}

Tutoriel vidéo

Autres méthodes d'extraction

Vous pourriez également être intéressé par nos autres types d'extraction :

• Document Extraction

• Text Anchor Extraction

• Position Extraction

Java SDK

DocumentPackage pkg = PackageBuilder.newPackageNamed("Text Tag Example Package")
					.withStatus(PackageStatus.SENT)
					.withSigner(SignerBuilder.newSignerWithEmail("mail32@example.com")
					.withFirstName("John")
					.withLastName("Smith")
					.withCustomId("Signer1"))
					.withDocument(DocumentBuilder.newDocumentWithName("Sample Contract")
					.fromFile("C:/Users/hhaidary/Desktop/sample_contract.pdf")
					.withExtractionType(ExtractionType.TEXT_TAGS_ONLY)
					.enableExtraction())
				.build();

Kit de développement logiciel (SDK) .NET

DocumentPackage pkg = PackageBuilder.NewPackageNamed("Text Tag Example Package")
					.WithStatus(DocumentPackageStatus.SENT)
					.WithSigner(SignerBuilder.NewSignerWithEmail("mail32@example.com")
					.WithFirstName("John")
					.WithLastName("Smith")
					.WithCustomId("Signer1"))
					.WithDocument(DocumentBuilder.NewDocumentNamed("Sample Contract")
					.FromFile("C:/Users/hhaidary/Desktop/sample_contract.pdf")
					.WithExtractionType(ExtractionType.TEXT_TAGS_ONLY)
					.EnableExtraction())
				.Build();

REST API

Pour télécharger l'exemple de code complet, consultez notre site Code Share. Le PDF utilisé dans ce guide se trouve .here

L'extraction de balises de texte permet aux intégrateurs d'extraire automatiquement des signatures et des champs en plaçant des balises de texte dans un document. OneSpan Sign analysera le document téléchargé et remplacera chaque texte qui correspond au modèle de balise de texte par la signature ou le champ approprié.

Pour ajouter des balises de texte, vous avez besoin d'un type de document approuvé qui contient déjà des balises de texte. Ces balises de texte doivent être nommées de manière à ce que OneSpan Sign puisse les reconnaître. Pour plus d'informations sur les paramètres et les formats des balises de texte, reportez-vous à la section feature overview.

Le signataire de ce document est nommé Signer1. Il s'agira de l'ID personnalisé utilisé dans le code pour permettre à OneSpan Sign de savoir quels champs associer à chaque signataire.

Ajout de balises de texte

En règle générale, une chaîne JSON est générée de manière dynamique, et non avec une chaîne statique géante, comme illustré ici. Cependant, cet exemple est présenté sous la forme d'une chaîne statique géante afin de donner une bonne représentation de la structure du JSON dont vous aurez besoin pour créer votre transaction.

Le fichier JSON ci-dessous est formaté pour être lisible. Dans chaque objet roles, vous verrez que l'ID personnalisé est le même que celui indiqué dans l'image du formulaire PDF ci-dessus.

Vous n'avez pas besoin de définir l'emplacement des signatures, ni de définir qui doit signer le document. Ceci est déjà pris en charge avec l'ID et les balises de texte associées du PDF.

Requête HTTP

POST /api/packages

En-têtes HTTP

Accept: application/json
Content-Type: multipart/form-data
Authorization: Basic api_key

Charge utile de la demande

------WebKitFormBoundary1bNO60n7FqP5WO4t
					Content-Disposition: form-data; name="file"; filename="sample-contract.pdf"
					Content-Type: application/pdf
					%PDF-1.5
					%µµµµ
					1 0 obj
					<>>>
					endobj.... 
					------WebKitFormBoundary1bNO60n7FqP5WO4t
					Content-Disposition: form-data; name="payload"
					{
					"documents": [
					{
					"id": "sample-contract",
					"name": "Test Document",
					"extract": true,
					"extractionTypes":[
					"TEXT_TAGS"
					]
					}
					],
					"status": "DRAFT",
					"type": "PACKAGE",
					"roles": [
					{
					"id": "Signer1",
					"type": "SIGNER",
					"signers": [
					{
					"email": "mail32@example.com",
					"firstName": "John",
					"lastName": "Smith",
					"id": "Signer1"
					}
					],
					"name": "Signer1"
					}
					],
					"name": "Text Tags Example Package"
					}
				------WebKitFormBoundary1bNO60n7FqP5WO4t--

Pour une description complète de chaque champ, consultez le tableau Charge utile de la demande ci-dessous.

Charge utile de réponse

{
  "id": "9sKhW-h-qS9m6Ho3zRv3n2a-rkI="
}

Résultats

Après avoir exécuté votre code, la transaction sera créée avec les champs appropriés pour chaque signataire.

Charge utile de la demande

APEX SDK

    	ESignLiveSDK sdk = new ESignLiveSDK();
         
					//Create package
					ESignLiveAPIObjects.Package_x pkg = new ESignLiveAPIObjects.Package_x();
					pkg.name = 'Test Text Tags - ' + Datetime.now().format();
					pkg.status = ESignLiveAPIObjects.PackageStatus.DRAFT;
        
					//Create Roles
					String roleId1 = 'Signer1';
					ESignLiveAPIObjects.Role role1 = new ESignLiveAPIObjects.Role();
					role1.signers = sdk.createRolesSigner('sigenr1_firstname', 'signer1_lastname', 'signer1@example.com', 'CEO', 'ABC Bank');
					role1.id = roleId1;
					role1.name = roleId1;
					pkg.roles = new List<ESignLiveAPIObjects.Role>{role1};    //add role
        
					//Prepare Documents Blob
					String document1Name = 'Sample_Text_Tag';
					StaticResource sr = [SELECT Id, Body FROM StaticResource WHERE Name = 'test_text_tag' LIMIT 1];
					Map<String,Blob> documentBlobMap = new Map<String,Blob>();
					documentBlobMap.put(document1Name, sr.Body);
         
					//Create Document Metadata
					ESignLiveAPIObjects.Document document1 = new ESignLiveAPIObjects.Document();
					document1.name = document1Name;
					document1.id = document1Name;
					document1.extract = true;
					ESignLiveAPIObjects.Data data_x = new ESignLiveAPIObjects.Data();
					data_x.esl_doc_extract_type = '1';
					document1.data = data_x;
					pkg.documents = new List<ESignLiveAPIObjects.Document>{document1};    //add document
        
					//Send package One Step
					String packageId = sdk.createPackage(pkg,documentBlobMap);
				System.debug('PackageId: ' + packageId);