Intégration API Universign
Nous développons votre connecteur Universign
Nous câblons l'API Universign à votre dossier métier pour créer les transactions, poser le bon niveau eIDAS et ramener le statut completed dans votre dossier. Du premier atelier de cadrage à la surveillance du flux.
- Équipe produit senior
- connecteurs de signature en production
- du cadrage au monitoring
À quoi sert l'intégration Universign et en quoi le contrat devient-il un objet métier ?
Universign est un prestataire de services de confiance qualifié eIDAS, proposant la signature électronique simple, avancée et qualifiée, le cachet électronique et l'horodatage. Son intégration permet à votre application d'envoyer un document à signer en choisissant le niveau de preuve requis, de suivre le statut de chaque signataire en temps réel, et de rapatrier la preuve de signature dans le dossier dès que la transaction est close. Le document cesse d'être une pièce jointe envoyée par email pour devenir un objet métier avec un statut juridique, une date et une valeur probante rattachés à votre processus.
Ce que nos clients branchent sur Universign
Logiciel immobilier, compromis et annexes
Compromis en level2 ou level4, cachet de l'agence sur les annexes, horodatage du dossier. Un connecteur, trois preuves.
Parapheur interne à politique fine
level1 au quotidien, bascule level4 sur les actes listés par la direction juridique. Le niveau n'est plus un second prestataire.
SaaS multi-tenant, Master Console
Un workspace Universign par client final, webhooks créés avec la clé master. L'éditeur opère plusieurs dossiers sans mélanger les secrets.
Relance sur motif, pas sur silence
action.stalled avec signature_refusal ou incorrect_name_prerequisite ouvre un ticket CRM. « Le client n'a pas signé » devient un motif actionnable.
Ce que ça change dans votre parcours
La technique au service d'un résultat mesurable : le bon niveau, un motif de blocage, une preuve de date.
Le bon niveau pour chaque document
Avenant, contrat cadre, acte : la politique interne choisit le niveau eIDAS. On évite de confondre signature avancée et qualifiée.
Cachet et horodatage dans le même flux
Personne morale et preuve de date dans le même parcours. Utile en notariat, immobilier, santé, finance.
Un blocage devient un motif lisible
Refus, certificat expiré, nom incorrect : votre produit arrête de traiter le silence comme une erreur technique.
La consommation est lisible par niveau
Vous voyez combien de signatures simples, avancées ou qualifiées partent. De quoi refacturer le surplus au métier qui l'a demandé.
Comment nous livrons votre connecteur Universign
Cadrage
Quels documents, quels min_signature_level réellement ouverts sur le workspace, Basic ou Bearer, Master Console ou clé workspace. On liste les cas limites avant d'écrire une ligne de code.
Développement
Machine à états transaction, idempotence sur POST transactions et start (409 Conflict nominal), vérif JWS PS256 via JWKS, file d'attente.
Recette
Alpha pour le flux. Une recette « qui marche en level1 » ne prouve rien pour la QES : on rejoue chaque niveau ouvert. Pause n'arrête pas l'expiration.
Monitoring
Réconciliation GET transaction, consumptions/summary périodique, alerte sur 429 rate_limit_error. Vous savez qu'un flux est cassé avant vos clients.
Ce que permet l'API Universign
- Transactions et participants
- Création, start, pause, cancel. Durée par défaut 14 jours (20 160 minutes), max 60 jours, ou 180 si long-term activé. Pause n'arrête pas l'expiration.
- Cinq niveaux eIDAS
- level0/level1 = SES, level2 = AES, level3 = AES + certificat qualifié (pas une QES), level4 = QES. level0, 2, 3 et 4 dépendent des entitlements du workspace.
- Cachet, horodatage, identité
- Cachet qualifié personne morale, horodatage qualifié eIDAS, prévalidation d'identité pour level2 (prevalidation_id / certificat lcp).
- Webhooks JWS PS256
- Header x-jws-signature, algorithme PS256, clés JWKS. Retries 1 min, 5 min, 30 min, 2 h, 6 h, 24 h, 48 h. Universign ne journalise que les appels API en 200.
Le vocabulaire de l'API Universign
- min_signature_level
- level0 SES sans auth, level1 SES (défaut), level2 AES, level3 AES + certificat qualifié, level4 QES. Confondre level3 et level4 dans un devis juridique est une erreur de qualification eIDAS.
- completed vs closed
- closed : les actions sont terminées. completed : les documents étendus sont téléchargeables. Votre produit archive sur completed, pas sur closed.
- x-jws-signature
- JWS detached RFC 7515, algorithme PS256, kid dans le header. Ce n'est pas un HMAC. Un copier-coller Yousign échouera. JWKS prod : api.universign.com/v1/webhooks/jwks.json.
- action.stalled
- Événement avec raisons nommées (signature_refusal, incorrect_name_prerequisite, sealer_expired, etc.). À traiter comme un ticket métier, pas comme une 5xx.
- Entitlements workspace
- Le vrai catalogue produit. Sans eux, level0/2/3/4 ne sont pas appelables. Une recette sandbox en level1 ne prouve rien pour la QES.
- rate_limit_error
- Type renvoyé avec le 429. Aucun plafond chiffré n'est publié. Dimensionner un batch sans demander le quota au support, c'est le découvrir en production.
Les contraintes réelles de l'API Universign
level3 n'est pas une QES
C'est une AES adossée à un certificat qualifié. Seul level4 est documenté comme qualified signature. Confondre les deux dans un devis est une erreur eIDAS, pas un détail d'enum.
Les entitlements font le catalogue
Sans ouverture workspace, level0, 2, 3 et 4 ne sont pas appelables. On persiste la matrice avant d'exposer le choix dans l'UI. Le sandbox level1 ne suffit pas.
Le quota de débit n'est pas publié
La doc officielle nomme le 429 et rate_limit_error, pas un chiffre. Nous le demandons au support avant tout batch, plutôt que de le découvrir en production.
Pause n'allonge pas le délai
Une transaction paused continue d'expirer. Durée par défaut 14 jours à compter du start, max 60 jours (180 si long-term). La pause n'est pas une prolongation.
API Universign ou API Docusign ?
Deux APIs de signature eIDAS. Universign ajoute cachet et horodatage ; Docusign pèse quand le parc est déjà là.
| Critère | UniversignCette page | DocusignRéférence mondiale |
|---|---|---|
| Objet central | Transaction (draft → completed) | Envelope (GUID) |
| eIDAS SES / AES / QES | 5 levels ; level3 ≠ QES ; level4 = QES | SBS, signatureProviderName |
| Preuves annexes | Cachet et horodatage qualifiés | Pack envelope + Connect |
| Webhooks | JWS PS256 + JWKS | HMAC X-Docusign-Signature-1 |
| Authentification | Basic clé : ou Bearer | OAuth 2.0, JWT Grant |
| Quota API | 429 rate_limit_error, chiffre non publié | 3 000 / h, burst 500 / 30 s en prod |
| Le bon cas | Notariat, immobilier, finance FR | Parc Docusign déjà en place |
Les trois (Universign, Docusign, Yousign) couvrent SES, AES et QES. Aucune ne rend la QES gratuite ni iframe par défaut. C'est un arbitrage de cadrage, pas un choix définitif.
Ce que nous mesurons sur une intégration Universign
Les autres API de signature
Si Universign n'est pas le bon socle, ces options se discutent au cadrage.
UniversignNous développons votre connecteur UniversignCette page
DocusignEnvelope, SBS, Connect HMAC, go-live qui refuse le polling.
YousignAPI v3 française, SES AES QES en enum, iframe interdite en QES.On combine Universign avec
La stack qui entoure Universign sur nos projets.
Intégration Universign : vos questions
Trois étapes. D'abord une clé workspace (Basic -u API_KEY : ou Bearer) et, si vous opérez plusieurs clients, une clé master Master Console. Ensuite créer la transaction en draft, poser min_signature_level selon la politique interne, start, et traiter le 409 Conflict comme un retry nominal. Enfin les webhooks : vérifier x-jws-signature en PS256 avec le JWKS, répondre 2xx, file, déduplication sur evt_*. La partie sensible n'est pas le POST, c'est la matrice d'entitlements et le fait que level3 n'est pas une QES.
Mapping officiel : level0 et level1 = SES (level0 sans authentification, level1 défaut). level2 = AES. level3 = AES adossée à un certificat qualifié : ce n'est pas une QES. level4 = QES, seule valeur documentée « qualified signature », équivalence manuscrite dans toute l'Union (règlement (UE) n° 910/2014, art. 25 § 2). level0, 2, 3 et 4 dépendent des entitlements du workspace. Un devis qui vend du level3 comme une QES est une erreur de qualification, pas un détail d'API.
Non. La documentation officielle décrit le 429 et le type rate_limit_error, pas un plafond chiffré. Nous demandons le quota au support avant de dimensionner un batch, et nous lisons les réponses en production plutôt que de copier un chiffre de blog. C'est moins vendeur qu'une table, c'est plus juste. Un batch lancé « à l'aveugle » découvre le plafond en production : c'est exactement ce que le cadrage évite.
Un premier flux utile, typiquement une transaction level1 et le write-back sur completed, se livre en deux à trois semaines. Une chaîne level4, cachet, horodatage, Master Console et stalled_reason dans le CRM demande plutôt six à huit semaines : les entitlements et la vérif JWS pèsent autant que le code. Une recette « qui marche en level1 » ne prouve rien pour la QES. Nous cadrons le périmètre en amont et vous donnons une estimation ferme avant de commencer.
Universign si vous avez besoin du cachet et de l'horodatage qualifiés, d'une politique à cinq niveaux, et d'un prestataire de confiance français. Docusign si le parc est déjà là (envelope, Connect, go-live strict). Yousign si SES, AES et QES comme enum suffisent, avec iframe en SES/AES. Aucune ne rend la QES iframe par défaut. level3 Universign n'est pas une QES : le dire dans le devis évite une erreur juridique. Le choix est un arbitrage de parc et de politique de preuve.
Un projet d'intégration Universign ?
Parlons-en. 30 minutes pour cadrer vos transactions, le niveau eIDAS réellement ouvert sur le workspace et vous dire franchement ce qui est faisable.
Parler de mon projet Universign