{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-@l10n/it/products/namirialsignenterprise/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Inviare la prima pratica","description":"Integration and usage documentation."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"inviare-la-prima-pratica","__idx":0},"children":["Inviare la prima pratica"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Questa guida illustra l'invio di una richiesta di firma tramite l'API NSE v1. Al termine si sarà creata una pratica, caricato un documento, aggiunto un firmatario, posizionato un campo Firma e inviata la pratica — tutto tramite API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisiti","__idx":1},"children":["Prerequisiti"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Un ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JWT Bearer token"]}," valido oppure un ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Personal Access Token"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["L'",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ID organizzazione"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["organizationId"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Un documento pronto per il caricamento"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"passaggio-1--creare-una-pratica","__idx":2},"children":["Passaggio 1 — Creare una pratica"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Il primo passo consiste nel creare una pratica. Si tratta del contenitore dei documenti e dei destinatari. Viene creata in stato ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["draft"]}," e resta modificabile fino all'invio."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Nella maggior parte delle integrazioni si assegna almeno un nome e si imposta una scadenza. In questo esempio si utilizza una scadenza relativa — 14 giorni dopo l'invio (espressa in secondi)."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/organizations/{organizationId}/envelopes\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"name\": \"Lease Agreement\",\n  \"expiration\": {\n    \"mode\": \"relative\",\n    \"afterSendInSeconds\": 1209600\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Risposta ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"a1b2c3d4-1234-1234-1234-ef1234567890\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Salvare l'",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," restituito: è l'",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["envelopeId"]}," da utilizzare in tutte le chiamate successive."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"passaggio-2--caricare-un-documento","__idx":3},"children":["Passaggio 2 — Caricare un documento"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Caricare il PDF che il destinatario dovrà firmare. Questo endpoint utilizza ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["multipart/form-data"]},", non JSON."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Nota: la dimensione massima del file è di 10 MB e una pratica può contenere al massimo 10 documenti."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/files\nContent-Type: multipart/form-data\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Descrizione"},"children":["Descrizione"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["file"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["binary"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Il file PDF da allegare"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Risposta ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"3fa85f64-1234-1234-1234-2c963f66afa6\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Salvare l'",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," restituito: è il ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fileId"]},", utilizzato per il posizionamento del campo Firma."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"passaggio-3--aggiungere-uno-stage-di-firma","__idx":4},"children":["Passaggio 3 — Aggiungere uno stage di firma"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Uno stage rappresenta un passaggio del workflow di firma. I destinatari appartenenti allo stesso stage firmano in parallelo; gli stage vengono eseguiti in sequenza. Per questo esempio è sufficiente un solo stage con un solo firmatario."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/stages\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"name\": \"Signers\",\n  \"requiredRecipientCompletions\": 1,\n  \"type\": \"signer\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Risposta ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"5c367bac-1234-1234-1234-08f3025e28ab\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Salvare l'",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," restituito: è lo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stageId"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"passaggio-4--aggiungere-un-destinatario","__idx":5},"children":["Passaggio 4 — Aggiungere un destinatario"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Aggiungere allo stage appena creato la persona che firmerà il documento."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/stages/{stageId}/recipients\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"givenName\": \"John\",\n  \"surname\": \"Doe\",\n  \"email\": \"john.doe@example.com\",\n  \"notificationChannels\": [\n    \"email\"\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Risposta ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"4e861e0f-1234-1234-1234-58bd9928b4a8\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Salvare l'",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," restituito: è il ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipientId"]},", utilizzato per il posizionamento del campo Firma."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"passaggio-5--posizionare-un-campo-firma","__idx":6},"children":["Passaggio 5 — Posizionare un campo Firma"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Aggiungere ora tutti i campi che devono comparire sul documento e indicare chi deve firmarlo. Questa chiamata sostituisce completamente tutti i task del file, pertanto è necessario inviare ogni volta l'elenco completo."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ogni task racchiude una definizione di ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["field"]}," insieme al ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipientId"]}," e a un ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sortOrder"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"PUT /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/files/{fileId}/tasks\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"tasks\": [\n    {\n      \"field\": {\n        \"fieldType\": \"Signature\",\n        \"id\": \"field-001\",\n        \"page\": 1,\n        \"positionX\": 100,\n        \"positionY\": 650,\n        \"width\": 200,\n        \"height\": 60,\n        \"allowedSignatureTypes\": [\n          { \"signatureType\": \"ClickToSignSignature\" },\n          { \"signatureType\": \"DrawToSignSignature\" }\n        ]\n      },\n      \"recipientId\": \"4e861e0f-1234-1234-1234-58bd9928b4a8\",\n      \"sortOrder\": 1\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Alcuni aspetti da tenere presenti:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["positionX"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["positionY"]}," sono le coordinate dell'angolo superiore sinistro del campo sulla pagina."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedSignatureTypes"]}," determina quali metodi di firma il destinatario può scegliere. Se si lascia il valore ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},", si applicano le impostazioni predefinite dell'organizzazione."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sortOrder"]}," definisce la sequenza con cui i campi vengono presentati al firmatario."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Risposta ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204 No Content"]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"passaggio-6--inviare-la-pratica","__idx":7},"children":["Passaggio 6 — Inviare la pratica"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Una volta completata la configurazione, inviare la pratica. Questa operazione porta la pratica da ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["draft"]}," a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sent"]}," e attiva l'e-mail di invito al destinatario."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/send\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Non è richiesto alcun corpo della richiesta."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Risposta ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204 No Content"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"passaggio-7--verificare-lo-stato-della-pratica","__idx":8},"children":["Passaggio 7 — Verificare lo stato della pratica"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["È possibile interrogare periodicamente questo endpoint per monitorare l'avanzamento."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Risposta ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"a1b2c3d4-1234-1234-1234-ef1234567890\",\n  \"name\": \"Lease Agreement\",\n  \"status\": \"completed\",\n  \"sentAt\": \"2026-04-20T10:05:00Z\"\n  ...\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"passaggio-8--scaricare-il-documento-firmato","__idx":9},"children":["Passaggio 8 — Scaricare il documento firmato"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Quando la pratica è ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed"]},", è possibile recuperare il file firmato e l'audit trail."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Elencare gli elementi disponibili:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/artifacts\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"artifacts\": [\n    {\n      \"id\": \"0a9e87c0-1234-1234-1234-99c8c87a9a33\",\n      \"name\": \"LeaseAgreement.pdf\",\n      \"type\": \"CompletedFile\"\n    },\n    {\n      \"id\": \"1b8f76b1-1234-1234-1234-aada9b8bab44\",\n      \"name\": \"Audit Trail.pdf\",\n      \"type\": \"AuditTrail\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Scaricare un artifact specifico:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/artifacts/{artifactId}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Restituisce il file come flusso binario (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/pdf"]},")."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prossimi-passi","__idx":10},"children":["Prossimi passi"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Questa guida ha illustrato il flusso essenziale. Il riferimento completo delle API descrive le ulteriori opzioni disponibili in ciascun passaggio, tra cui:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Pratica:"]}," promemoria automatici, date di scadenza assolute"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Stage:"]}," firma in parallelo, stage di sola approvazione (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Approver"]},"), copia per conoscenza (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CarbonCopy"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Destinatari:"]}," autenticazione SMS/OTP, codici di accesso, configurazione dei certificati QES"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Campi:"]}," campi di testo, caselle di controllo, elenchi a discesa, conferme di lettura e altro ancora"]}]}]},"headings":[{"value":"Inviare la prima pratica","id":"inviare-la-prima-pratica","depth":1},{"value":"Prerequisiti","id":"prerequisiti","depth":2},{"value":"Passaggio 1 — Creare una pratica","id":"passaggio-1--creare-una-pratica","depth":2},{"value":"Passaggio 2 — Caricare un documento","id":"passaggio-2--caricare-un-documento","depth":2},{"value":"Passaggio 3 — Aggiungere uno stage di firma","id":"passaggio-3--aggiungere-uno-stage-di-firma","depth":2},{"value":"Passaggio 4 — Aggiungere un destinatario","id":"passaggio-4--aggiungere-un-destinatario","depth":2},{"value":"Passaggio 5 — Posizionare un campo Firma","id":"passaggio-5--posizionare-un-campo-firma","depth":2},{"value":"Passaggio 6 — Inviare la pratica","id":"passaggio-6--inviare-la-pratica","depth":2},{"value":"Passaggio 7 — Verificare lo stato della pratica","id":"passaggio-7--verificare-lo-stato-della-pratica","depth":2},{"value":"Passaggio 8 — Scaricare il documento firmato","id":"passaggio-8--scaricare-il-documento-firmato","depth":2},{"value":"Prossimi passi","id":"prossimi-passi","depth":2}],"frontmatter":{"seo":{"title":"Inviare la prima pratica"}},"lastModified":"2026-10-20T12:01:05.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/it/products/namirialsignenterprise/namirialsignenterprise-knowledge-center/03-developer-documentation/01-api-reference/basic-envelope-workflow","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}