Guide de migration de Signature_Électronique vers EU-SES

Voici un guide étape par étape pour migrer de l'ancienne API Signature Numérique vers la nouvelle API eSignature. Veuillez noter que l'ancienne API a été dépréciée et que son support prendra fin le 31 décembre 2026.

1. Modification des domaines de base (Base URL)

La première étape de la migration consiste à mettre à jour les domaines de vos appels API afin qu'ils pointent vers les nouveaux serveurs eSignature :

• Production : passez de https://ws.firmadigitale.com à https://esignature.openapi.com.
• Sandbox : passez de https://test.ws.firmadigitale.com à https://test.esignature.openapi.com.

2. Correspondance des endpoints

Les anciens endpoints /firma_elettronica ont été remplacés et réorganisés au sein de la nouvelle API eSignature, introduisant une distinction entre l’endpoint de création de signature /EU-SES, l’endpoint permettant d’accéder à l’historique des signatures /signatures, et celui permettant d’obtenir les détails d’un document signé spécifique /signatures/{id}/{actionType}.

Voici la correspondance exacte pour la migration :

Création d'une demande de Signature Électronique Simple (SES)

Récupération de la liste des signatures / demandes

Récupération des informations / détails d'une demande spécifique

Téléchargement du document signé

Récupération de la piste d’audit (Audit Trail)

Suppression de documents (Nouvelle fonctionnalité)

3. Modification du mode de personnalisation de l’interface utilisateur

Dans l’ancienne API, il existait des endpoints dédiés à la création et à la gestion d’interfaces graphiques personnalisées (/firma_elettronica_ui) pour l’iframe de signature. Ces endpoints (POST, GET et DELETE /firma_elettronica_ui) ont déjà été marqués comme DÉPRÉCIÉ.

La nouvelle API supprime toutes les limitations de la précédente et permet de créer un nombre illimité d’interfaces directement lors de la requête POST /EU-SES en transmettant toutes les informations de personnalisation dans les champs d’options disponibles.

Voici les paramètres optionnels permettant de personnaliser l’interface utilisateur visible par l’utilisateur final ou le mode de signature :

1. Couleurs et style (Thématisation)

Tous les paramètres de couleur nécessitent une chaîne hexadécimale (HEX) suivant le modèle : ^#[0-9a-fA-F]{6}$.

Zone Barre latérale (Sidebar)

Zone En-tête et Pied de page (Header & Footer)

Boutons standards

Boutons de signature / procédure (Sign Button)

2. Visibilité et comportement

Ces paramètres contrôlent l’affichage des éléments de l’interface. La valeur par défaut est false pour tous les champs booléens.

3. Intégration et redirection

Paramètres utilisés pour gérer l’intégration de l’application et le flux de navigation après l’opération.

4. Conservation des documents dans la nouvelle API

Un aspect important de la nouvelle API à prendre en compte lors de la migration est la politique de conservation des données. Dans la nouvelle API eSignature :

• Les documents signés, validés et importés resteront disponibles au téléchargement dans le système pendant un maximum de 90 jours, après quoi ils seront automatiquement supprimés.
• Les données structurées de signature et la piste d’audit seront conservées pendant un maximum de 10 ans.

Assurez-vous que vos processus backend sont mis à jour afin de télécharger le fichier final depuis /signatures/{id}/signedDocument et de l’archiver dans vos systèmes pendant la fenêtre de conservation de 90 jours.

5. Différences du corps de requête (POST)

Le payload utilisé pour créer une nouvelle demande de signature (POST /EU-SES) a subi des modifications importantes par rapport à l’ancien endpoint POST /firma_elettronica/base.

Ancien corps de requête (Exemple)

{
  "members": [
    {
      "firstname": "Mario",
      "lastname": "Rossi",
      "email": "[email protected]",
      "phone": "+393333333333",
      "signs": [
        {
          "page": 1,
          "position": "100,200,45,35"
        }
      ]
    }
  ],
  "callback": {
    "headers": {
      "custom": "test"
    },
    "field": "data",
    "url": "https://webhook.site/12345678"
  },
  "content": "JVBERi0xLjQNCiWio4+TD..."
}

Corps de requête (nouvelle version - exemple)

