# Introduzione

Iniziare a usare le api pubbliche di Timesafe.io

## Base path

Tutte le chiamate vengono effettuate al medesimo endpoint base

```
https://public-api.timesafe.io
```

## Stati degli oggetti

Le API trattano di fatto 2 oggetti base: **utenti** e **certificati.** Ecco gli stati in cui questi oggetti possono trovarsi:

#### Stati User

| Stato             | Significato                                                                                             |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| USER\_NOT\_ACTIVE | Questa utenza esiste ma non può essere ancora usata.                                                    |
| USER\_READY       | Questa utenza è pronta a essere usata ma non ha un Token assegnato (utente non ha mai effettuato login) |
| USER\_LOGGED      | L'utente ha effettuato un login.                                                                        |
| USER\_SUSPENDED   | Utenza sospesa                                                                                          |
| USER\_DELETED     | Utenza eliminata definitivamente.                                                                       |

#### Stati Certificate

| Stato                | Significato                                                                                                                                                                                                                                                              |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| JUST\_CREATED        | Questo certificato è stato creato da un User                                                                                                                                                                                                                             |
| SENT\_TO\_BLOCKCHAIN | Questo certificato è stato inviato alla Blockchain, ed è in attesa di essere inserito in un pool di mining.                                                                                                                                                              |
| TRANSACTION\_CREATED | Il certificato è inserito in una transazione da un miner.                                                                                                                                                                                                                |
| BLOCK\_SECURED       | Il blocco di cui fa parte la transazione è stato aggiunto alla blockchain ed ha un numero di conferme sufficiente a considerarlo immutabile.                                                                                                                             |
| LOST\_IN\_FORK       | <p>La transazione di questo certificato è su un blocco che è finito in una fork non confermata della blockchain. Verrà rimesso automaticamente in stato SENT\_TO\_BLOCCHAIN per essere riprocessato.</p><p>È estremamente improbabile che questo stato si verifichi.</p> |

## Postman

Di seguito i file per testare le API tramite Postman e il file di environment relativo. Il file di environment va modificato (da Postman o da editor testuale), inserendo il proprio Token per effettuare le chiamate.

{% file src="/files/-M8nf2CrJ61CYOKJeeFd" %}
TimeSafe API Client.postman.collection.json
{% endfile %}

{% file src="/files/-MRTxqXO5\_JV6NZQvidy" %}
TimeSafe Public API.postman\_environment.json
{% endfile %}

## Sandbox mode, Live mode

Le API pubbliche di Timesafe consentono l'utilizzo di una modalità sandbox\
Ogni untente ha a disposizione due credenziali, quelle di produzione (live mode) e quelle di test ( sandbox mode).\
Il funzionamento delle API è il medesimo, ma l'utenza Sandbox non salva le transazioni in blockchain e non esaurisce mai i crediti.\
Inoltre per gli utenti di tipo amministratore, in sandbox mode è impossibile creare nuove utenze (la chiamata ha successo ma restituisce dati mock-up)


# User

Lista degli endpoint per ottenere l'oggetto user

## Get user

<mark style="color:blue;">`GET`</mark> `https://public-api.timesafe.io/user`

Questo servizio permette di ottenere i dati dell'utente in uso.

#### Headers

| Name  | Type   | Description                             |
| ----- | ------ | --------------------------------------- |
| token | string | Token JWT ottenuto da endpoint di login |

{% tabs %}
{% tab title="200 Utente trovato" %}

```
{
    "status": "OK",
    "data": [
        {
            "id": 374862,
            "cf": MRARSS70A01F205K,
            "email": "mario.rossi@timesafe.io",
            "status": "USER_LOGGED",
            "credits": 99,
            "creation_date": "2020-01-01 01:01:01",
            "created_by": "Timesafe Admin",
            "can_create_users": true,
            "sandbox": true
        }
    ]
}
```

{% endtab %}

{% tab title="501 In caso il token non sia valido" %}

```
{
    "error": {
        "code": "5_topi_invalidi",
        "details": "This token is not valid."
    }
}
```

{% endtab %}
{% endtabs %}


