Vous pouvez ajouter jusqu’à 20 documents à votre transaction. Nous acceptons les formats PDF, Word et images, avec une taille maximale de 25 Mo par document (50 Mo si la fonctionnalité Fichiers volumineux est activée sur votre espace de travail). Le document final (le document signé) est toujours au format PDF.
L’ajout d’un document à une transaction se fait en deux étapes.
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.
Ajouter l’identifiant du 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.
Remarque : Vous devez envoyer une requête par document.
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents \
-d document=file_d0bDo8LgEkEA \
-d name=DocName
Vous pouvez transmettre d’autres arguments optionnels :
-
archiving_configuration_id: l’identifiant de la configuration d’archivage des documents signés. À récupérer depuis votre espace de travail. Pour plus de détails sur la configuration d’archivage, consultez Archiver les documents signés. -
compliance_policy: à définir surpdfapour forcer l’opération de signature/scellement à respecter la norme PDF/A. Universign conserve le niveau de conformité PDF/A du document que vous importez : par exemple, un document PDF/A-3b reste PDF/A-3b une fois signé ou scellé. Si ce paramètre n’est pas défini, un document PDF/A sera signé/scellé mais ne sera plus conforme à la norme PDF/A. -
pdfa_variant: définit le rendu du cartouche de signature lorsquecompliance_policyest défini surpdfa. Valeurs possibles :1bet3b. Ne pas définirpdfa_variantéquivaut à définirpdfa_variant=1b. Toute autre valeur est ignorée. -
metadata: les métadonnées du document, sous forme de paires clé-valeur. Pour plus de détails, consultez Ajouter des métadonnées au document.
Conserver la transparence de votre logo avec pdfa_variant=3b : la norme PDF/A-1 (ISO 19005-1) interdit la transparence. En 1b (ou sans pdfa_variant), le logo et l’image de signature manuscrite s’affichent sur un fond blanc dans le cartouche de signature. La transparence est autorisée à partir de PDF/A-2 : pour les documents PDF/A-2b et PDF/A-3b, définissez pdfa_variant=3b pour la conserver.
PDF/A est un format normalisé ISO (ISO 19005) avec des règles strictes visant à éliminer tout ce qui pourrait se dégrader avec le temps.
PDF/A est couramment requis lorsque des documents doivent être archivés, échangés ou conservés à des fins légales.
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": []
}
Ajouter des métadonnées au document
Vous pouvez associer des métadonnées (paires clé-valeur) à chaque document d’une transaction, par exemple une référence de contrat, un numéro de dossier ou un identifiant issu de votre SI. Elles sont ensuite restituées dans les réponses de l’API et dans les archives des transactions.
Chaque document peut porter 15 métadonnées maximum. Chaque clé de métadonnée est limitée à 20 caractères, tandis que la valeur est limitée à 200 caractères.
Notez que les métadonnées de document ne remontent pas encore dans les résultats de recherche des transactions (text_search) et ne sont pas encore modifiables depuis l’application web.
Ajouter des métadonnées lors de l’ajout d’un document
Pour définir des métadonnées lorsque vous ajoutez un document à votre transaction, envoyez une requête à POST /v1/transactions/{transaction_id}/documents et transmettez l’argument metadata, suivi de la clé de métadonnée entre crochets (par exemple metadata[contract_ref]) :
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents \
-d document=file_d0bDo8LgEkEA \
-d name=Contrat.pdf \
-d metadata[contract_ref]=C-2026-001 \
-d metadata[case_number]=2026-0042
Si vous envoyez une Full transaction request, transmettez les métadonnées dans l’objet documents[].metadata :
"documents" : [{
"file_id" : "file_d0bDo8LgEkEA",
"name" : "Contrat.pdf",
"metadata" : {
"contract_ref" : "C-2026-001",
"case_number" : "2026-0042"
},
"fields" : [ ... ]
}]
Modifier les métadonnées d’un document
Pour modifier les métadonnées d’un document, envoyez une requête à POST /v1/transactions/{transaction_id}/documents/{document_id} et transmettez l’argument metadata. Vous pouvez le faire tant que le document n’a pas été signé ou validé par un participant.
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents/doc_wWz6 \
-d metadata[contract_ref]=C-2026-002 \
-d metadata[case_number]=""
Dans la requête ci-dessus, la nouvelle valeur de la métadonnée contract_ref (C-2026-002) remplace la valeur précédemment transmise (C-2026-001), et la métadonnée case_number est supprimée car sa valeur est vide.
Pour supprimer une métadonnée, transmettez sa clé avec une valeur vide.
Récupérer les métadonnées d’un document
Les métadonnées de document sont renvoyées dans l’objet documents[].metadata lorsque vous récupérez une transaction ou une transaction archivée :
"documents" : [ {
"id" : "doc_wWz6",
"name" : "Contrat.pdf",
"metadata" : {
"contract_ref" : "C-2026-001",
"case_number" : "2026-0042"
}
} ]
Erreurs
L’API renvoie une erreur 400 dans les cas suivants :
| Cas | error_description |
|---|---|
| Plus de 15 métadonnées | we can't have more than 15 metadata entries |
| Clé de métadonnée de plus de 20 caractères | metadata keys length can't have more than 20 characters |
| Valeur de métadonnée de plus de 200 caractères | metadata values length can't have more than 200 characters |
{
"type": "invalid_request_error",
"error_description": "we can't have more than 15 metadata entries"
}
Pour les métadonnées au niveau de la transaction, consultez Ajouter des métadonnées à la transaction.
Importer un document à partir d’une URL (demande de transaction complète uniquement)
Si vous envoyez une Full transaction request, vous pouvez importer un document directement à partir d’une URL. Cette fonctionnalité vous permet de contourner les contraintes liées au téléchargement de documents.
Notez que cette fonctionnalité doit être activée sur votre espace de travail. Si vous souhaitez l’activer, vous devez contacter votre gestionnaire de compte chez Universign.
Vous devez d’abord autoriser l’URL dans votre espace de travail. Pour plus d’information, consultez URL des documents.
Ensuite, dans votre Full transaction request, transmettez l’URL dans l’argument URL. Notez que l’argument URL ne doit pas être transmis si le document content ou file_id est défini.
Important : Assurez-vous que l’URL mène au document lui-même et non à son emplacement.
"documents" : [{
"url" : "https://getsamplefiles.com/download/pdf/sample-1.pdf",
"name" : "MyDoc",
"fields" : [
{
"id" : "field_id_1",
"name" : "signature field",
"page" : 1,
"x" : 150,
"y" : 275,
"type" : "signature",
"consents" : [ "I hereby accept the terms and conditions stated in this document!" ],
"optional_consents" : [ "I accept to fill a satisfaction form once the signature process is completed!" ]
},{
"id" : "field_id_2",
"name" : "signature field 2",
"page" : 1,
"x" : 175,
"y" : 200,
"type" : "signature"
}]
}],
