Inviare una richiesta di firma

Ogni richiesta di firma è sempre collegata a un dossier e viene inviata al cittadino attraverso l'AppIO. All'interno dell'applicazione, il cittadino può consultare i documenti contenuti nella richiesta, visualizzare le firme previste, selezionare quelle desiderate e infine applicarle.

Per procedere alla creazione di una richiesta di firma sono necessari:

• Il codice fiscale del firmatario

• Il riferimento al dossier

• I documenti da firmare in formato PDF

È inoltre possibile specificare una data entro la quale il cittadino può completare il processo di firma (di default entro 3 mesi) e decidere se notificare la richiesta tramite un messaggio sull'AppIO.

Chi può creare una richiesta di firma?

Affinché sia possibile creare una richiesta di firma, l'utente deve essere dotato del ruolo di Request Editor per il dossier correlato alla richiesta che si intende creare.

Una volta create, le richieste di firma non possono più essere modificate, ma solo cancellate ed eventualmente ricreate. Le richieste vengono create in stato Draft ed elaborate dal sistema fino alla loro pubblicazione, scarto o cancellazione.

Tramite applicazione web

Accedendo alla console di gestione è possibile creare una richiesta di firma accedendo al menù corrispondente e selezionando il pulsante "Crea richiesta". Nella form conseguente è necessario inserire almeno i dati obbligatori.

La console verifica a-priori che il firmatario disponga dell'AppIO necessaria alla firma. Un simbolo grafico a fianco del dato indica l'esito della verifica e la form potrà essere sottomessa solo in caso di esito positivo.

Completando la form si viene indirizzati alla pagina di dettaglio della richiesta appena creata potendo da qua monitorarne la lavorazione.

I tempi di pubblicazione dipendono dalla frequenza di esecuzione dei batch di elaborazione e dal carico del sistema.

Tramite servizi REST

La creazione di una richiesta di firma si articola in tre fasi:

1. Verifica che il firmatario disponga dell'AppIO

2. Upload dei documenti PDF

3. Creazione della richiesta di firma

La verifica che il firmatario disponga dell'AppIO è opzionale ed evita che la successiva richiesta venga scartata per questo motivo.

Find signer id

POSThttps://example.com/api/v1/utils/find-signer

Body

application/json

fiscal_code*FiscalCode (string (FiscalCode))

User's fiscal code.

Example: "SPNDNL80R13C555X"

Response

200404

The signer detail

Body

application/json

idIoId (string)

Identificativo assegnato da Firma con IO

Example: "01GG4TG9FP2D3JPWFTAM0WEFTG"

fiscal_code*FiscalCode (string (FiscalCode))

User's fiscal code.

Example: "SPNDNL80R13C555X"

Request

JavaScriptCurlPython

const response = await fetch('https://example.com/api/v1/utils/find-signer', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "fiscal_code": "SPNDNL80R13C555X"
    }),
});
const data = await response.json();

Response

200404

{
  "id": "01GG4TG9FP2D3JPWFTAM0WEFTG",
  "fiscal_code": "SPNDNL80R13C555X"
}

Ciascun documento PDF previsto dal dossier deve essere poi caricato su sistema ed acquisito l'identificativo da utilizzare nella successiva richiesta di firma:

Upload a document

POSThttps://example.com/api/v1/documents

Body

application/pdf

string (binary)

Response

201401403default

The uploaded document details

Body

application/json

idId (number (int64))

Entity Id

Example: 123

created_atTimestamp (string (date-time))

_linksobject

Request

JavaScriptCurlPython

const response = await fetch('https://example.com/api/v1/documents', {
    method: 'POST',
    headers: {
      "Content-Type": "application/pdf"
    },
    body: JSON.stringify("binary"),
});
const data = await response.json();

Response

201401403default

{
  "id": 1234,
  "created_at": "2022-12-31T23:59:59Z",
  "_links": {
    "self": {
      "href": "https://www.example.com/documents/1234"
    },
    "download": {
      "href": "https://www.example.com/documents/1234/download"
    },
    "created_by": {
      "href": "https://www.example.com/users/789",
      "embeddable": true
    }
  }
}

Deve essere infine creata la richiesta di firma indicando la lista dei documenti caricati in precedenza. E' possibile in questa fase fornire dei metadati diversi da quelli previsti dal dossier, una data di scadenza della richiesta di firma e specificare se inviare un messaggio al firmatario in occasione della pubblicazione:

Create a Signature Request

POSThttps://example.com/api/v1/signature-requests

Body

application/json

dossierDossierRef (one of)

objectobject

signerobject

expires_atTimestamp (string (date-time))

documents*array of DocumentUnassigned (object)

Response

201401403422429default

The Signature Request detail

Body

application/json

id*Id (number (int64))

Entity Id

Example: 123

status*SignatureRequestStatus (enum)

DRAFTREQUESTABLEUPLOADABLEREADYPUBLISHEDSIGNEDREJECTEDCANCELLED

signer*SignerDetailView (object)

documents*array of DocumentDetailView (object)

notificationNotificationDetailView (object)

expires_at*Timestamp (string (date-time))

created_at*Timestamp (string (date-time))

updated_at*Timestamp (string (date-time))

signed_atTimestamp (string (date-time))

rejected_atTimestamp (string (date-time))

reject_reasonstring

qr_code_urlstring (uri)

cancelled_atTimestamp (string (date-time))

_linksobject

Request

JavaScriptCurlPython

const response = await fetch('https://example.com/api/v1/signature-requests', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "documents": [
        {
          "id": 123
        }
      ]
    }),
});
const data = await response.json();

Response

201401403422429default

{
  "id": 123,
  "status": "DRAFT",
  "signer": {
    "id": "01GG4TG9FP2D3JPWFTAM0WEFTG",
    "fiscal_code": "SPNDNL80R13C555X"
  },
  "documents": [
    {
      "id": 1234,
      "created_at": "2022-12-31T23:59:59Z",
      "_links": {
        "self": {
          "href": "https://www.example.com/documents/1234"
        },
        "download": {
          "href": "https://www.example.com/documents/1234/download"
        },
        "created_by": {
          "href": "https://www.example.com/users/789",
          "embeddable": true
        }
      }
    }
  ],
  "notification": {
    "io_message_id": "01GG4TG9FP2D3JPWFTAM0WEFTG"
  },
  "expires_at": "2024-09-30T01:22:10.966Z",
  "created_at": "2024-09-30T01:22:10.966Z",
  "updated_at": "2024-09-30T01:22:10.966Z",
  "signed_at": "2024-09-30T01:22:10.966Z",
  "rejected_at": "2024-09-30T01:22:10.966Z",
  "reject_reason": "text",
  "qr_code_url": "https://example.com",
  "cancelled_at": "2024-09-30T01:22:10.966Z",
  "_links": {
    "dossier": {
      "href": "https://example.com",
      "embeddable": false
    },
    "requested_by": {
      "href": "https://example.com",
      "embeddable": false
    }
  }
}