# Login

## user/login

<mark style="color:green;">`POST`</mark> `https://public-api.timesafe.io/user/login`

Questo servizio permette di ottenere un token JWT da usare per le chiamate successive.

#### Request Body

| Name   | Type   | Description                                                                                                                                                                                                                                  |
| ------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ttl    | string | Time To Live specifica in secondi la durata che il token generato deve avere. Può valere un minimo di 5 e un massimo di 86400, oppure "one-time". In questo caso il token non ha scadenza temporale, ma può essere usato una volta soltanto. |
| secret | string | password dell'utente                                                                                                                                                                                                                         |
| email  | string | email o codice identificativo dell'utente.                                                                                                                                                                                                   |

{% tabs %}
{% tab title="200 Autenticazione avvenuta con successo, risponde con token JWT da usare per le successive chiamate e dati dell'utente.
Notare che i campi TTL e issued esistono solo se si è specificato in fase di login un TTL" %}

```
{
    "status": "OK",
    "data": {
        "id": 374862,
        "cf": 11044930961,
        "email": "alan@timesafe.io",
        "sandbox": true,
        "status": "USER_LOGGED",
        "ttl": "one-time",  
        "issued": 1590561214,
        "token": "eyJhbGciOiAiSFMyNTYiLCJ0eXAiOiAiSldUIn0=.eyJpZCI6IjM3NDg2MiIsImNmIjoiMTEwNDQ5MzA5NjEiLCJlbWFpbCI6ImFsYW5AdGltZXNhZmUuaW8iLCJzYW5kYm94Ijp0cnVlLCJzdGF0dXMiOiJVU0VSX0xPR0dFRCIsInR0bCI6Im9uZS10aW1lIiwiaXNzdWVkIjoxNTkwNTYxMjE0fQ==.n3HcNb0jbqIVELGjOmrugUThGWCNdM8b+YHVlaamjlA="
    }
}
```

{% endtab %}

{% tab title="501 In caso di dati errati o mancanti." %}

```
// WRONG PASSWORD
{
    "error": {
        "code": "Wrong password",
        "details": "Wrong password."
    }
}

// WRONG USER
{
    "error": {
        "code": "5_topi_invalidi",
        "details": "This email is not valid."
    }
}

// MISSING ARGUMENT
{
    "error": {
        "code": "3_asini_tristi",
        "details": "Missing argument email."
    }
}
```

{% endtab %}
{% endtabs %}


# User - Change Password

Endpoint per il cambio della password. Il sistema non effettua verifiche sul grado di sicurezza della password, che viene lasciato al buon senso dell'utente.

## user/change\_password

<mark style="color:green;">`POST`</mark> `https://public-api.timesafe.io/user/change_password`

Questo servizio permette di modificare la password, fornendo la precedente password e la nuova.

#### Headers

| Name  | Type   | Description                             |
| ----- | ------ | --------------------------------------- |
| token | string | Token JWT ottenuto da endpoint di login |

#### Request Body

| Name | Type   | Description      |
| ---- | ------ | ---------------- |
| new  | string | Nuova password   |
| old  | string | Vecchia password |

{% tabs %}
{% tab title="200 Password modificata con successo" %}

```
{
    "status": "OK",
    "data": []
}
```

{% endtab %}

{% tab title="501 La password corrente fornita non è valida, o mancano dei  parametri" %}

```
// UNCORRECT OLD PASSWORD 
{
    "error": {
        "code": "5_topi_invalidi",
        "details": "Wrong password."
    }
}

// MISSING PARAMETER
{
    "error": {
        "code": "3_asini_tristi",
        "details": [
            "This parameter is missing: ",
            "old"
        ]
    }
}
```

{% endtab %}
{% endtabs %}


# User - Create

Questo servizio permette la creazione di un'utenza con relativo wallet. Può essere chiamato solo da utenti di tipo admin.

## Create user

<mark style="color:blue;">`GET`</mark> `https://public-api.timesafe.io/user/create`

Questo servizio può essere chiamato solo da utenti che abbiano il permesso di creazione, ovvero che nella risposta alla chiamata get\_user abbiano il campo `can_create_users` settato a `TRUE`.\
Se questo servizio viene chiamato in sandbox mode, risponderà con dati di mockup, simili per formato a quelli reali.\
Per via dei tempi di creazione dei wallet del nuovo utente, la risposta può richiedere 5\~30 secondi.

#### Headers

| Name  | Type   | Description                             |
| ----- | ------ | --------------------------------------- |
| token | string | Token JWT ottenuto da endpoint di login |

#### Request Body

| Name  | Type   | Description                                                                                                                                                                                                                                                                                                                       |
| ----- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cf    | string | Il campo intende un codice fiscale, una partita iva o un identificativo univoco dell'utente nel mondo reale. Sebbene non venga controllato nel contenuto ma solo nella forma (deve essere univoco, alfanumerico e di massimo 20 caratteri), la sua utilità è nella verifica del dato da terzi, se ne consiglia quindi l'utilizzo. |
| email | string | Email del nuovo utente. Verrà usata come login. Nota: non deve essere già presente.                                                                                                                                                                                                                                               |

{% tabs %}
{% tab title="200 Utenza creata " %}

```
{
    "status": "OK",
    "data": [
        {
            "id": 01,
            "cf": "RSSMRA01A01F205Q",
            "email": "mario.rossi@timesafe.io",
            "password": "LIVE_uiymc0dpdcj712og4omk",
            "sandbox_password": "SANDBOX_5emetfiiqpziifz3h14i",
            "ethereum_wallet": "x4dn8jo6vns9u0oae9enys4mnngd3m51rrnbjtja",
            "algorand_wallet": "aptg72d68xhpo6p74z7pg2y4omyr8xgo7huvke74l59unkf8aq63iluofr",
            "creation_date": "2021-01-01 01:01:01",
            "created_by": 12345
        }
    ]
}
```

{% endtab %}

{% tab title="501 Email o cf già presenti" %}

```
// EMAIL GIA ESISTENTE
{
    "error": {
        "code": "3_asini_tristi",
        "details": "A user with this email already exists."
    }
}

// CF GIA PRESENTE
{
    "error": {
        "code": "3_asini_tristi",
        "details": "A user with this CF already exists."
    }
}
```

{% endtab %}
{% endtabs %}

<mark style="color:green;">`POST`</mark> `https://public-api.timesafe.io/user/change_password`

#### Headers

| Name  | Type   | Description                             |
| ----- | ------ | --------------------------------------- |
| token | string | Token JWT ottenuto da endpoint di login |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}


