Creare un dossier

Un dossier è un contenitore che identifica l'insieme dei metadati dei documenti da firmare all'interno di una richiesta di firma. Ti consente di raggruppare le richieste di firma per tipologia di contratto.

Ciascun dossier rappresenta un caso d’uso specifico. Ad esempio, potresti creare un dossier per i documenti delle borse di studio, denominato “Richiesta Borsa di studio”, e un altro “Contratto di assunzione” per i contratti di collaborazione. In questo modo, è possibile creare le richieste di firma verso gli utenti riutilizzando lo stesso dossier.

Creare un dossier

Chi può creare i dossier?

Affinché sia possibile creare un dossier, l'utente deve essere dotato del ruolo di Dossier Editor nell'organizzazione correlata al dossier che si intende creare.

Per creare un Dossier devono essere individuati:

• Un titolo di massimo 75 caratteri, es “Contratto 150 ore”

• Un codice di riferimento, es “DPT-XII-CON-150h”

• Una email di assistenza per gli utenti firmatari (opzionale)

• Una email a cui notificare l'avvenuta firma (opzionale)

• I metadati di ciascun documento da firmare:

  • Un titolo di massimo 60 caratteri, es “Contratto”

  • Opzionalmente l'elenco delle firme previste e la loro posizione all'interno del documento.

Le informazioni presenti nei metadati dei documenti possono essere soggette a modifiche durante una richiesta di firma. È fortemente consigliabile progettare i documenti PDF destinati alla firma in modo tale che i metadati rimangano invariati, riducendo così la necessità di modificarli nelle richieste successive.

Cosa accade se non si specificano le firme previste?

In questo caso l’utente potrà inserire una sola firma digitale su tutto il documento che però non avrà alcun corrispettivo grafico (firma trasparente).

Create a Dossier

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

Body

application/json

organization_id*Id (number (int64))

Entity Id

Example: 123

reference_code*ReferenceCode (string)

Pattern: [a-zA-Z0-9\-]{3,35}

title*DossierTitle (string)

support_emailEmail (string (email))

Email for a specific dossier.

Example: "[e-mail]"

documents_metadata*DocumentMetadataList (array of DocumentMetadata (object))

Response

201400401403429default

The Dossier detail

Body

application/json

id*Id (number (int64))

Entity Id

Example: 123

reference_code*ReferenceCode (string)

Pattern: [a-zA-Z0-9\-]{3,35}

title*DossierTitle (string)

created_at*Timestamp (string (date-time))

support_emailEmail (string (email))

Email for a specific dossier.

Example: "[e-mail]"

notification_emailEmail (string (email))

Email for a specific dossier.

Example: "[e-mail]"

documents_metadata*DocumentMetadataList (array of DocumentMetadata (object))

version*Version (integer (int32))

_links*object

Request

JavaScriptCurlPython

const response = await fetch('https://example.com/api/v1/dossiers', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "organization_id": 724,
      "reference_code": "DPT-XVII-Contratto-150h",
      "title": "Contratto 150 ore",
      "support_email": "[e-mail]",
      "documents_metadata": [
        {
          "title": "Contratto",
          "signature_fields": [
            {
              "clause": {
                "title": "Accettazione contratto",
                "type": "REQUIRED"
              },
              "attrs": {
                "coordinates": {
                  "x": 360,
                  "y": 100
                },
                "size": {
                  "w": 170,
                  "h": 30
                },
                "page": 1
              }
            }
          ]
        }
      ]
    }),
});
const data = await response.json();

Response

201400401403429default

{
  "id": 1,
  "reference_code": "DPT-XVII-Contratto-150h",
  "title": "Contratto 150 ore",
  "created_at": "2022-12-31T23:59:59",
  "support_email": "[e-mail]",
  "notification_email": "[e-mail]",
  "version": 1,
  "documents_metadata": [
    {
      "title": "Contratto",
      "signature_fields": [
        {
          "clause": {
            "title": "Accettazione contratto",
            "type": "REQUIRED"
          },
          "attrs": {
            "coordinates": {
              "x": 360,
              "y": 100
            },
            "size": {
              "w": 170,
              "h": 30
            },
            "page": 1
          }
        }
      ]
    }
  ],
  "_links": {
    "self": {
      "href": "https://www.example.com/dossiers/1"
    },
    "organization": {
      "href": "https://www.example.com/organizations/123",
      "embeddable": true
    },
    "created_by": {
      "href": "https://www.example.com/users/678",
      "embeddable": true
    }
  }
}

Creare una nuova versione

Non è possibile modificare un dossier, ma è possibile crearne una nuova versione mantenedo il medesimo "Codice di riferimento".