OneSpan Signe pour les nouveaux utilisateurs: Créer et envoyer un paquet en utilisant REST avec Java

Quand j’ai commencé avec OneSpan Sign, j’ai commencé une série de blogs appelé "OneSpan Sign for New Users". J’ai couvert des exemples simples d’utilisation de l’interface utilisateur OneSpan Sign, Java SDK, .NET SDK, et l’API REST avec C . Il ya eu plusieurs questions sur l’utilisation REST avec Java à la place, alors j’ai décidé de faire équipe avec Haris (notre nouveau Junior OneSpan Sign Evangelist). Je vais faire le premier de deux blogs plus dans la série. Le mien couvrira la création et l'envoi d'un paquet de documents tandis que Haris fera un suivi avec la vérification de l'état du paquet et le téléchargement des documents à partir du paquet.

Si vous n'avez pas de compte Sandbox, consultez mon premier blog pour savoir comment vous pouvez vous inscrire.

Configuration

Avant de commencer, vous devrez configurer votre environnement. Pour cet exemple, je vais utiliser Java et Eclipse. Allez-y et créez un nouveau projet et un fichier .java. J'ai nommé mon projet "CreateAndSendPackageREST" et mon fichier .java, "CreateAndSendPackageREST.java". Si vous avez besoin d'aide pour obtenir cette mise en place, voir mon premier . Java SDK blog pour des instructions plus détaillées sur la mise en place d'un projet.

Créer et envoyer un paquet à l'aide de REST avec Java

Le code

Depuis la configuration de l'environnement et la configuration du projet a été couvert dans les blogs précédents, dans cette série, je vais sauter directement dans le code. Ouvrez le fichier .java que vous avez créé ci-dessus et copiez-le dans le code suivant. Je vais couvrir le code plus en détail ci-dessous.

OneSpan Sign Developer Community

Rejoignez la communauté OneSpan Sign Developer! Forums, blogs, documentation, téléchargements SDK, et plus encore.

Joignez-vous aujourd'hui

paquet com.esignlive.exemple;

import java.io.BufferedReader;
importer java.io.File;
import java.io.IOException;
importer java.io.InputStreamReader;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.io.PrintWriter;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.net.URL;
import java.net.URLConnection;
importer java.nio.file.Files;
 