# Certificate

Endpoint per ottenere uno dei propri certificati.

## certificate

<mark style="color:blue;">`GET`</mark> `https://public-api.timesafe.io/certificate/{id}`

Questo servizio permette di ottenere la lista dei certificati caricati. Nel caso in cui ci siano dei certificati che sono nuove versioni di un precedente, viene restituita l'ultima versione disponibile.\
Se viene specificato un id, verrà mostrato solo il certificato relativo a quell'ID.\
Per la lista delle versioni di un certificato, vedere l'apposito endpoint.\
Per ottenere il file associato a un certificato, vedere l'apposito endpoint.\
\
**I parametri restituiti sono :**\
**id:** identificativo univoco del certificato all'interno di timesafe.\
**blockchain:** indica quale blockchain è usata per la notarizzazione.\
**parent\_certificate:** se il certificato attuale è una nuova versione di un certificato passato, questo dato rappresenta l'id univoco del primo certificato.\
**original\_file\_name:** nome del file originale, inviato in fase di creazione del certificato.\
**original\_file\_size:** espresso in Byte, la dimensione del file originale, inviato in fase di creazione del certificato.\
**hash\_file\_and\_cf:** opzionale, di default vale TRUE (1), e indica se l'hash salvato in blockchain è file+cf dell'utente. Se vale FALSE (0) è solo hash del file.\
**file\_hash:** hash sha1 del file, inviato in fase di creazione del certificato.\
**hash:** hash della giustaposizione  del file\_hash e dell'hash codice fiscale dell'utente creatore.\
**hash\_eth:** se il certificato è già caricato in blockchain, questo è hash della transazione. \
**block\_eth:** se il certificato è già caricato in blockchain, questo è ID del blocco.\
**status:** stato del certificato. Per dettagli vedere la sezione "stati degli oggetti".\
**creation\_date:** timestamp di creazione del certificato.\
**note:** campo di testo libero \
\
NOTE sul parametro **hash\_eth**\
\
1\) Nel caso la blockchain di riferimento sia invece Algorand, il parametro hash*eth lo hash della transazione su algorand. Ecco il link da utilizzare per verificare la transazione (in questo caso hash\_eth vale "PES2YAYRHJCMZEB3DAIF4XXLFXH7EFTPPA5NODKOHZTQRWATIKAQ" ):*\
**Algoexplorer**\
`https://algoexplorer.io/tx/PES2YAYRHJCMZEB3DAIF4XXLFXH7EFTPPA5NODKOHZTQRWATIKAQ`\
**GoalSeeker**\
`https://goalseeker.purestake.io/algorand/mainnet/transaction/PES2YAYRHJCMZEB3DAIF4XXLFXH7EFTPPA5NODKOHZTQRWATIKAQ`\
\
2\) Nel caso la blockchain di riferimento sia Ethereum il parametro **hash\_eth** è lo hash, privato del prefisso *0x*, della transazione su Ethereum.\
Ecco i link da utilizzare per verificare la transazione sui principali blockchain explorer (*in questo caso hash\_eth vale "22807ec5eeaadb6896bed8ccc1816a17349c4c7a167bdcb120a42a51e56c782b"*):\
**Etherscan**\
`https://etherscan.io/tx/0x22807ec5eeaadb6896bed8ccc1816a17349c4c7a167bdcb120a42a51e56c782b`\
**Ethexplorer**\
`https://ethplorer.io/tx/0x22807ec5eeaadb6896bed8ccc1816a17349c4c7a167bdcb120a42a51e56c782b`\
**Etherchain**\
`https://etherchain.org/tx/22807ec5eeaadb6896bed8ccc1816a17349c4c7a167bdcb120a42a51e56c782b`\
**Blockchain.com**\
`https://www.blockchain.com/it/eth/tx/0x22807ec5eeaadb6896bed8ccc1816a17349c4c7a167bdcb120a42a51e56c782b`

