DevPortalPagoPA

Table of contents

💼 Create the dossier

Now you must create the dossier, a container that identifies the set of document metadata to be signed within a signature request. It makes it possible to group the signature requests by type of contract.
Each dossier represents a specific use case. For example, you can create a dossier for documents for scholarships, called “Scholarship request”, and another “Insurance contract” for educational collaboration contracts. This makes it possible to create the signature requests for users, reusing the same dossier. In fact, all students who must sign contracts to request a scholarship must receive a signature request created based on the same dossier (in this example, “Scholarship request”).
The signature requests for the same dossier can have in common the title, email of reference and often also the signatures to be inserted. For this reason it is easier to create a dossier also for the revision of signatures.
The title of the dossier will also be specified in the signature request message to the citizen:

An example

Here is an example of a call to the endpoint:
POST /api/v1/sign/dossiers
Imagine you have to create a dossier for the signature of a 150 hour contract ("title":"150 hour contract").
The dossier has only one document ("title":"Contract"), which in turn requires only one signature ("title":"Sign contract") required ("type":"REQUIRED") by the user.

Do you want to add other documents to the dossier?

A dossier can have multiple documents. You can send multiple PDF documents to be signed in a single request, entering a subject for each document in the list documents_metadata.

Do you want to add a specific support email for the dossier?

When creating a dossier, you can enter a specific support email for that dossier. support_email is an optional field. If it is not specified, the default mail entered during the onboarding phase will be used by default.

Did you create signature fields with coordinates?

In this case, the body of the message will be:
1{
2   "title": "150 hour contract",
3   "documents_metadata":[
4      {
5         "title":"Contract",
6         "signature_fields":[
7            {
8               "clause":{
9                  "title":"Sign contract",
10                  "type":"REQUIRED"
11               },
12               "attrs":{
13                  "coordinates":{
14                     "x":360,
15                     "y":100
16                  },
17                  "size":{
18                     "w":170,
19                     "h":30
20                  },
21                  "page":1
22               }
23            }
24         ]
25      }
26   ],
27   "support_email": "demo@assistenza.it"
28}
29

Did you not create the signature fields (transparent signature)?

In this case, the body of the message will be:
1{
2   "title": "Sign contract",
3   "documents_metadata":[
4      {
5         "title":"Contract",
6         "signature_fields":[]
7      }
8   ]
9}
10
In all cases, the response received will contain the dossier created with the relative associated ID (dossier_id).
1{
2   "id":"01GG4NFBCN4ZH8ETCCKX3766KX",
3   "title": "150 hour contract",
4   "documents":[
5      {
6         "title":"Contract",
7         "signature_fields":[
8            {
9               "unique_name":"Signature1",
10               "clause":{
11                  "title":"Sign contract",
12                  "type":"REQUIRED"
13               }
14            }
15         ]
16      }
17   ]
18}
19
In this case, of course, it is assumed that the only transparent signature needed to sign the document is required, for this reason the "type":"REQUIRED” was added. In general, in fact, at least one signature must be required or unfair, documents with only optional signatures are not accepted.
How can you indicate if signatures are required, optional or vessatorie?
  • To indicate that the signature is required, enter the "type":"REQUIRED"
  • To indicate that the signature is unfair, insert the "type":"UNFAIR"
  • To indicate that the signature is optional, enter the "type":"OPTIONAL"

On this page

An example

Need help during integration?

Write an e-mail describing your problem or question to the address

io‑service‑management@pagopa.it

Ongoing support

For problems or questions after integration, write to us at the address enti-firmaconio@assistenza.pagopa.it