# Riferimento API

L'API di Namirial Sign Enterprise (v1) è un'API RESTful che consente di creare, gestire e monitorare i workflow di firma elettronica in modo programmatico. È possibile utilizzarla per integrare NSE nelle proprie applicazioni, automatizzare l'invio delle pratiche o realizzare portali di firma personalizzati.

La specifica API interattiva è disponibile di seguito: è possibile utilizzarla per esplorare gli endpoint, esaminare gli schemi di richiesta e risposta ed effettuare chiamate di prova direttamente.

## URL di base

Tutti gli endpoint API sono relativi all'URL di base della propria istanza NSE:

Ad esempio

```
https://demo-eu-ie1-api.namirialsign.com/api/
```

La maggior parte degli endpoint include `organizationId` come parametro di percorso obbligatorio (assicurarsi di averlo a disposizione ogni volta che si utilizza l'API). Si tratta dell'identificativo dell'organizzazione nella propria istanza NSE che possiede la risorsa su cui si opera.

## Principi dell'API v1

- **Semantica REST completa** — utilizza i verbi GET, POST, PUT, PATCH e DELETE secondo le convenzioni REST standard.
- **Risorse con ambito organizzazione** — tutte le risorse, ad eccezione dei dati di riferimento, hanno come ambito `/organizations/{organizationId}/`.
- **Workflow basato su stage** — i workflow di firma sono modellati come **Stage** ordinati. I destinatari appartenenti allo stesso stage firmano in parallelo; gli stage vengono elaborati in sequenza secondo l'ordine di ordinamento.
- **Separazione tra struttura e contenuto** — file, stage e destinatari sono gestiti come sotto-risorse indipendenti di una pratica o di un modello, consentendo un controllo granulare su ogni parte del workflow.
- **Artifact per i documenti completati** — una volta completata una pratica, i documenti firmati e l'audit trail sono accessibili come **Artifact**.


## Autenticazione

L'autenticazione API utilizza OAuth 2.0 Client Credentials con MyNamirial come Identity Provider.

### Configurazione

1. Creare un'**applicazione IdP** (Account di servizio).
2. Annotare l'**ID client** e la **Chiave privata cliente** assegnati all'applicazione.


> **Nota:** la creazione di un IdP in MyNamirial e il rilascio di ClientID e ClientSecret possono essere completati nell'interfaccia utente, nella sezione dedicata agli account di servizio. Per maggiori informazioni vedere: [Account di servizio](/it/products/namirialsignenterprise/namirialsignenterprise-knowledge-center/02-products-and-modules/01-nse/02-nse-settings/users)


### Ottenere un token

Utilizzare il grant Client Credentials per ottenere un token JWT Bearer.

### Token di accesso personale

Inoltre è possibile creare un token di accesso personale per utilizzare l'API. Per maggiori informazioni vedere: [Token di accesso](/it/products/namirialsignenterprise/namirialsignenterprise-knowledge-center/02-products-and-modules/01-nse/02-nse-settings/user-account-settings). Aggiungere come header "Personal-Access-Token" con il token ottenuto come valore.

### Utilizzare il token

Includere il token come Bearer token nell'header `Authorization` di ogni richiesta API:

```
Authorization: Bearer <access_token>
```

Le richieste non autenticate o con token scaduto restituiscono `401 Unauthorized`.

## Concetti fondamentali

### Pratica

Una pratica rappresenta una singola richiesta di firma. Contiene uno o più documenti (file), un workflow di firma (stage) e opzioni pratica quali nome, data di scadenza e configurazione dei promemoria.

Ciclo di vita della pratica:

| Stato | Descrizione |
|  --- | --- |
| **Draft** | Creata ma non ancora inviata. Tutta la configurazione può essere modificata. |
| **InProgress** | Inviata ai destinatari. Il workflow di firma è in corso. |
| **Completed** | Tutti i destinatari hanno completato le proprie attività. Gli artifact sono disponibili per il download. |
| **Canceled** | Annullata manualmente. Non è possibile alcuna ulteriore attività. |
| **Expired** | La data di scadenza è stata raggiunta prima del completamento. Può essere riattivata con una nuova data. |
| **Rejected** | La pratica è stata respinta da uno o più destinatari. |


### Modello

Un modello è una configurazione di pratica riutilizzabile, precaricata con documenti, stage, destinatari e posizionamento dei campi. La creazione di una pratica a partire da un modello copia l'intera configurazione in una nuova pratica in stato Draft, che può essere personalizzata prima dell'invio.

### Stage

Uno stage rappresenta un passaggio del workflow di firma. Ogni stage contiene uno o più destinatari che agiscono in parallelo. Gli stage vengono elaborati in sequenza in ordine crescente di `sortOrder`. Utilizzare `requiredRecipientCompletions` per consentire l'avanzamento di uno stage quando un numero minimo di destinatari (sul totale) ha completato la propria attività: utile negli scenari di firma di gruppo.

### Destinatario

Un destinatario è una persona assegnata a uno stage. Ogni destinatario dispone di dati di contatto (email, nome, telefono), un canale di notifica (Email, SMS, WhatsApp o None), una lingua preferita, requisiti di autenticazione opzionali (codice di accesso, SMS OTP, OAuth) e una configurazione di firma opzionale (tipo di firma ed eventuali dati precompilati obbligatori).

### File e task

Un file è un documento allegato a una pratica o a un modello. I **task** sono gli elementi interattivi assegnati ai destinatari: campi firma, campi di testo, caselle di controllo, elenchi a discesa, richieste di allegato e conferme di lettura. La maggior parte dei task è posizionata su una pagina specifica di un file, ma alcuni (come le conferme di lettura) operano a livello di file o di pagina senza una posizione fissa.

### Artifact

Quando una pratica raggiunge lo stato **Completed**, i suoi file di output diventano disponibili come Artifact. Esistono due tipi di artifact: `CompletedFile` (il documento firmato) e `AuditTrail` (il log completo degli eventi in formato PDF).

## Tipi di firma supportati

| Tipo | Descrizione |
|  --- | --- |
| `ClickToSignSignature` | Firma semplice con conferma tramite clic, senza certificato crittografico. |
| `DrawToSignSignature` | Firma tracciata a mano libera acquisita nel browser o su un dispositivo touch. |
| `TypeToSignSignature` | Firma creata digitando il nome del destinatario con un carattere selezionato. |
| `LocalCertificateSignature` | Firma con un certificato installato sul dispositivo locale del destinatario. |
| `DisposableCertificateSignature` | Firma con un certificato qualificato di breve durata (usa e getta) generato al momento della firma. |
| `BiometricSignature` | Firma acquisita tramite tavoletta biometrica (pressione e dinamica della penna). |
| `RemoteCertificateSignature` | Firma con un certificato qualificato remoto (richiede `userId` e `deviceId`). |
| `OneTimePasswordSignature` | Firma confermata tramite SMS OTP inviato al numero di telefono del destinatario. |
| `AutomaticSignature` | Firma applicata senza alcuna interazione necessaria |
| `PluginSignature` | Firma delegata a un plugin di firma personalizzato configurato sull'istanza. |


## Gestione degli errori

Tutte le risposte di errore seguono una struttura coerente:

```json
{
  "errors": [
    {
      "errorId": "string",
      "field": "string",
      "message": "string",
      "messageEn": "string",
      "additionalData": {}
    }
  ]
}
```

| Stato HTTP | Significato |
|  --- | --- |
| `200 OK` | Richiesta completata con successo. |
| `201 Created` | La risorsa è stata creata. L'ID della nuova risorsa viene restituito nel corpo della risposta. |
| `204 No Content` | Richiesta completata con successo senza corpo della risposta (aggiornamento o eliminazione). |
| `400 Bad Request` | La richiesta non è valida o è malformata. |
| `401 Unauthorized` | L'autenticazione è assente o il token è scaduto. |
| `403 Forbidden` | L'utente autenticato non ha l'autorizzazione per accedere a questa risorsa. |
| `404 Not Found` | La risorsa richiesta non esiste. |
| `422 Unprocessable Entity` | La richiesta è valida ma viola una regola di business. |
| `500 Internal Server Error` | Si è verificato un errore inatteso sul server. |


## Workflow di integrazione tipico

Una tipica integrazione per l'invio di una richiesta di firma prevede i seguenti passaggi:

1. **Creare una pratica** — `POST /organizations/{organizationId}/envelopes`
2. **Caricare un documento** — `POST /organizations/{organizationId}/envelopes/{envelopeId}/files`
3. **Aggiungere uno stage di firma** — `POST /organizations/{organizationId}/envelopes/{envelopeId}/stages`
4. **Aggiungere un destinatario allo stage** — `POST /organizations/{organizationId}/envelopes/{envelopeId}/stages/{stageId}/recipients`
5. **Posizionare i task di campo sul documento** — `PUT /organizations/{organizationId}/envelopes/{envelopeId}/files/{fileId}/tasks`
6. **Inviare la pratica** — `POST /organizations/{organizationId}/envelopes/{envelopeId}/send`
7. **Verificare la pratica** — `GET /organizations/{organizationId}/envelopes/{envelopeId}`
8. **Scaricare gli artifact** — `GET /organizations/{organizationId}/envelopes/{envelopeId}/artifacts`


Per creare a partire da un modello, sostituire i passaggi 1–5 con:

1. **Creare una pratica da un modello** — `POST /organizations/{organizationId}/templates/{templateId}/create-envelope`
2. Facoltativamente aggiornare i destinatari o i file nella bozza, quindi procedere con l'invio.


## Specifica API

La specifica API interattiva completa è disponibile nella Swagger UI della propria istanza NSE. Contattare il proprio referente Namirial per ottenere l'URL corretto per il proprio ambiente.

La SwaggerUI DEMO è disponibile a questo URL:
https://demo-eu-ie1-api.namirialsign.com/api/swagger/index.html