#### Path Parameters

| Name | Type    | Description        |
| ---- | ------- | ------------------ |
| id   | integer | ID del certificato |

#### Headers

| Name  | Type   | Description                             |
| ----- | ------ | --------------------------------------- |
| token | string | Token JWT ottenuto da endpoint di login |

{% tabs %}
{% tab title="200 Certificato trovato" %}

```
{
    "status": "OK",
    "data": {
        "items": [
            {
                "id": 93843,
                "parent_certificate": 0,
                "original_file_name": "New Test File Name.PDF ",
                "original_file_size": 12345,
                "hash_file_and_cf": "FALSE",
                "hash": "d40c7d3b55c0ea817f54daace4a50d95503b3746",
                "file_hash": "",
                "hash_eth": null,
                "block_eth": null,
                "status": "JUST_CREATED",
                "d_i": "2020-05-13 15:16:37"
            }
        ],
        "total_item_count": 1
    }
}
```

{% endtab %}
{% endtabs %}


# File

Questo endpoint restituisce il file associato a un certificato.

## certificate/get\_file

<mark style="color:blue;">`GET`</mark> `https://public-api.timesafe.io/certifcate/{ID}/get_file`

Al fine di fornire un unico endpoint per tutti i file all'utente delle API, è possibile richiedere tramite questo servizio sia i file caricati tramite API di Timesafe, sia i file per cui è stato solo specificato un URL.\
Per questi ultimi il servizio cercherà di ottenere il permesso di comportarsi da proxy, ma a seconda delle impostazioni di sicurezza del server remoto, potrebbe fallire.

#### Path Parameters

| Name | Type    | Description                                             |
| ---- | ------- | ------------------------------------------------------- |
| ID   | integer | ID del certificato di cui si desidera ottenere il file. |

