💼 Updating a Deed

A step-by-step guide to operate on a simple deed through the API.

🤔 What's a Deed?

Head over to the Entities page to understand what a ✍️Deed entity is and all the different kinds of deeds.

🤔 How do I create a Deed?

Head over to the Entities page to understand how to create ✍️Deed entity through the API.

📄 Uploading documents to the deed

A deed would be particularly useless without any documents attached to it, don't you think? Let's fix this issue by uploading a document to our newly created deed with the following 📌API request:

Node.js

// Read file from somewhere on disk (this is just an example, the file might be downloaded from URL or extracted from a DB)
const file = await fs.promises.readFile("/path/to/file");

// Prepare deed document metadata (follows DeedDocumentBean model)
const deedDocument = {
    deedId: 60123,
    filename: "test.pdf",
    origin: "ATTACHMENT",
    participantVisibility: [40123, 40124]
};

// Upload with multipart/form-data
const form = new FormData();
form.set("file", file);
form.set("document", deedDocument);
form.set("isVirtualMeetingActive", false);

const res = await fetch("https://staging.gayadeed.it/gaya/protected/folder", {
    method: "POST",
    headers: {
        "Content-Type": "multipart/form-data",
        "Authorization": accessToken
    },
    body: form
});
const response = await res.json();

The API returns true if the upload is successful, false otherwise (with a non-OK status code). Some notes on the required params:

• deedId: Refers to the deed where we want to upload this document.
• filename: Remember that it must include the extension (e.g. .pdf).
• origin: Can be ATTACHMENT, INFOCERT, SIGNATURE_POINTS, TEMPLATE. In this case we are using ATTACHMENT because we want the document to be just attached to the deed. More details can be found on this page.

♻️ Updating the deed

Updating the deed can be done with the following 📌API request:

Node.js

const deedId = 60123;

const res = await fetch(`https://staging.gayadeed.it/gaya/protected/deed/update/${deedId}`, {
    method: "PUT",
    headers: {
        "Content-Type": "application/json",
        "Authorization": accessToken
    },
    body: JSON.stringify({
        dossierDescription: "Updated description",
        paperworkSerialNumber: "2/2023",
        signDate: "2022-04-07",
        signHour: "15:30",
        signMode: "ASYNC"
    })
});
const response = await res.json();

Only a subset of values can be updated (most importantly, the signMode). If you need to update some other things, you'll need to delete and recreate the deed.

The API returns true if the update is successful, false otherwise (with a non-OK status code).

Updating deed documents

Let's say that the document we just uploaded was wrong. Instead of removing it and uploading it again, we can override it. There are 3 endpoints to perform this operation:

• Override just the document's file
• Override the document's metadata (and optionally the file too).

caution

Please keep in mind that these requests act on documents which have not been signed.

The last one is dedicated to update a document which has been signed. It is not possible to update metadata of a signed document, only its file.

🚧 TODO 🚧: Code examples

Deleting a deed document

Swagger reference here

🚧 TODO 🚧: Code example

🗑️ Deleting the deed

Deleting the deed can be done with the following 📌API request:

Node.js

const deedId = 60123;

const res = await fetch(`https://staging.gayadeed.it/gaya/protected/deed/${deedId}`, {
    method: "DELETE",
    headers: { "Authorization": accessToken }
});
const response = await res.json();

The API returns true if the deletion is successful, false otherwise (with a non-OK status code).

🗄️Closing and archiving an ARCHIVE deed

An ARCHIVE deed is essentially created just to be archived, so this operation is fundamental.

caution

Please keep in mind that once a deed has been archived, it becomes frozen and impossible to update or delete, as it is also stored on an external third-party database.

Closing the deed also means archiving it, so it is not possible to re-open a deed once it has been closed.

To perform this operation, use the following 📌API request:

Node.js

const deedId = 60123;

const res = await fetch(`https://staging.gayadeed.it/gaya/protected/deed/close/${deedId}`, {
    method: "PUT",
    headers: { "Authorization": accessToken }
});
const response = await res.json();

The API returns true if the operation is successful, false otherwise (with a non-OK status code).

info

The archiving operation on the third-party database is executed asynchronously some time after the deed's closure, and it might fail. At the moment we do not have a way to alert the API user if the operation failed.

🗄️What about archiviation on FEA and FEQ deeds?

Archiviation on deeds which are not ARCHIVE is always automatically performed when the signature process is done.