Signe OneSpan pour les nouveaux utilisateurs: Comment créer et envoyer votre premier paquet (API REST)
L’achèvement de la série "OneSpan Sign for New Users" est proche. Jusqu’à présent, j’ai couvert des exemples simples d’utilisation de signatures e, l’interface du signe OneSpan, Java SDK, et .NET SDK. Vous pouvez voir la liste complète des messages au bas de ce blog. Les deux derniers blogs de la série couvriront l’utilisation de l’API OneSpan Sign REST, avec celui-ci couvrant, créant et envoyant un paquet de documents.
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 C et Microsoft Visual Studio. Allez-y et obtenez un projet et un fichier .cs créé. J'ai nommé mon projet "CreateAndSendPackageREST" et mon fichier .cs, "CreateAndSendPackageREST.cs". Si vous avez besoin d'aide pour mettre en place, consultez mon premier blog .NET SDK (vous pouvez ignorer la partie .NET SDK et passer à la "Télécharger Microsoft Visual Studio" et "Créer et configurer votre projet C" sections) pour des instructions plus détaillées.
Guide du débutant sur les signatures électroniques
Ce document de préparation essentiel de 24 pages présente des concepts juridiques et des enjeux clés importants pour la création de processus d’affaires numériques qui font appel aux signatures électroniques.
TéléchargerCréer et envoyer un paquet
Le code
Depuis la configuration de l'environnement et la configuration du projet ont été couverts dans les blogs précédents, dans cette série, je vais sauter directement dans le code. Ouvrez le fichier .cs que vous avez créé ci-dessus et copiez-le dans le code suivant. Je vais couvrir le code plus en détail ci-dessous.
enutilisantle système;enutilisantSystem.Diagnostics;l'utilisationde System.IO;l'utilisationde System.Net;enutilisantSystem.Net.Http;enutilisantSystem.Net.Http.Headers;enutilisantSystem.Text;namespaceCreateAndSendPackageREST{classe publiqueCreateAndSendPackage{publicstatiquevideMain(corde[] args){apiKeyà cordeset "YOUR_API_KEY";url àcordeset "https://sandbox.esignlive.com/api";stringjsonString -""roles" :["locked" :faux, "emailMessage":"content":"content":"" ""roles"""."attachmentRequirements"::"emailMessage":"content":"" [], "reassign":faux, "specialTypes":[], "id"":"Sender", "données"":null,"type"": "SIGNER", "index"::0,"signers":["auth":"défis": [], "scheme" :"NONE" , "société":"Silanis", "premier nom":"votre premier", "lastName":"yourLast" "email"":"[email protected]", "knowledgeBasedAuthentication":null, "language":"en" ", "title" : "Silanis", "external":null, "professionalIdentityFields": [], "userCustomFields":[], "delivery"":"email":true,"provider"":false,"download"":true, "group":null,"signature"":null,"address"":null, "data"":null, "name":::"""" [], "nom":"Sender" , "verrouillé":faux, "emailMessage"":: "content":"content":""""attachmentRequirements":[], "reassign ":faux, "specialTypes":[], "id":"Signer", "données":null,"type":"SIGNER", "index":0,"signataires":: ["auth" : "défis" : [], "scheme" :"NONE" , "société"":"" " " " " "premier nom " : « signerFirst », « lastName » : « signerLast », « signerLast », « téléphone@example» : « « « » "email"":"signer.email .com", "knowledgeBasedAuthentication":null, "language":"en" ", "title" :" ""external":null, "professionalIdentityFields":": [], "userCustomFields":[], "livraison":"email":faux,"fournisseur"::faux,"télécharger":faux, "groupe":null,"id" : « Signer », « signature » : null, « address » : null, « data » : null, « nom » : « SpecialTypes » : [],« nom » "Signer" ], "documents":["approbations" :["rôle":"Signer", "signé":null,"accepté":null,"données":null,""données":null,"champs":"champs":: ["page":0, "sous-type":"FULLNAME", "largeur":200, "contraignant":null,"extract":faux, "extractAnchor":null,"left":1 75, "top" :165, "validation":null,"height":50, "data"::null,"type":"SIGNATURE", "valeur":"" nom ":""" " " " " "role" : "Sender", "signé":null, "accepté":null,"data":null,"fields":"fields": ["page":0, "sous-type":"FULLNAME", "largeur":200, "contraignant":null,"extract":false, "extractAnchor":null,""extractAnchor":null,"""extractAnchor":null,""" gauche":550, "top" :165, "validation" :null, "height" ":50", "données":null,"type":"SIGNATURE", "valeur""valeur"". : : « Ô » et « nom » : « « Nom » : « « « Ô ] », « nom » : « sampleAgreement » : « Test Package REST », « type » : « PACKAGE », « PACKAGE » "langue":"en", "emailMessage" ::"" "", "description":"Nouveau paquet", "autoComplete":vrai, "statut": "SENT";StringContent jsonContent -nouveauStringContent(jsonString, Encoding.UTF8,"application/json");octte[] fileByteArray - File.ReadAllBytes ("PATH_TO_YOUR_PDF.pdf");Contenu ByteArrayContent 'nouveauByteArrayContent(fileByteArray);contenu. Headers.ContentDisposition -nouveauContentDispositionHeaderValue ("form-data");contenu. Headers.ContentDisposition.Name ' '' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' '' ' ' ' ' ''contenu. Headers.ContentDisposition.FileName '"NAME_OF_YOUR_FILE.pdf";contenu. Headers.ContentType -nouveauMediaTypeHeaderValue ("application/pdf");Formulaire MultipartFormDataContent 'nouveauMultipartFormDataContent();forme. Ajouter (contenu,"fichier","NAME_OF_YOUR_FILE.pdf""));forme. Ajouter(jsonContent,""charge utile""));HttpClient myClient 'nouveauhttpClient();myClient.DefaultRequestHeaders.Authorization -newAuthenticationHeaderValue ("Basic", apiKey);myClient.DefaultRequestHeaders.Add("Accept","application/json");varréponse - myClient.PostAsync (nouveauUri(url) -"/packages/", formulaire). Résultat;Debug.WriteLine (réponse. Content.ReadAsStringAsync(). Résultat);}}}
Décomposer le code
Maintenant que vous avez le code copié dans votre fichier .cs, je vais passer par le code, section par section, vous permettant de savoir où vous aurez besoin d'entrer des informations pour votre paquet et décrivant ce que chaque section fait. Comme il s'agit d'un exemple très simple, tout est fait dans la méthode principale. Décomposer le Code
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'elle est signée dans votre compte OneSpan Sign.
1 apiKey de chaîne et « YOUR_API_KEY »; 2 url de chaîne et "https://sandbox.esignlive.com/api";
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":"your.email.com",
"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":"signer.email.com",
"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". Dans cet exemple, j'ai mis le "statut" à "SENT". Cela enverra le colis et en informera les signataires. Si vous voulez enregistrer ce paquet comme un projet, faire la valeur "DRAFT", à la place.
La ligne suivante du code prendra votre chaîne JSON et fera l'objet StringContent que vous passerez comme la charge utile dans votre commande REST API.
StringContent jsonContent - nouveau StringContent(jsonString, Encoding.UTF8, "application/json");
Les deux prochaines lignes seront lues dans votre fichier PDF et l'utiliseront pour créer votre objet ByteArrayContent de fichier pour votre appel REST. Assurez-vous de changer le placeholder au chemin de votre fichier.
1 octet[] fileByteArray - File.ReadAllBytes("PATH_TO_YOUR_PDF.pdf");
2 Contenu ByteArrayContent 'nouveau ByteArrayContent(fileByteArray);
Les lignes suivantes définissent l'en-tête de disposition du contenu de l'objet de contenu de fichier pdf.
1 contenu. Headers.ContentDisposition - nouveau ContentDispositionHeaderValue ("form-data");
2 contenu. Headers.ContentDisposition.Name « « fichier »;
3 contenu. En-têtes.ContentDisposition.FileName ' ''NAME_OF_YOUR_FILE.pdf'' ;
4 contenu. Headers.ContentType - nouveau MediaTypeHeaderValue ("application/pdf");Le prochain bloc de code est l'endroit où vous créez votre formulaire multipartite et ajoutez vos objets de contenu créés ci-dessus pour passer avec votre appel REST. Assurez-vous de définir le nom du fichier.
1 Formulaire MultipartFormDataContent 'nouveau MultipartFormDataContent(); 2 formulaire. Ajouter (contenu, « fichier », « NAME_OF_YOUR_FILE.pdf ») ; 3 formulaire. Ajouter (jsonContent, ""charge utile");
Ensuite, vous créerez le httpClient que vous utiliserez pour faire votre demande POST et définirez l'autorisation d'en-tête appropriée et accepterez les valeurs.
1 httpClient myClient ' nouveau httpClient();
2 myClient.DefaultRequestHeaders.Authorization - new AuthenticationHeaderValue ("Basic", apiKey);
3 myClient.DefaultRequestHeaders.Add("Accept", "application/json");Enfin, vous ferez l’appel POST, en passant votre formulaire à OneSpan Sign, la création de votre paquet de documents. La ligne Debug affichera le résultat sur la console de sortie de débogage.
1 réponse var ' myClient.PostAsync(nouveau Uri(url) '/packages/", formulaire). Résultat; 2 Debug.WriteLine (réponse. Content.ReadAsStringAsync(). Résultat);
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 package 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 le placement de boîtes de signature avec l'API REST.
Merci pour la lecture! Si vous avez des questions ou des fonctionnalités que vous souhaitez voir couvertes du point de vue d'un nouvel utilisateur, n'hésitez pas à poster dans la section commentaires. Liens vers tous les messages de cette série de blog peut être trouvé, ci-dessous. Si vous voulez voir plus de messages de moi, voir ma page d'auteur.
Michael Williams
Twitter - France Facebook - France LinkedIn (en)