Questa guida illustra il workflow completo per classificare un documento tramite una Classe documentale e inviare una pratica utilizzando l'Integration API di NSE. Al termine si sarà creata una classe documentale, creata una pratica, caricato un file, classificato il file con i metadati, verificate e applicate le policy collegate e inviata la pratica.
Una Classe documentale è utile quando i documenti devono essere categorizzati (per esempio "Contratto" o "Fattura") e instradati automaticamente attraverso un workflow di firma predefinito in base alle policy collegate a tale categoria.
- Il feature flag DocumentClasses deve essere abilitato per l'organizzazione
- Un token JWT Bearer oppure un Personal Access Token valido
- Il proprio ID organizzazione (
organizationId) - Un documento pronto per il caricamento
Una Classe documentale definisce una categoria di documenti (ad esempio "Contratto") con un insieme di campi metadati tipizzati. Una volta creata, può essere riutilizzata in più pratiche e collegata alle policy.
Nella richiesta seguente viene aggiunta una classe documentale contenente un campo metadato di tipo String. Si noti che è possibile aggiungere più campi metadati a una classe documentale e che sono disponibili anche i tipi di metadato Number e Date.
POST /api/v1/organizations/{organizationId}/document-classes{
"name": "Contracts",
"description": "Document class for contracts",
"metadata": [
{
"id": 1,
"name": "Name",
"type": "StringType",
"required": true
}
]
}Risposta 201 Created
{
"id": "d4e5f6a7-1234-1234-1234-1234567890ab"
}Salvare l'id restituito: è il documentClassId, utilizzato nel Passaggio 4.
Per una configurazione semplice viene creata una pratica con un nome e una data di scadenza.
POST /api/v1/organizations/{organizationId}/envelopes{
"name": "Name",
"expiration": {
"expiresAt": "2026-05-30T18:30:00.000Z",
"mode": "absolute"
}
}Risposta 201 Created
{
"id": "a1b2c3d4-1234-1234-1234-ef1234567890"
}Salvare l'id restituito: è l'envelopeId da utilizzare in tutti i passaggi successivi.
Caricare un PDF (o un altro formato supportato) nella pratica. Questo endpoint utilizza multipart/form-data, non JSON.
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/files
Content-Type: multipart/form-data| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
file | binary | Sì | Il file del documento |
documentClassId | string (UUID) | No | Opzionale: assegna la classe documentale al momento del caricamento |
Esempio curl:
curl -X POST \
"https://demo-eu-ie1-api.namirialsign.com/api/organizations/{organizationId}/envelopes/{envelopeId}/files" \
-H "Authorization: Bearer <token>" \
-F "file=@/path/to/document.pdf"Risposta 201 Created
{
"id": "3fa85f64-1234-1234-1234-2c963f66afa6"
}Salvare l'id restituito: è il fileId, utilizzato nei passaggi successivi.
Associare al file caricato la classe documentale creata nel Passaggio 1 e fornire i valori per ciascun campo metadato.
PUT /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/files/{fileId}{
"documentClass": {
"id": "6a1231231231233f5",
"metadata": [
{
"type": "StringType",
"value": "TEST",
"id": 1
}
]
}
}Risposta 204 No Content
Dopo questo passaggio il file è classificato e i relativi metadati sono memorizzati. Il sistema può ora valutare quali policy risultano applicabili in base alla classe documentale.
Prima di applicare la policy, richiamare l'endpoint verify per controllare se la pratica e i relativi documenti classificati soddisfano già i requisiti delle policy associate. Non viene apportata alcuna modifica alla pratica.
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/verify-policies{}Risposta 200 OK
{
"compliant": false
}Richiamare apply-policies per popolare la pratica con il workflow definito dalle policy collegate. In questo modo i destinatari vengono aggiunti automaticamente secondo quanto configurato nella policy.
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/apply-policies{}Risposta 204 No Content
Dopo questa chiamata il workflow di firma della pratica è interamente configurato dalla policy. I destinatari e le fasi sono ora presenti nella pratica: è possibile verificarlo richiamando di nuovo l'endpoint verify (Passaggio 7).
Eseguire nuovamente la chiamata di verifica dopo aver applicato la policy, per confermare che la pratica sia completa e coerente.
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/verify-policies{}Risposta 200 OK
{
"compliant": true
}Se compliant è true, le condizioni configurate per le policy sono soddisfatte.
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/sendNon è richiesto alcun corpo della richiesta.
Risposta 200 OK
{
"id": "3fa85f64-1234-1234-1234-2c963f66afa6"
}I destinatari riceveranno ora le notifiche e-mail con i collegamenti alle rispettive attività di firma.
Per la documentazione di riferimento che illustra il lato interfaccia utente di questo argomento, consultare: