Aperçu des fonctionnalités Java 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 les signatures et les champs en plaçant des balises texte dans un document. OneSpan Sign analysera le document téléchargé et remplacera chaque texte correspondant au motif de la balise de texte par la signature ou le champ approprié.

Cette section aborde :

• Syntaxe des balises de texte

• Noms de rôles dans les balises texte

• Types de balises textuelles

• Paramètres de balise texte

• Signataire avec plusieurs signatures

Meilleures pratiques pour l'utilisation des balises texte

Voici quelques bonnes pratiques à garder à l'esprit lors de l'utilisation des balises texte :

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

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

  Un exemple plus complexe pourrait ressembler à :

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

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

• Assurez-vous que votre tag texte est dans une seule ligne.

Voici quelques exemples de code qui intègre ces suggestions :

{{esl_optionA :Signer1 :Radio :Group(« Frequency »),Value(« X »),size(10,10),offset(40,-8)}}
{{esl_optionB :Signer1 :Radio :Group(« Frequency »),Value(«  »),size(10,10),offset(40,-8)}}
{{esl_optionC :Signer1 :Radio :Group(« Frequency »),Value(«  »),size(10,10),offset(40,-8)}}

Dans cet exemple, la taille des tags est fixée à 1, et la taille normale du texte est fixée à 12. Voici ce que vous obtenez après avoir extrait vers ces champs :

Pour une copie du document Word utilisé dans cet exemple, cliquez ici.

Si vous avez des problèmes pour placer vos balises texte à leur emplacement correct, essayez d'utiliser l'attribut de décalage. C'est particulièrement utile lorsqu'on utilise un document Microsoft Word.

Syntaxe des balises de texte

La ligne suivante illustre la syntaxe d'un Text Tag :

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

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

Notez dans cette phrase que :

• Le début et la fin d'un Text Tag comportent des doubles crochets. Les crochets ne devraient apparaître nulle part ailleurs dans un Text Tag.

• Le troisième caractère — le X — est un personnage optionnel provisoire. Ce caractère peut être soit un point d'interrogation (?), soit un astérisque (*). Un astérisque indique qu'un champ d'entrée est requis. Un point d'interrogation indique qu'un champ d'entrée est optionnel. Le point d'interrogation est la valeur par défaut — c'est-à-dire que si aucun des deux caractères n'est présent, un champ d'entrée sera optionnel. 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 d'entrée) — voir Types de balises textuelles. Si spécifié, ce paramètre suivra le préfixe «esl ». Les noms des champs sont alphanumériques. Ils ne peuvent pas contenir de caractères spéciaux autres que le sous-trait (_). Si vous prévoyez de récupérer la valeur saisie lors de l'Expérience Signer, entrez un nom unique par champ. Exemple : {{esl_SignerAutograph:Signer1:Signature}}

• roleName est le nom du rôle associé au signataire visé. Pour trouver le nom du rôle à utiliser, consultez Noms de rôles dans les balises textuelles.

• fieldType est l'un des types de champs décrits dans Types de balises de texte.

• parameter1 et parameter2 sont des paramètres décrits dans les paramètres de l'étiquette textuelle.

Veuillez noter ce qui suit :

• Un Tag de texte ne peut pas apparaître sur plusieurs lignes.

• Si une liste de paramètres est présente, elle doit être une liste séparée par des virgules.

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

{{esl:roleName:fieldType}}

Noms de rôles dans les balises texte

Si vous créez une transaction en utilisant l'interface web OneSpan Sign, le nom du rôle de l'expéditeur est toujours Propriétaire.

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

Si vous créez un signataire temporaire et que vous le nommez Client, alors Client sera le nom du rôle. Le client restera le nom du rôle lorsque ce substitut sera remplacé par un destinataire ou un groupe spécifique.

Si vous créez un signataire avec le SDK et que vous attribuez un identifiant personnalisé à ce signataire, cet ID sera le nom de rôle du signataire. Si vous n'attribuez pas d' ID personnalisé au signataire, un identifiant est généré pour le signataire en utilisant les mêmes règles que lors de l'interface web OneSpan Sign.

Types de balises textuelles

Il existe trois principaux types de balises texte :

• Signatures

• Autofields

• Champs d'entrée

Signatures

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

• Signature — Ce bloc de signature est Click-to-Sign. Le nom du signataire sera estampillé sur le bloc cliqué.

• Initiales — Ce bloc de signature est Clic-à-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 dispositif d'entrée. Le signataire peut également choisir de se connecter sur un appareil mobile comme un smartphone si l'expéditeur a la capture mobile activée sur son compte. Le dessin est ensuite tamponné sur le bloc de signature. Notez que l'utilisation d'un stylet n'est pas prise en charge dans l'interface 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 avec leur doigt ou un stylet. Le dessin de la signature est ensuite tamponné sur le bloc.

• Choose_Signature — Le signataire choisit sa méthode de signature préférée parmi une liste définie de choix. Si sélectionné, une fois qu'un signataire commence le processus de signature, il reçoit un dialogue lui demandant de choisir la police pour ses initiales, ou éventuellement de dessiner la sienne.

Autofields

Un tag texte Autofield particulier peut être l'un des types de champs 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 reste 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 reste vide.

• Date de signature — Au moment de la signature, le système remplit automatiquement ce champ avec la date actuelle.

Champs d'entrée

Un tag texte de champ d'entrée particulier peut être l'un des types de champs suivants :

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

• TextArea — C'est similaire au type TextField , car il fournit une zone où les signataires peuvent saisir du texte libre. Cependant, contrairement aux champs de texte, il offre un enroulement automatique. 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 soit sélectionner soit effacer cette case simple.

• Étiquette — L'expéditeur du colis peut ajouter un champ Étiquette pour intégrer du texte dans un document. Il s'agit d'un champ en lecture seule dont la valeur sera simplement estampillée sur le PDF. Pendant l'Expérience Signant, le champ Étiquette s'affiche comme du texte non modifiable.

Paramètres de balise texte

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

• Offset et Taille sont utilisés pour les trois types de balises textuelles.

• 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 optionnels.

Si des guillemets sont requis dans un paramètre du tableau suivant, vous devez utiliser des guillemets directs. Vous ne pouvez pas utiliser de guillemets en boucle.

Vous ne pouvez pas ajouter de champs personnalisés ou de champs notaires via des balises textuelles.

Signataire avec plusieurs signatures

Supposons qu'une extraction de document utilise des balises de texte, et que le document possède plus d'un champ 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

• Champs d'entrée

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}}

Autofields

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 de l'autochamp 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 dates différentes 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 d'entrée

Si un champ d'entrée est lié à l'un des multiples champs de signature d'un signataire, les métadonnées de ce champ d'entrée 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 différentes liaisons de champ de texte et de zone de texte 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 :

• Extraction de documents

• Extraction d'ancrage textuel

• 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();

.NET SDK

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 complet de code, consultez notre site de partage de code . Le PDF utilisé dans ce guide est disponible ici.

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

Pour ajouter des balises texte, il faut un type de document approuvé qui comporte déjà des balises texte. Ces balises texte doivent être nommées d'une manière que OneSpan Sign puisse reconnaître. Pour plus d'informations sur les paramètres et formats des balises textuelles, consultez l' aperçu des fonctionnalités.

Le signataire de ce document s'appelle Signer1. Ce sera l'ID personnalisé utilisé dans le code pour indiquer à OneSpan Sign quels champs associer à chaque signataire.

Ajout de balises texte

Typiquement, une chaîne JSON est construite dynamiquement, et non avec une chaîne statique géante comme illustré ici. Cependant, cet exemple est présenté comme une énorme chaîne statique afin de donner une bonne représentation de la structure du JSON, il faudra créer votre transaction.

Le JSON ci-dessous est formaté pour la lisibilité. Dans chaque objet Roles, vous verrez que l'ID personnalisé est le même que montré sur l'image du formulaire PDF ci-dessus. L'objet documents a également extrait défini sur true.

Vous n'êtes pas obligé de définir les lieux de signature, ni de déterminer qui doit signer le document. Cela est déjà réglé avec l'ID et les balises textuelles 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 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, voir le tableau des charges utiles de 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 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();
					ese_document_texttag_extract_needed = '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);