#### Headers

| Name  | Type   | Description                              |
| ----- | ------ | ---------------------------------------- |
| token | string | Token JWT ottenuto da servizio di login. |

{% tabs %}
{% tab title="200 Il servizio restituisce il file come stream di dati ( Content-Type : application/.... )
" %}

```
```

{% endtab %}
{% endtabs %}


# Versions

Questo endpoint estende certificate get e restituisce le versioni di un certificato.

## certificate/versions

<mark style="color:blue;">`GET`</mark> `https://public-api.timesafe.io/certificate/{ID}/versions`

Un certificato può essere una successiva versione di un certificato "parent".\
Un "parent" può avere N "figli" che sono le versioni successive del documento, che avranno come "parent" il primo documento della serie; la cardinalità è garantita dall'ordinamento su base temporale "creation\_date".\
Questo servizio restituisce tutti i certificati relativi a un certificato padre.\
\
ESEMPIO:\
se ho un certificato ID:1, che ha 3 versioni successive ( ID: 2,3,4), ognuna di queste versioni succesive avrà come *parent* ID:1\
Se chiamo questo servizio con uno qualsiasi degli ID "figli" (2,3,4) o con ID "parent" (1)\
Otterrò la lista di certificati 1,2,3,4 ( tutte le versioni figlie + parent)

#### Path Parameters

| Name | Type    | Description                                               |
| ---- | ------- | --------------------------------------------------------- |
| id   | integer | ID del certificato di cui si voglioono tutte le versioni. |

#### Headers

| Name  | Type   | Description                             |
| ----- | ------ | --------------------------------------- |
| token | string | token JWT ottenuto da endpoint di login |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```
{
    "status": "OK",
    "data": {
        "items": [
            {
                "id": 93847,
                "parent_certificate": 93843,
                "original_file_name": "Once again Put a new.PDF ",
                "original_file_size": 1223447,
                "hash_file_and_cf": 1,
                "hash": "cea79eade58eab4a11a65b2b79705fe0746e067a",
                "file_hash": "999912345678966f8dd41e00c5a7ac36a32a9950d271",
                "hash_eth": null,
                "block_eth": null,
                "status": 0,
                "creation_date": "2020-05-14 10:47:33",
                "note": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. "
            },
            {
                "id": 93846,
                "parent_certificate": 93843,
                "original_file_name": "Put a new.PDF ",
                "original_file_size": 1223447,
                "hash_file_and_cf": 1,
                "url": "https://www.abcde.fgh/XYZXXXXXXX_v2.ABC",
                "hash": "cea79eade58eab4a11a65b2b79705fe0746e067a",
                "file_hash": "999912345678966f8dd41e00c5a7ac36a32a9950d271",
                "hash_eth": null,
                "block_eth": null,
                "status": 0,
                "creation_date": "2020-05-14 10:31:47",
                "note": ""
            },
            {
                "id": 93845,
                "parent_certificate": 93843,
                "original_file_name": "New Test File Name VERSION 2.PDF ",
                "original_file_size": 12347,
                "hash_file_and_cf": 1,
                "url": "https://www.abcde.fgh/XYZ_v2.ABC",
                "hash": "cea79eade58eab4a11a65b2b79705fe0746e067a",
                "file_hash": "999912345678966f8dd41e00c5a7ac36a32a9950d271",
                "hash_eth": null,
                "block_eth": null,
                "status": 0,
                "creation_date": "2020-05-13 15:33:36",
                "note": ""
            },
            {
                "id": 93844,
                "parent_certificate": 93843,
                "original_file_name": "New Test File Name VERSION 2.PDF ",
                "original_file_size": 12347,
                "hash_file_and_cf": 1,
                "url": "https://www.abcde.fgh/XYZ_v2.ABC",
                "hash": "cea79eade58eab4a11a65b2b79705fe0746e067a",
                "file_hash": "",
                "hash_eth": null,
                "block_eth": null,
                "status": 0,
                "creation_date": "2020-05-13 15:19:53",
                "note": ""
            },
            {
                "id": 93843,
                "parent_certificate": 0,
                "original_file_name": "New Test File Name.PDF ",
                "original_file_size": 12345,
                "hash_file_and_cf": 0,
                "url": "https://www.abcde.fgh/XYZ.ABC",
                "hash": "d40c7d3b55c0ea817f54daace4a50d95503b3746",
                "file_hash": "",
                "hash_eth": null,
                "block_eth": null,
                "status": 0,
                "creation_date": "2020-05-13 15:16:37",
                "note": ""
            }
        ],
        "total_item_count": 5
    }
}
```

{% endtab %}
{% endtabs %}


# Certificate - put

Endpoint per il caricamento di un certificato. Questo endpoint funziona in due modalità a seconda dei parametri passati: tramite hash o tramite file.

## certificate/put

<mark style="color:orange;">`PUT`</mark> `https://public-api.timesafe.io/certificate/put`

Questo servizio permette di salvare un hash in blockchain.\
Se in modalità sandbox il certificato sarà confermato entro 60 secondi, ma i dati relativi al salvataggio in blockchain saranno dei fac-simile.\
Se in modalità live, può essere necessario un tempo fino a 7 minuti per avere conferma completa di salvataggio in blockchain per Ethereum, fino a 3 minuti per Algorand. Questi tempi si riferiscono a un normale stato operativo delle blockchain, in eccezionali casi di grande congestione delle blockchain relative,  possono subire variazioni.<br>

#### Headers

| Name  | Type   | Description                             |
| ----- | ------ | --------------------------------------- |
| token | string | Token JWT ottenuto da endpoint di login |

#### Request Body

| Name                | Type    | Description                                                                                                                                                                                            |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| blockchain          | string  | Indica quale blockchain usare. Può valere "Algorand" o "Ethereum". Opzionale, di default vale "Ethereum".                                                                                              |
| hash\_file\_and\_cf | boolean | Indica se l'hash passato è da salvare in blockchain così come è (0) o se deve prima essere giustapposto all'hash del Codice Fiscale dell'utente (1). Opzionale, di default vale 1.                     |
| note                | string  | campo libero per le note (o dati custom che si vogliono persistere)                                                                                                                                    |
| fileSize            | integer | dimensione del file originale, in Byte.                                                                                                                                                                |
| fileName            | string  | Nome del file originale. Di fatto può essere un identificativo diverso dal nome del file, ma si suggerisce di usare il nome orginale e usare il campo *note* per altri scopi.                          |
| url                 | string  | se il file è presente in uno storage pubblico raggiungibile tramite URL si può inserire qui il suo indirizzo                                                                                           |
| parent              | integer | <p>se questo certificato è una nuova versione di uno già presente, specificare con questo parametro l'ID. <br>NOTA: il parent deve essere della stessa modalità (live/sandbox) dell'utenza in uso.</p> |
| hash                | string  | Hash del file ottenuto con algoritmo SHA1, **senza 0x iniziale**                                                                                                                                       |

{% tabs %}
{% tab title="200 Salvataggio avvenuto con successo" %}

```
{
    "status": "OK",
    "data": {
        "certificate_id": 93847,
        "certificate_hash": "cea79eade58eab4a11a65b2b79705fe0746e067a"
    }
}
```

{% endtab %}
{% endtabs %}

## certificate/put

<mark style="color:green;">`POST`</mark> `https://public-api.timesafe.io/certificate/put`

Questo servizio permette di salvare un hash in blockchain partendo da un file che viene a sua volta salvato in un apposito storage remoto e non pubblico.\
Se in modalità sandbox il certificato sarà confermato entro 60 secondi, ma i dati relativi al salvataggio in blockchain saranno dei fac-simile.\
Se in modalità live, può essere necessario un tempo fino a 7 minuti per avere conferma completa di salvataggio in blockchain.<br>

#### Headers

| Name  | Type   | Description                             |
| ----- | ------ | --------------------------------------- |
| token | string | Token JWT ottenuto da endpoint di login |

#### Request Body

| Name                | Type    | Description                                                                                                                                                                                            |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| blockchain          | string  | Indica quale blockchain usare. Può valere "Algorand" o "Ethereum". Opzionale, di default vale "Ethereum".                                                                                              |
| hash\_file\_and\_cf | boolean | indica se l'hash passato è da salvare in blockchain cos' com'è (0) o se deve prima essere giustapposto all'hash del Codice Fiscale (1). Opzionale, di default vale 1.                                  |
| note                | string  | Campo libero per le note (o parametri custom che si vogliono persistere)                                                                                                                               |
| parent              | integer | <p>se questo certificato è una nuova versione di uno già presente, specificare con questo parametro l'ID .<br>NOTA: il parent deve essere della stessa modalità (live/sandbox) dell'utenza in uso.</p> |
| file                | object  | Il file da salvare.                                                                                                                                                                                    |

{% tabs %}
{% tab title="200 Salvataggio avvenuto con successo" %}

```
{
    "status": "OK",
    "data": {
        "certificate_id": 93847,
        "certificate_hash": "cea79eade58eab4a11a65b2b79705fe0746e067a"
    }
}
```

{% endtab %}
{% endtabs %}


# Hash

Questo endpoint verifica se un hash esiste già.

## hash

<mark style="color:blue;">`GET`</mark> `https://public-api.timesafe.io/hash/{hash}`

Questo servizio restituisce **true** o **false** in base alla presenza o meno del hash specificato come parametro tra i certificati dell'utente. \
L'hash passato può essere quello originale del file, quello calcolato dalla giustapposizione di hash del file e hash del codice fiscale dell'utente, o quello della transazione Ethereum.\
NOTA: se si cerca un hash di un certifica  creato con una modalità (live/sandbox) differente da quella dell'utenza che si sta usando, il servizio risponderà FALSE, anche se il certificato fosse presente.

#### Path Parameters

| Name | Type   | Description                                                                                                                  |
| ---- | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| hash | string | Hash del file originale, della transazione ethereum o del risultante calcolato con il codice fiscale, **senza 0x iniziale.** |

#### Headers

| Name  | Type   | Description                               |
| ----- | ------ | ----------------------------------------- |
| token | string | Token JWT ottenuto traimte endpoint login |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```
// HASH PRESENTE
{
    "status": "OK",
    "data": {
        "exists": true,
        "id": 93843
    }
}

// HASH NON PRESENTE
{
    "status": "OK",
    "data": {
        "exists": false
    }
}
```

{% endtab %}
{% endtabs %}


# Credits

Gestione dei crediti dell'account

## Send credits

<mark style="color:green;">`POST`</mark> `https://public-api.timesafe.io/credits/send`

Questo servizio permette di inviare crediti dal proprio budget a quello di un altro utente, purché se ne abbia l'ID. Dato che il trasferimento di crediti è un'operazione on-chain, ha un costo (1 credito circa). Dunque bisogna tenere conto di questo costo come scarto tra crediti disponibili e crediti inviabili.&#x20;

#### Headers

| Name  | Type   | Description                              |
| ----- | ------ | ---------------------------------------- |
| token | string | Token JWT ottenuto da endpoint di login. |

#### Request Body

| Name    | Type    | Description                                           |
| ------- | ------- | ----------------------------------------------------- |
| user    | integer | ID dell'utente a cui si vogliono inviare crediti.     |
| credits | integer | Numero di crediti da inviare. Minimo 1, massimo 9999. |

{% tabs %}
{% tab title="200 Crediti inviati con successo" %}

```
{
    "status": "OK",
    "data": {
        "your_new_balance": 97,
        "user_new_balance": 2
    }
}
```

{% endtab %}

{% tab title="501 Problemi di invio" %}

```
// CREDITI INSUFFICIENTI
{
    "error": {
        "code": "5_topi_invalidi",
        "details": "You don't have enough credits to perform this action."
    }
}

// UTENTE NON ESISTENTE O PARTE DI ALTRA ORGANIZZAZIONE
{
    "error": {
        "code": "5_topi_invalidi",
        "details": "This user does not exists or you do not have the permission to use it."
    }
}
```

{% endtab %}
{% endtabs %}


