EU-SES Signature Migration Guide

Here is a step-by-step guide to migrate from the old Digital Signature API to the new eSignature API. Please note that the old API has been deprecated and support for it will end on December 31, 2026.

1. Base Domain Changes (Base URL)

The first step in the migration process is updating your API call domains to point to the new eSignature servers:

• Production: change from https://ws.firmadigitale.com to https://esignature.openapi.com.
• Sandbox: change from https://test.ws.firmadigitale.com to https://test.esignature.openapi.com.

2. Endpoint Mapping

The old /firma_elettronica endpoints have been replaced and reorganized within the new eSignature API, introducing a distinction between the signature creation endpoint /EU-SES, the endpoint used to access the historical list of signatures /signatures, and the endpoint for retrieving details of a single signed document /signatures/{id}/{actionType}.

Below is the exact mapping for the migration:

Simple Electronic Signature (SES) Request Creation

Retrieving the Signature / Request List

Retrieving Information / Details for a Specific Request

Downloading the Signed Document

Retrieving the Audit Trail

Document Deletion (New Feature)

3. Changes to UI Customization Mode

In the previous API there were dedicated endpoints for creating and managing custom graphical interfaces (/firma_elettronica_ui) for the signature iframe. These endpoints (POST, GET and DELETE /firma_elettronica_ui) have already been marked as DEPRECATED.

The new API overcomes all the limitations of the previous version and allows unlimited interfaces to be created directly during the POST /EU-SES request by passing all customization information through the available option fields.

These are the optional settings used to customize the user interface displayed to the end user or the signing mode:

1. Colors and Style (Theming)

All color parameters require a hexadecimal string (HEX) following the pattern: ^#[0-9a-fA-F]{6}$.

Sidebar Area

Header & Footer Area

Standard Buttons

Signature / Workflow Buttons (Sign Button)

2. Visibility and Behavior

These parameters control the display of interface elements. The default value is false for all boolean fields.

3. Integration and Redirection

Parameters used to manage application embedding and the post-operation navigation flow.

4. Document Retention in the New API

An important aspect of the new API to consider during migration is the retention policy. In the new eSignature API:

• Signed, validated, and uploaded documents will remain available for download in the system for up to 90 days, after which they will be automatically deleted.
• Structured signature data and the audit trail will be retained for up to 10 years.

Make sure your backend processes are updated to download the final file from /signatures/{id}/signedDocument and archive it within your own systems during the 90-day retention window.

5. Request Body Differences (POST)

The payload for creating a new signature request (POST /EU-SES) has undergone significant changes compared to the previous endpoint POST /firma_elettronica/base.

Old Request Body (Example)

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

New Request Body (Example)

{
  "signers": [
    {
      "name": "Mario",
      "surname": "Rossi",
      "email": "[email protected]",
      "mobile": "+393333333333",
      "message": "Hello Mario, {OTP} is the code to enter...",
      "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 Migration Mapping and Key Points

Details of the New Callback Object

The callback object (sent within the POST /EU-SES request) defines the webhook configuration that the eSignature platform will use to notify the external application about signature request status changes.

The supported callback configuration fields are described below:

Complete Configuration Example:

{
    "callback": {
        "url": "https://www.yoursite.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. New Signature Response Body

The response body returned by the request:

POST /EU-SES

has been enhanced in the new eSignature API to immediately provide not only the unique ID of the created request and the redirect URL for the signing interface, but also the updated status of the entire request, the signer user ID, and the specific URL for signer access.
Below is an example of the extended response body:

{
    "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": "Hello Mario, {OTP} is the code to enter to confirm the signing process",
                "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": {}
}}

Callback Response Body Details (DONE Status Example)

The provided example represents a typical callback body sent by the new eSignature API when the status of a signature request reaches a significant state, in this case DONE.

Key Details Analysis

Signer Details (signers Array)

Documents (document Section)

In a DONE state, detailed information is provided both for the validated original document and for the signed document:

Recommended Action:

Since the status is DONE and the signedDocument field is available, the next step in your system should be to use the primary ID (69aaada4adb8b5c80203553d) to execute a GET /signatures/{id}/signedDocument request and download the signed file. Remember that the document is retained for only 90 days.