classe publique SimpleCreateAndSendREST (en)
      
     
    public statique vide principal (String[] args) jette MalformedURLException, IOException (fr)
         
        Demande de cordesURL et "https://sandbox.esignlive.com/api";
        String apiKey - "Your_API_Key";
        Charlette à cordes "UTF-8";
        File de téléchargement de fichiers1 - nouveau fichier ("C:/Eclipse/workspace_442/CreateAndSendPackage/sampleAgreement.pdf");
        Limite de chaîne - Long.toHexString (System.currentTimeMillis)); Générer une valeur aléatoire pour la limite de formulaire
        Corde CRLF ''r''' ; Séparateur de ligne utilisé dans les données multiparties/form-data.
        String jsonContent - ""Roles" :["locked" :faux, "emailMessage":"content":"content":"" ""attachmentRequirements":[], "reas" ":faux", "specialTypes":[], "id"": "Sender", "données":null,"type":"SIGNER", "index":0 , "signataires" :["auth":"challenges":[], "scheme" :"NONE" firstName ": "PreparerFirst", "lastName" :"PreparerLast", "téléphone":""" " " " " " " "email"": "[email protected]", knowledgeBasedAuthenticationMD":null, "language"":"en" ", "title" :"Silanis", "external":null,"professionalIdentityFields":[],"userCustomFields":[], "delivery"::"email":true, "provider"":false, "". ":null,"address"":null,"data"":null,"name"":""specialTypes":[],"nom":"Sender" " , ""verrouillé":faux, "emailMessage":"content":"content":"". specialTypesMD":[], "id"":"Signer", "données":null,"type"": "SIGNER", "index":0, "signers":[[ "auth"": "challenges":[], "scheme" :"NONE" , "société":: ""premier nom":"SignerFirst", "SignerFirst", "Signer Last ": "Silanis", "téléphone"::"" " " " , " "email " : " [email protected] ", "knowledgeBasedAuthentication" :null, "language" :"fr "titre":""""external":null,"professionalIdentityFields":[], "userCustomFields":[], "livraison":"email" : faux, "fournisseur":faux, "téléchargement":faux, "groupe":null, "id"":"Signer", "signature":null,"address":null,"data"":"data":".null,"nom" :" " ", "SpecialTypes" :[], "nom": "Signer" : « Signer », « signé » : nul, « accepté » : nul, « données » : null, « fields » : [[» pageô::0, "subtype" : "FULLNAME", "FULLNAME" width ":200, "contraignant":null, "extract":faux, "extractAnchor":null, "gauche":175, "top":165, "validation"": null,"height":50, "données":null,"type"":"SIGNATURE", "valeur":"""" "." ""nom": """ "rôle":"Sender "signé":null,"accepted" :null, "data":null,"fields"":["page":0, "subtype":"FULLNAME", "largeur":200,"largeur":200,"contraignant":null,"extract":false, "extractAnchor":null, "left":550, "top":165, "validation":null,"height":50, "données" ":null,"type":"SIGNATURE" ", "valeur"":"""" """ " " " ô] », « nom » : « Nom » Test Package RESTMD, «type» : « PACKAGE », « langue » : « en / En », « emailMessage » : « « » », « description » : « Nouveau paquet », « autoComplete » : « vrai », « statut » : « SENT » ;
 
        Connexion URLConnection ' nouvelle URL (requestURL ' "/packages/).openConnection();
        connection.setDoOutput (vrai);
        connection.setRequestProperty("Content-Type", "multipart/form-data; limites de la frontière);
        connection.setRequestProperty ("Autorisation", "Basic" - apiKey);
    connection.setRequestProperty ("Accept", "application/json");
    Sortie OutputStream ' connection.getOutputStream();
    Écrivain PrintWriter - nouveau PrintWriter (nouveau OutputStreamWriter (sortie, charset), vrai);
 
        essayer  .
 
             Ajouter le fichier pdf.
             writer.append("--" - limite).append (CRLF);
             writer.append("Content-Disposition: form-data; nom "fichier"; nom de fichierMD "" - uploadFile1.getName() '''''''''''''' '' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' '
             writer.append("Content-Type: " ' URLConnection.guessContentTypeFromName(uploadFile1.getName())).append(CRLF);
             writer.append("Content-Transfer-Encoding: application/pdf").append (CRLF);
             writer.append (CRLF).flush();
             Files.copy(uploadFile1.toPath(), sortie);
             output.flush();
             writer.append (CRLF).flush();
                 
             ajouter la charge utile json
             writer.append("--" - limite).append (CRLF);
             writer.append("Content-Disposition: form-data; nom de "charge utile").append (CRLF);
             writer.append("Content-Type: application/json; charsetMD et charset).append (CRLF);
             writer.append (CRLF).append(jsonContent).append(CRLF).flush();
 
             Fin des données multiparties/form-data.
             writer.append("--" - limite - "--).append(CRLF).flush();
        }
        catch (IOException ex)
            System.err.println (ex);
        }
 
        obtenir et écrire le code de réponse
        int responseCode ((HttpURLConnection) connection).getResponseCode();
        System.out.println (responseCode);
         
        obtenir et écrire la réponse
        BufferedReader dans le nouveau BufferedReader (nouveau InputStreamReader(connection.getInputStream());
    Ligne d'entrée de chaîne ;
    Réponse StringBuffer - nouveau StringBuffer();
     
    tandis que ((inline - in.readLine()) !
         response.append (inputLine);
    }
        in.close();
      
    résultat d'impression
    System.out.println (response.toString));
    }
}
 

Décomposer le Code

Comme il s'agit d'un exemple très simple, tout est fait dans la méthode principale.

Dans les deux premières lignes, les informations de connexion pour votre connexion OneSpan Sign sont définies. Si vous utilisez l'environnement de production, utilisez l'URL, https://apps.e-signlive.com/api. Assurez-vous de remplacer le texte du placeholder par votre API_KEY. Vous pouvez trouver cette valeur dans la page ACCOUNT lorsqu’il est connecté à votre compte OneSpan Sign Sandbox. Si vous utilisez l'instance de production, vous devrez contacter le support pour obtenir cette clé.

1 apiKey de chaîne et « YOUR_API_KEY »;
2 url de chaîne et "https://sandbox.esignlive.com/api";

Après cela, vous verrez plusieurs autres variables en cours d'élaboration que nous utiliserons dans la création de l'appel POST, comme la valeur limite du formulaire et le fichier que vous prévoyez de télécharger.

1 charet à cordes et "UTF-8";
2 File de téléchargementde1 - nouveau fichier ("C:/Eclipse/workspace_442/CreateAndSendPackage/sampleAgreement.pdf");
3 Limite de chaîne - Long.toHexString (System.currentTimeMillis)); Générer une valeur aléatoire pour la limite de formulaire
4 Cordes CRLF ' ''r''' ;' Séparateur de ligne utilisé dans les données multiparties/form-data

