Migrationsleitfaden von Elektronische_Signatur zu EU-SES

Hier ist eine Schritt-für-Schritt-Anleitung zur Migration von der alten Digital Signature API zur neuen eSignature API. Bitte beachten Sie, dass die alte API veraltet ist und ihr Support am 31. Dezember 2026. endet.

1. Änderung der Basis-Domains (Base URL)

Der erste Schritt der Migration besteht darin, die Domains Ihrer API-Aufrufe so zu aktualisieren, dass sie auf die neuen eSignature-Server verweisen:

• Produktion: von https://ws.firmadigitale.com zu https://esignature.openapi.com.
• Sandbox: von https://test.ws.firmadigitale.com zu https://test.esignature.openapi.com.

2. Endpoint-Mapping

Die alten /firma_elettronica-Endpoints wurden in der neuen eSignature API ersetzt und neu strukturiert. Dabei wird zwischen dem Endpoint zur Erstellung einer Signatur /EU-SES, dem Endpoint zum Abrufen der Signaturhistorie /signatures sowie dem Endpoint für Details eines einzelnen signierten Dokuments /signatures/{id}/{actionType} unterschieden.

Hier ist das exakte Mapping für die Migration:

Erstellung einer einfachen elektronischen Signatur (SES)

Abruf der Signatur-/Anfrageliste

Abruf von Informationen / Details einer bestimmten Anfrage

Download des signierten Dokuments

Abruf des Audit Trails

Löschen von Dokumenten (Neue Funktion)

3. Änderung des UI-Anpassungsmodus

In der alten API gab es dedizierte Endpoints zur Erstellung und Verwaltung benutzerdefinierter Oberflächen (/firma_elettronica_ui) für das Signatur-iframe. Diese Endpoints (POST, GET und DELETE /firma_elettronica_ui) wurden bereits als VERALTET markiert.

Die neue API hebt alle Einschränkungen der vorherigen Version auf und ermöglicht es, unbegrenzt viele Interfaces direkt im Rahmen der POST /EU-SES-Anfrage zu erstellen, indem alle Anpassungsinformationen in den Optionsfeldern übergeben werden.

Dies sind die optionalen Parameter zur Anpassung der Benutzeroberfläche oder des Signaturverhaltens:

1. Farben und Stil (Theming)

Alle Farbparameter erfordern einen Hex-String (HEX) im Format: ^#[0-9a-fA-F]{6}$.

Sidebar-Bereich

Header- & Footer-Bereich

Standard-Buttons

Signatur- / Prozess-Buttons

2. Sichtbarkeit und Verhalten

Diese Parameter steuern die Anzeige von UI-Elementen. Der Standardwert ist für alle booleschen Felder false.

3. Integration und Weiterleitung

Parameter zur Steuerung der Einbettung der Anwendung und des Weiterleitungsflusses nach Abschluss.

4. Dokumentenaufbewahrung in der neuen API

Ein wichtiger Aspekt der neuen API, der bei der Migration berücksichtigt werden muss, ist die Aufbewahrungsrichtlinie. In der neuen eSignature API gilt:

• Signierte, validierte und hochgeladene Dokumente bleiben bis zu 90 Tage im System zum Download verfügbar und werden danach automatisch gelöscht.
• Strukturierte Signaturdaten und der Audit Trail werden bis zu 10 Jahre aufbewahrt.

Stellen Sie sicher, dass Ihre Backend-Prozesse aktualisiert werden, um die finale Datei über /signatures/{id}/signedDocument herunterzuladen und innerhalb des 90-Tage-Zeitraums in Ihren Systemen zu archivieren.

5. Unterschiede im Request Body (POST)

Das Payload zur Erstellung einer neuen Signaturanfrage (POST /EU-SES) hat im Vergleich zum alten Endpoint POST /firma_elettronica/base erhebliche Änderungen erfahren.

Alter Request Body (Beispiel)

{
  "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..."
}

Neuer Request Body (Beispiel)

{
  "signers": [
    {
      "name": "Mario",
      "surname": "Rossi",
      "email": "[email protected]",
      "mobile": "+393333333333",
      "message": "Hallo Mario, {OTP} ist der Code zur Eingabe...",
      "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"
  }
}

Payload-Mapping und Migrationspunkte

Details des neuen Callback-Objekts

Das callback-Objekt (gesendet in der POST /EU-SES-Anfrage) definiert die Webhook-Konfiguration, die von der eSignature-Plattform verwendet wird, um externe Systeme über Statusänderungen einer Signaturanfrage zu informieren.

Die unterstützten Felder sind unten beschrieben:

Vollständiges Konfigurationsbeispiel:

{
    "callback": {
        "url": "https://www.your-site.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": "Human Resources"
        }
    }
}

6. Antwortkörper der neuen Signatur

Der Antwortkörper der Anfrage:

POST /EU-SES

wurde in der neuen eSignature API erweitert, um sofort nicht nur die eindeutige ID der erstellten Anfrage und die Weiterleitungs-URL zur Signatur-Oberfläche bereitzustellen, sondern auch den aktuellen Status der gesamten Anfrage, die Signierer-ID sowie die spezifische URL für den Zugriff des Signierenden.
Nachfolgend ein Beispiel des erweiterten Response-Bodys:

{
    "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": "Hallo Mario, {OTP} ist der Code zur Eingabe zur Bestätigung des Signaturprozesses",
                "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": {}
    }
}

Details des Callback-Bodys (Beispiel DONE-Status)

Das folgende Beispiel zeigt einen typischen Callback-Body, der von der eSignature API gesendet wird, wenn der Status einer Signaturanfrage einen finalen Zustand wie DONE erreicht.

Wichtige Analysepunkte

Details des Signierenden (signers)

Dokumente (Bereich document)

Im Status DONE werden sowohl das validierte Originaldokument als auch das signierte Dokument detailliert bereitgestellt:

Empfohlene Aktion:

Da der Status DONE ist und das Feld signedDocument vorhanden ist, sollte Ihr System im nächsten Schritt die ID (69aaada4adb8b5c80203553d) verwenden, um einen Aufruf GET /signatures/{id}/signedDocument durchzuführen und das signierte Dokument herunterzuladen. Beachten Sie, dass das Dokument nur 90 Tage im System verfügbar ist.