Prérequis à l’intégration API
Vous aurez besoin d’une clé API pour authentifier la plupart des requêtes adressées à l’API Universign. Seuls les membres ayant les droits d’administrateur ou un rôle d’intégrateur peuvent créer des clés API.
Créer une clé API
Dans le menu Développeur de l’application web, accédez à la section Clés API et cliquez sur Créer une clé API.
1. Donnez un nom explicite à votre clé API. Il vous sera ainsi plus facile d’identifier quelle clé API peut être supprimée, par exemple.
2. Copiez votre clé API et conservez-la dans un endroit sûr de votre côté. Pour des raisons de sécurité, Universign ne stocke pas la valeur des clés API.
3. Créez votre clé.
Authentifier une requête
Une fois votre clé API créée, vous êtes prêt à authentifier votre requête. Ajoutez-la à l’en-tête de la requête en tant que valeur du nom d’utilisateur suivi d’un deux-points : -u your_API_key: (le champ mot de passe peut être laissé vide).
Vous pouvez également vous authentifier via l’authentification du porteur : -H "Authorization: Bearer votre_clé_API"
Erreurs d’authentification
Si vous ne fournissez pas de clé API ou si vous fournissez une clé invalide lorsqu’une authentification est requise, vous recevrez une réponse 401 - Unauthorized.
Si la clé API que vous avez fournie ne vous donne pas accès à la ressource, vous recevrez une réponse 403 - Forbidden.
Envoyer votre premier document à signer
1. Créer une transaction
Créez une transaction en draft en envoyant une requête à l’endpoint POST /v1/transactions.
curl
https://api.universign.com/v1/transactions
L’API renvoie un objet transaction comprenant un id :
{
"object": "transaction",
"id": "tx_AWo949MOq0JE",
"folder_id": "fol_MJQbbKe5PV7d",
"created_at": "2022-10-18T07:34:58Z",
"duration": 20160,
"name": "tx_AWo949MOq0JE",
"folder_name": "My folder",
"stalled": false,
"language": "fr",
"creator": {
"workspace_name": "My company",
"api_key_name": "My API key"
},
"state": "draft",
"participants": [],
"watchers": [],
"sealers": [],
"documents": [],
"instructions": {
"signatures": [],
"reviews": [],
"captures": [],
"sequencing": [],
"editions": []
},
"actions": [],
"metadata": {},
"progress_value": 0,
"ongoing_conversation": false,
"has_unread_message": false,
"origin": "API",
"carbon_copies": [],
"uploads": [],
"max_expiry": "180_days",
"private": false
}
2. Ajouter un document
L’ajout d’un document à une transaction se fait en deux étapes.
2.1. Importer votre fichier sur les serveurs Universign
Avant de pouvoir ajouter le document à votre transaction, vous devez le télécharger sur nos serveurs. Pour ce faire, envoyez une requête multipart/form-data à POST /v1/files et transmettez le document (au format PDF, Word ou image) dans l’argument file :
curl
https://api.universign.com/v1/files \
-F [email protected]
l’API renvoie un file ID :
{
"object" : "file",
"id" : "file_d0bDo8LgEkEA",
}
Notez que nous conservons le fichier pendant 24 heures afin que vous puissiez réutiliser l’identifiant du fichier pendant cette période.
2.2. Ajouter l’identifiantdu fichier à votre demande de transaction
Pour ajouter l’identifiant du fichier à votre transaction, envoyez une demande à POST /v1/transactions/{transaction_id}/documents et transmettez l’identifiant du fichier dans l’argument document.
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents \
-d document=file_d0bDo8LgEkEA \
L’API renvoie un identifiant de document. Le nom du document correspond par défaut au nom du fichier.
{
"id": "doc_wWz6",
"name": "myDocument.pdf",
"updatable": true,
"deletable": true,
"fields": []
}
3. Ajouter un champ de signature au document
Pour ajouter un champ de signature à votre transaction, envoyez une requête à POST /v1/transactions/{transaction_id}/documents/{document_id}/fields et transmettez signature comme argument du type de champ :
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents/doc_wWz6/fields \
-d type=signature
4. Attribuer un signataire au champ
Pour attribuer un signataire, vous devez associer le champ de signature que vous venez de créer à l’email du signataire. Pour ce faire, envoyez une requête à POST /v1/transactions/{transaction_id}/signatures et transmettez les arguments field et signer :
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/signatures \
-d [email protected] \
-d field=fld_5XoG
L’API renvoie :
{
"id": "fld_5XoG",
"type": "signature",
"built_in": false,
"consents": [],
"updatable": true,
"deletable": true
}
5. Activer la notification du signataire (facultatif)
Par défaut, lorsque la transaction est créée par API, aucune invitation n’est envoyée au signataire. Si vous souhaitez que le signataire reçoive une invitation pour accéder au document, envoyez une requête à POST /v1/transactions/{transaction_id}/participants et transmettez l’email du signataire dans l’argument email et 0 dans l’argument schedule. Pour plus d’informations, consultez Ajouter un message d’invitation.
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/participants \
-d [email protected] \
-d schedule=[0]
Noter que l’invitation ne sera pas envoyée tant que votre transaction sera en brouillon.
6. Commencer une transaction
Vous êtes prêt à envoyer votre première transaction. Pour ce faire, envoyez une requête à POST /v1/transactions/{transaction_id}/start :
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/start
L’API renvoie un objet transaction, avec une statut started.
{
"object": "transaction",
"id": "tx_AWo949MOq0JE",
"folder_id": "fol_DGX2qbq6yGmm",
"created_at": "2022-10-19T10:23:07Z",
"started_at": "2022-10-19T10:31:41Z",
"expires_at": "2022-11-02T10:31:41Z",
"name": "tx_k1b29GMrJJzW",
"folder_name": "Default folder",
"stalled": false,
"language": "fr",
"creator": {
"workspace_name": "WorkspaceName",
"api_key_name": "MyAPIKey"
},
"state": "started",
"participants": [
{
"email": "[email protected]",
"min_signature_level": "level1",
"schedule": [
0
],
"ongoing_conversation": false,
"has_unread_message": false,
"state": "open"
}
],
"watchers": [],
"sealers": [],
"documents": [
{
"id": "doc_wWz6",
"name": "DocumentName.pdf",
"updatable": true,
"deletable": false,
"fields": [
{
"id": "fld_5XoG",
"type": "signature",
"built_in": false,
"consents": [],
"updatable": true,
"deletable": false
}
]
}
],
"instructions": {
"signatures": [
{
"signer": "[email protected]",
"field": "fld_5XoG"
}
],
"reviews": [],
"captures": [],
"sequencing": [],
"editions": []
},
"actions": [
{
"id": "act_vP4399Kob9PWE",
"actor": "[email protected]",
"state": "open",
"url": "https://apps.trunk.universign.net/npds/act_vP4399Kob9PWE",
"tasks": [
{
"type": "signature",
"state": "todo",
"field": "fld_5XoG"
}
],
"stalled": false
}
],
"metadata": {},
"progress_value": 0,
"ongoing_conversation": false,
"has_unread_message": false,
"origin": "API",
"carbon_copies": [],
"uploads": [],
"private": false
}
Votre transaction est désormais en cours : le signataire reçoit instantanément un email contenant un lien pour accéder au document à signer.
Notez que vous pouvez créer et commencer une transaction entièrement configurée à l’aide d’une seule requête. Pour plus d’informations, consultez Full transaction request.
