Documentation - Add signature

Add signature

Requête

Crée un objet Signature à partir de sa représentation JSON. L'en-tête Content-Type de la requête HTTP doit être application/json, ou l'API retournera une erreur.

POST /api/signatures?details=links
Authentication: Bearer cle+api+du+compte+client
Content-Type: application/json

{
	"description": "Contrat à signer",
	"expirationDate": "2025-01-07T00:00:00+01:00"
	"allowedMethods": "email,touch",
	"signatoryName": "Pascal Dupont",
	"signatoryEmail": "pascal.dupont@laposte.fr",
	"signatoryMobile": "+336123456789",
	"clientData": {
		"customerId": 123456
	},
	"notificationUrl": "https://erp.client.org/sigtool/document-signed,mailto:notification@client.org",
	"documents": [
		{
			"description": "Contrat à signer",
			"fileName": "contract.pdf"
			"data": "<encodage base64 du fichier PDF>",
			"positions": [
				{
					"page": 1,
					"offsetX": 10,
					"offsetY": 250,
					"sizeX": 80,
					"sizeY": 40,
					"orientation": "right"
				}
			]
		}
	],
	"attributes": {
		"signatory.must-agree": {
			"fr": "Veuillez lire et accepter les termes contrat"
		}
	}
}

Valeurs du JSON à transmettre

• description
  obligatoire
  
  Chaîne décrivant l'ensemble des documents à signer, présentée au signataire.
• expirationDate
  optionnel
  
  Chaîne au format ISO8601 de la date à partir de laquelle le document ne sera plus accessible, ni pour signature, ni via l'API. SigTool annonymisera l'objet Signature au delà de cette date, les informations du signataire seront supprimées, et les fichiers PDFs, signés ou non, seront détruis.