{
  "signers": [
    {
      "name": "Mario",
      "surname": "Rossi",
      "email": "[email protected]",
      "mobile": "+393333333333",
      "message": "Bonjour Mario, {OTP} est le code à saisir...",
      "authentication": [
        "sms"
      ],
      "signatures": [{
        "page": 1,
        "x": "100",
        "y": "200"
      }]
    }
  ],
  "options": {
    "signatureMode": [
      "drawn"
    ],
    "ui": {
      "sidebarLogo": "https://www.your-company.com/logo.png",
      "buttonBackgroundColor": "#0a5aa6"
    }
  },
  "inputDocuments": {
    "sourceType": "base64",
    "payload": "JVBERi0xLjQK..."
  },
  "callback": {
    "url": "https://webhook.site/12345678"
  }
}

Mappage du payload et points clés de migration

Détails du nouvel objet callback

L’objet callback (envoyé dans la requête POST /EU-SES) définit la configuration du webhook utilisée par la plateforme eSignature pour notifier l’application externe des changements de statut d’une demande de signature.

Les champs pris en charge sont décrits ci-dessous :

Exemple de configuration complète :

{
    "callback": {
        "url": "https://www.votresite.com/api/webhook/signature",
        "method": "JSON",
        "field": "data",
        "retry": 3,
        "headers": {
            "Authorization": "Bearer your_security_token",
            "X-Custom-Header": "custom_value"
        },
        "custom": {
            "internal_case_id": "PRT-98765",
            "department": "Ressources Humaines"
        }
    }
}

6. Corps de réponse de la nouvelle signature

Le corps de réponse de la requête :

POST /EU-SES

a été enrichi dans la nouvelle API eSignature afin de fournir immédiatement non seulement l’ID unique de la demande créée et l’URL de redirection vers l’interface de signature, mais aussi le statut mis à jour de l’ensemble de la demande, l’ID du signataire et l’URL spécifique d’accès au signataire.
Voici un exemple du corps de réponse étendu :

{
    "data": {
        "id": "69aaa647adb8b5c802035539",
        "errorNumber": null,
        "errorMessage": null,
        "updatedAt": "2026-03-06 10:02:47.980+00:00",
        "createdAt": "2026-03-06 10:02:47.979+00:00",
        "certificateType": "EU-SES",
        "state": "WAIT_VALIDATION",
        "signatureType": "pades",
        "signers": [
            {
                "authentication": [
                    "sms"
                ],
                "name": "Mario",
                "state": "NEW",
                "surname": "Rossi",
                "mobile": "+393333333333",
                "mobileEditable": false,
                "email": "[email protected]",
                "emailEditable": false,
                "id": "b99f85d9-8482-4970-b57d-ff6703a98818",
                "url": "https://esign.openapi.com/b99f85d9-8482-4970-b57d-ff6703a98818",
                "language": "browser",
                "message": "Bonjour Mario, {OTP} est le code à saisir pour confirmer la procédure de signature",
                "mobileValidation": {
                    "isPossible": true,
                    "isValid": true,
                    "regionCode": "IT",
                    "countryCode": "39",
                    "isValidNumberForRegion": true,
                    "numberType": "MOBILE",
                    "otpAttempts": 0
                }
            }
        ],
        "options": {
            "asyncDocumentsValidation": true,
            "asyncSignature": false,
            "signatureMode": [
                "typed"
            ],
            "withTimestamp": false,
            "timezone": "UTC"
        },
        "document": {}
    }
}

Détails du corps de callback (exemple état DONE)

L’exemple fourni représente un corps de callback typique envoyé par la nouvelle API eSignature lorsque le statut d’une demande de signature atteint un état significatif, dans ce cas DONE.

Analyse des éléments clés

Détails du signataire (signers)

Documents (section document)

Dans un état DONE, des informations détaillées sont fournies à la fois pour le document original validé et pour le document signé :

Action recommandée :

Étant donné que le statut est DONE et que le champ signedDocument est présent, l’étape suivante dans votre système doit être d’utiliser l’ID principal (69aaada4adb8b5c80203553d) pour effectuer un appel GET /signatures/{id}/signedDocument et télécharger le fichier signé. N’oubliez pas que le document est conservé uniquement pendant 90 jours.