La ligne suivante est la chaîne JSON qui définit votre paquet. Typiquement, vous allez probablement construire votre chaîne JSON dynamiquement vs ayant une chaîne statique géante, comme ceci, mais je l'ai fait de cette façon pour donner une bonne représentation de la structure de la JSON, vous aurez besoin pour créer votre paquet correctement. J'ai laissé de nombreuses propriétés vides dans la chaîne qui ne sont pas nécessaires pour la création de sorte que vous pouvez voir quelques-unes des autres options qui sont disponibles et comment ils sont passés dans le JSON. J'ai formaté le JSON pour la readablility, ci-dessous.

string jsonString
	"Rôles":[
	{
		"verrouillé":faux,
		"emailMessage":
		{
			"content": ""
		},
		"attachmentRequirements":[,,
		"Résigne":faux,
		"SpecialTypes":[,,
		"id": "Sender",
		"données":null,
		"Type": "SIGNER",
		"Index":0,
		"signataires":[
		{
			"auth":
			{
				"Défis":[],
				"Scheme" : "NONE"
			},
			"Société": "Silanis",
			"premier nom": "YOUR_FIRST_NAME" ",
			"dernier nom": "YOUR_LAST_NAME" ",
			"téléphone": ""
			"email":"[email protected]",
			"KnowledgeBasedAuthentication":null,
			"langue": "en",
			"titre": ""
			"externe":null,
			"ProfessionalIdentityFields":[],
			"userCustomFields":[],
			«livraison»:
			{
				"email":vrai,
				"fournisseur":faux,
				"téléchargement":vrai
			},
			"groupe":null,
			"signature":null,
			"adresse":null,
			"données":null,
			"Nom": ""
			"SpecialTypes":[]
		}],
		"Nom": "Sender"
	},
	{
		"verrouillé":faux,
		"emailMessage":
		{
			"content": ""
		},
		"attachmentRequirements":[,,
		"Résigne":faux,
		"SpecialTypes":[,,
		"Id": "Signer",
		"données":null,
		"Type": "SIGNER",
		"Index":0,
		"signataires":[
		{
			"auth":
			{
				"Défis":[],
				"Scheme" : "NONE"
			},
			"Société": ""
			"premier nom": "SIGNER_FIRST_NAME" ",
			"dernier nom": "SIGNER_LAST_NAME",
			"téléphone": ""
			"email":"[email protected]",
			"KnowledgeBasedAuthentication":null,
			"langue": "en",
			"titre": ""
			"externe":null,
			"ProfessionalIdentityFields":[],
			"userCustomFields":[],
			«livraison»:
			{
				"email":faux,
				"fournisseur":faux,
				"téléchargement":faux
			},
			"groupe":null,
			"Id": "Signer",
			"signature":null,
			"adresse":null,
			"données":null,
			"Nom": ""
			"SpecialTypes":[]
		}],
		"Nom": "Signer"
	}],
	"documents":[
	{
		"approbations":[
		{
			"Rôle": "Signer",
			"signé":null,
			"accepté":null,
			"données":null,
			"Champs":[
			{
				"page":0,
				"sous-type": "FULLNAME",
				"largeur":200,
				"contraignant":null,
				"extrait":faux,
				"extractAnchor":null,
				"Gauche":175,
				"top":165,
				"validation":null,
				"hauteur":50,
				"données":null,
				"Type": "SIGNATURE",
				"valeur": ""
			}],
			"Nom": ""
		},
		{
			"Rôle": "Sender",
			"signé":null,
			"accepté":null,
			"données":null,
			"Champs":[
			{
				"page":0,
				"sous-type": "FULLNAME",
				"largeur":200,
				"contraignant":null,
				"extrait":faux,
				"extractAnchor":null,
				"Gauche":550,
				"top":165,
				"validation":null,
				"hauteur":50,
				"données":null,
				"Type": "SIGNATURE",
				"valeur": ""
			}],
			"Nom": ""
		}],
		"nom": "YOUR_FILE_NAME"
	}],
	"Nom": "Test Package REST",
	"Type": "PACKAGE",
	"langue": "en",
	"emailMessage": ""
	"Description": "Nouveau paquet",
	"autoComplete":vrai,
	"statut": "SENT"
}";
 

La première partie de la chaîne JSON du paquet est l'objet "rôles". À l'intérieur, vous pouvez définir des éléments comme le "id", "société", "prénom", "nom de famille", "email", et "nom" pour personnaliser vos rôles de signataire. Certains des autres paramètres notables seraient "message électronique", "titre", et "livraison".

La section suivante de la chaîne JSON du paquet est l'objet "documents". À l'intérieur, vous définirez des éléments comme le « nom » et les « approbations » (blocs de signature). Dans les "approbations", les éléments principaux à définir seraient le "type", "sous-type", "rôle", "page", et les paramètres de localisation. Ceux-ci définiront les signatures requises dans chaque document.

Enfin, les derniers réglages de la chaîne JSON paquet que vous voudrez noter sont le "nom", "type", "statut", "emailMessage", et "autoComplete".

Ensuite, vous définirez la connexion sur laquelle vous enverrez votre demande. La première ligne ouvre la connexion à l'URL de demande. Notez que le reste de l'URL pour la demande particulière qui est faite est ajouté à l'URL de base, ici. Le reste définit les propriétés de demande et crée le OutputStream et PrintWriter pour communiquer la charge utile de demande avec OneSpan Sign.

1 connexion URLConnection ' nouvelle URL (requestURL ' '/packages/).openConnection();
2 connection.setDoOutput (vrai);
3 connection.setRequestProperty("Content-Type", "multipart/form-data; limites de la frontière);
4 connection.setRequestProperty ("Autorisation", "Basic" - apiKey);
5 connection.setRequestProperty ("Accept", "application/json");
6 Sortie OutputStream 'connection.getOutputStream();
7 Écrivain PrintWriter - nouveau PrintWriter (nouveau OutputStreamWriter (sortie, charset), vrai);

À l'intérieur du bloc d'essai, la forme réelle en plusieurs parties est créée. Ci-dessous, vous pouvez voir comment la limite, les descripteurs de partie de forme, et le contenu sont ajoutés dans chaque partie du formulaire.

Ajouter le fichier pdf.
writer.append("--" - limite).append (CRLF);
writer.append("Content-Disposition: form-data; nom "fichier"; nom de fichierMD "" - uploadFile1.getName() '''''''''''''' '' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' '
writer.append("Content-Type: " ' URLConnection.guessContentTypeFromName(uploadFile1.getName())).append(CRLF);
writer.append("Content-Transfer-Encoding: application/pdf").append (CRLF);
writer.append (CRLF).flush();
Files.copy(uploadFile1.toPath(), sortie);
output.flush();
writer.append (CRLF).flush();
                 
ajouter la charge utile json
writer.append("--" - limite).append (CRLF);
writer.append("Content-Disposition: form-data; nom de "charge utile").append (CRLF);
writer.append("Content-Type: application/json; charsetMD et charset).append (CRLF);
writer.append (CRLF).append(jsonContent).append(CRLF).flush();
 
Fin des données multiparties/form-data.
writer.append("--" - limite - "--).append(CRLF).flush();
 
Fin des données multiparties/form-data.
writer.append("--" - limite - "--).append(CRLF).flush();
 

Enfin, vous ferez l’appel POST, en passant votre formulaire à OneSpan Sign, la création de votre paquet de documents. Dans cet exemple, j'écris le code de réponse et le contenu de réponse à la conole.

obtenir et écrire le code de réponse
int responseCode ((HttpURLConnection) connection).getResponseCode();
System.out.println (responseCode);
             
obtenir et écrire la réponse
BufferedReader dans le nouveau BufferedReader (nouveau InputStreamReader(connection.getInputStream());
Ligne d'entrée de chaîne ;
Réponse StringBuffer - nouveau StringBuffer();
      
tandis que ((inline - in.readLine()) !
    response.append (inputLine);
}
in.close();
      
résultat d'impression
System.out.println (response.toString));
 

Si tout avec votre appel REST est correct, vous devriez obtenir un iD paquet retourné comme votre réponse, comme celui-ci:

Si vous vous connectez à votre compte OneSpan Sign, vous pouvez voir que le paquet a été créé tel que défini dans votre demande.

C’est tout. Vous avez créé avec succès un nouveau package, y compris un fichier, des signataires et des boîtes de signature en utilisant REST avec Java.

Si vous avez des questions concernant ce blog ou toute autre chose concernant l'intégration oneSpan Sign dans votre application, visitez les forums de la communauté des développeurs: https://developer.esignlive.com. C'est moi qui l'ai fait. Merci de lire! Si vous avez trouvé ce message utile, s'il vous plaît le partager sur Facebook, Twitter, ou LinkedIn.

Michael Williams

Twitter - France Facebook - France LinkedIn (en)