• allowedMethods
  optionnel
  
  Chaîne contenant la liste des méthodes de signature proposées au signataire, séparées par des virgules. Les méthodes supportées sont email pour une signature via un code envoyé par E-mail, sms pour une signature via un code envoyé par SMS (si l'option SMS est activée au niveau du compte client, celle-ci engendrant des frais), touch pour une signature graphique optionnelle si le périphérique utilisé par le signataire supporte le tactile, ou mouse pour une signature graphique inconditionnelle (souris ou tactile).
• signatoryName
  obligatoire
  
  Chaîne contenant le nom de la personne qui devra signer le ou les documents.
• signatoryCompany
  optionnel
  
  Chaîne contenant la société ou l'organisation à laquelle appartient la personne qui devra signer le ou les documents.
• signatoryEmail
  optionnel
  
  Chaîne contenant l'adresse E-mail utilisée pour envoyer le code de signature au signataire. La signature par E-mail ne sera pas disponible si cette valeur n'est pas renseignée.
• signatoryMobile
  optionnel
  
  Chaîne contenant le numéro de téléphone portable, au format internationnal, utilisé pour envoyer le code de signature au signataire. La signature par SMS ne sera pas disponible si cette valeur n'est pas renseignée, ou si l'option SMS n'est pas activée au niveau du compte client.
• clientData
  optionnel
  
  Valeur opaque de n'importe quel type (entier, chaîne, tableau, objet) qui sera associée à l'objet Signature. Cette valeur sera envoyée via les notifications HTTP. L'API de recherche des signatures peut aussi utiliser cette valeur.
• notificationUrl
  optionnel
  
  Chaîne contenant la liste des URLs de notification, séparées par des virgules. Lorsque le signataire signe le ou les documents, SigTool notifie le client sur toutes ces URLs, et sur les URLs de notification du compte client si ce dernier en possède. Les URLs supportées sont de type :
  • HTTP : SigTool appelera l'URL de notification HTTP, permattant d'automatiser la récupération des documents signés dans un environnement serveur.
  • mailto : Un email sera envoyé à l'adresse contenu dans cette URL. Si l'adresse est suffixé par la chaîne ?attach=yes, les PDFs signés seront attachés au mail envoyé.
  • sms : Un SMS sera envoyé au numéro contenu dans cette URL, si l'option SMS est activée au niveau du compte client.
• redirectionUrl
  optionnel
  
  Chaîne contenant une URL de type HTTP vers laquelle sera redirigé le signataire après avoir signé le ou les documents. Si cette valeur est absente, le signataire restera sur la page de signature et pourra télécharger le ou les documents signés. Les même paramètres que ceux utilisés pour les notifications HTTP seront ajoutés à la query string de la page de destination. Pour le calcul de la somme de contrôle HMAC, seuls les paramètres de la query string commençant par sgt_ seront à prendre en compte.
• documents
  1..n
  
  Tableau d'objets document representant le ou les documents PDFs à signer.
  • description
    optionnel
    
    Chaîne contenant la description de ce document, présentée au signataire. Si la Signature ne comporte qu'un seul document à signer, cette valeur devrait être la même que celle de l'objet Signature.
  • fileName
    optionnel
    
    Chaîne contenant le nom de fichier du document si le signataire souhaite le télécharger. Un nom de fichier par défaut sera généré si cette valeur est omise.
  • data
    obligatoire
    
    Chaîne base64 du contenu binaire du fichier PDF associé au document.
  • positions
    0..n
    
    Tableau d'objets position spécifiant où sera apposée la signature graphique ou numérique dans le document PDF. Une image sera apposée au PDF par objet position. Si aucun objet position n'est fournis, SigTool ajoutera une signature en haut à droite d'une nouvelle page vierge.
    • page
      optionnel
      
      Entier représentant le numéro de la page où la signature sera apposée, ou la chaîne new pour apposer la signature sur une nouvelle page vierge, ou la chaîne all pour apposer la signature sur toutes les pages du document PDF. Valeur new par défaut.
    • offsetX
      optionnel
      
      Entier représentant la position horizontale en millimètres, en partant de la gauche où sera apposé la signature. Valeur 15 par défaut.
    • offsetY
      optionnel
      
      Entier représentant la position verticale en millimètres, en partant du haut où sera apposé la signature. Valeur 15 par défaut.
    • sizeX
      optionnel
      
      Entier représentant la taille horizontale maximale en millimètres de l'image de signature. Celle-ci sera étirée au maximum sans déformation pour remplir la zone définie avec sizeY. Valeur 80 par défaut.
    • sizeY
      optionnel
      
      Entier représentant la taille horizontale maximale en millimètres de l'image de signature. Valeur 40 par défaut.
    • orientation
      optionnel
      
      Chaîne représentant l'orientation de l'image de signature, right pour une orientation normale vers la droite, bottom pour une orientation vers le bas (rotation à -90°), left pour une orientation vers la gauche (rotation à -180°) et top pour une orientation vers le haut (rotation à 90°). Valeur right par défaut.
• attributes
  optionnel
  
  Objet de propriétés nommées pouvant avoir une valeur numérique, chaîne, tableau à une dimension, ou objet de profondeur 1. Les propriétés nommées suivantes ont une fonctionnalité bien définie :
  • signatory.must-agree
    Propriété utilisée lors de la signature pour demander au signataire d'accepter des conditions en cochant les cases adéquates. Cette propriété peut être soit une chaîne de caractère contenant une ou plusieurs conditions à cocher, séparées par un caractère retour chariot <CR>, soit un objet dont le nom des sous-valeurs est la langue de la condition (sur 2 caractères), et la sous-valeur associée est la chaîne de conditions dans cette langue.
  • signature.unique-identifier
    Chaîne de caractères servant à protéger la signature contre les duplicatats. Si une nouvelle signature est ajoutée avec la même propriété signature.unique-identifier, une erreur sera retournée. Cette propriété peut aussi être utilisée pour la recherche.
  • redirection.button
    Si cette propriété est présente ainsi que la valeur redirectionUrl, une fois le ou les documents signés, l'utilisateur ne sera pas redirigé automatiquement vers redirectionUrl, mais un bouton avec le texte de cette valeur sera affiché pour le rediriger. Ceci laisse le temps au signataire de télécharger son document signé. Cette propriété est soit une chaîne de caractère soit un objet de sous-valeurs par langue comme signatory.must-agree.

Réponse

La donnée retournée sera l'objet Signature créé, au format JSON. En fonction du paramètre query string optionnel details, l'objet retourné contiendra différentes valeurs.

200 OK
Content-Type: application/json

{
	"success": true,
	"signature": {
		"cancelled": false,
		"description": "Contrat à signer",
		"token": "rKQ9qljTcXdynOzxBCnzfi3cWuqNDQl0",
		"creationDate": "2024-12-23T20:27:47+01:00",
		"allowedMethods": "email,touch",
		"signatoryName": "Pascal Dupont",
		"signatoryCompany": null,
		"signatoryEmail": "pascal.dupont@laposte.fr",
		"signatoryMobile": "+336123456789",
		"notificationUrl": "https://erp.client.org/sigtool/document-signed,mailto:notification@client.org",
		"redirectionUrl": null,
		"resourceUrl": "https://www.sigtool.com/api/signatures/rKQ9qljTcXdynOzxBCnzfi3cWuqNDQl0",
		"signUrl": "https://www.sigtool.com/sign/identifiantclient/rKQ9qljTcXdynOzxBCnzfi3cWuqNDQl0"
	}
}