Panoramica

L'API Askme Sign v2 permette di gestire processi di firma digitale di documenti PDF attraverso chiamate REST. L'API supporta l'invio di documenti da firmare, il monitoraggio dello stato, il download e la gestione completa del ciclo di vita dei file.

Autenticazione

L'API utilizza un sistema di autenticazione basato su API Key attraverso header HTTP:

• X-SignToken: Token API per l'autenticazione (es. 8GvIU4U1xZ36VXbxOVwxgU1jBgFlPQBPWbUZ)
• X-SignUser: Username o identificativo utente (es. A462252)

X-SignToken: your-api-token
X-SignUser: your-username

Endpoint Base

https://sign.askme.it

---

Casi d'Uso

1. Avvio del Processo di Firma

Endpoint: POST /api/v2/files/send

Questo endpoint è il punto di ingresso principale per creare una nuova pratica (processo di firma) in Askme Sign. Permette di inviare uno o più documenti (PDF o altri formati supportati) per la firma elettronica, specificando i firmatari, le coordinate dove apporre la firma, la scadenza, le notifiche email e opzionalmente webhook, placeholder e parametri di workflow.

Caso d'uso: Un'azienda deve far firmare un contratto a un cliente. Il documento viene caricato (in Base64 o tramite URL), vengono specificate le coordinate della firma e il cliente riceve una notifica email per procedere con la firma. Lo stesso endpoint supporta anche invii a contatti/gruppi, più firmatari in sequenza, scadenza, invio di copia a completamento e notifiche webhook per integrazioni esterne.

---

Autenticazione e headers

La richiesta deve includere gli header di autenticazione API:

Header	Obbligatorio	Descrizione
X-SignToken	Sì	Token API (es. 8GvIU4U1xZ36VXbxOVwxgU1jBgFlPQBPWbUZ)
X-SignUser	Sì	Username o identificativo utente (es. A462252)

Esempio:

POST /api/v2/files/send HTTP/1.1
Host: sign.askme.it
Content-Type: application/json
X-SignToken: your-api-token
X-SignUser: your-username

{ ... body JSON ... }

---

Corpo della richiesta (body)

Il body è un oggetto JSON (FileInsertSimpleDTO). Tutti i campi sono opzionali eccetto gli elementi minimi per definire documenti e firmatari: almeno documents (array non vuoto) e signers (array non vuoto) oppure destinationContacts (array non vuoto), a seconda del flusso desiderato.

Struttura generale

Sezione	Campo / gruppo	Obbligatorietà	Descrizione breve
Documenti	documents	Sì	Array di documenti da firmare (Base64 o URL)
Firmatari	signers	Condizionale*	Array di firmatari (nome, email, azione, coordinate firma). *Obbligatorio se non si usano firmatari definiti in una tipologia di processo
Destinatari	destinationContacts	No	Array di utenti (email) da inserire in copia conoscenza alla pratica
Identificazione	name, notes, summary	Condizionale*	Nome pratica, note, riepilogo. *Obbligatorio name a meno che non sia specificato già nella tipologia.
Scadenza	expirationDate, expirationDateDays	No	Data scadenza o giorni alla scadenza
Notifiche	sendNotifications, sendCopyIterCompleted	No	Invio email ai firmatari / copia a completamento
Webhook	webhook, webhooks	No	URL da notificare a eventi (creazione, firma, rifiuto, scadenza)
Placeholder	placeholders	No	Campi da compilare (testo, data, firma) sul documento
Parametri	params	No	Metadati/parametri del workflow
Mail certificato	certificateMail	No	Oggetto, messaggio, PEC, CC per invio con certificato. Nota: questa funzionalità deve essere precedentemente configurata.
Opzioni	draft, urgent, privacy, protocol, visibilityMode	No	Bozza, urgente, privacy, protocollo, visibilità
Limitazioni	limitationUsernames, limitationDepartmentCodes, limitationSerialNumbers	No	Array di utenti/UO ai quali è limitata la visibilità della pratica.

---

Parametri nel dettaglio

1. documents (obbligatorio)

Array di oggetti UploadDocumentDTO. Ogni elemento rappresenta un documento da allegare alla pratica.

Attributo	Tipo	Obbligatorio	Descrizione
base64content	string	No*	Contenuto del file codificato in Base64. *Obbligatorio se non si usa externalUrl o uploadedFilename
filename	string	Consigliato	Nome del file (es. contratto.pdf)
externalUrl	string	No	URL pubblico da cui il sistema scaricherà il documento (alternativa a base64content)
order	integer	No	Ordine del documento nella pratica (0-based)
convert	boolean	Condizionale*	Se true, il sistema può convertire il file in formato standard (es. PDF). *Nota: deve essere attiva l'integrazione e una licenza valida di Aspose.
verifySignatures	boolean	No	Se true, verifica le firme eventualmente già presenti sul documento
docExternalId	string	No	ID esterno del documento
uploadedFilename	string	No*	Nome file dopo upload. *Nota: il file deve essere preventivamente caricato tramite l’apposita API dedicata; il nome file restituito in risposta può quindi essere impostato in questo parametro per utilizzare il documento nella pratica.

Nota: Per PDF, il contenuto deve essere codificato in Base64 senza inserire interruzioni di riga nel mezzo della stringa.

---

2. signers (obbligatorio per invio a persone specifiche)

Array di oggetti SimpleSignerDTO. Ogni elemento è un firmatario che prenderà parte al processo di firma.

Attributo	Tipo	Obbligatorio	Descrizione
email	string	Condizionale*	Email del firmatario. *Obbligatorio se non specificato il parametro username
firstName	string	Condizionale*	Nome del firmatario. *Obbligatorio se non specificato il parametro username
lastName	string	Condizionale*	Cognome del firmatario. *Obbligatorio se non specificato il parametro username
action	string	Sì	Azione richiesta: S Firma semplice, E FES, T FES con OTP, V FEA, Q Firma Elettronica Qualificata, P Visto, O FEQ One-Shot, J Firma IO.
username	string	Condizionale*	Username se il firmatario è un utente interno Askme Sign. *Se l'username non è valorizzato, devono essere compilati i campi email, firstName, lastName.
sendNotifications	boolean	No	Se true, invia notifiche email al firmatario.
notificationType	string	No	Tipo di notifica (email, push, ecc.)
signatureCoordinates	array	No	Coordinate e modalità di firma (vedi tabella sotto). Usato sia per firma grafica visibile (document, page, positionX, positionY, width, height, signatureType) sia per firma invisibile (elemento nell’array con signatureType idoneo.).
placeholders	array	No	Placeholder assegnati a questo firmatario. Per tipi supportati e struttura degli elementi vedi la sezione dedicata.
requirePassword	boolean	No	Richiedi password per firmare
requireOtp	boolean	No	Richiedi OTP
password	string	No	Password di accesso alla pratica per questo firmatario. Se requirePassword è true: valorizzandola l’integrazione imposta la password che il firmatario dovrà inserire per aprire il link e firmare; se omessa, il sistema ne genera una casuale e la comunica al firmatario (es. via email/SMS).
phone, phonePrefix	string	No	Telefono e prefisso (per OTP o contatto)
hostUsername	string	No	Username dell’utente che ospita la sessione di firma di persona: il firmatario opera sul dispositivo dell’host, che viene identificato da questo username.
digitalSignatureType	string	No	Formato della firma digitale. Valori ammessi: PAdES (PDF, default), CAdES, XAdES. Se omesso, si usa PAdES.
webhook	object	No	Webhook specifico per questo firmatario (stessa struttura di webhook a livello pratica)
customMessage	string	No	Testo personalizzato del corpo dell’email di invito al firmatario. Si applica solo all’invio tramite email.
customMessageObject	string	No	Testo personalizzato dell’oggetto dell’email di invito al firmatario. Si applica solo all’invio tramite email.
acrofields	array	No	Campi acroform PDF da mappare a firma o placeholder per questo firmatario. Ogni elemento: acrofieldKeyword (nome/pattern del campo nel PDF), acrofieldSignatureType (tipo firma se il campo è di firma), acrofieldMatch (modalità match: full, prefix, postfix, contains). I campi trovati nei documenti vengono usati come coordinate di firma o come placeholder testo.

Oggetto coordinate firma (signatureCoordinates)

Ogni elemento dell’array definisce un’area dove verrà apposta la firma grafica sul documento.

Attributo	Tipo	Obbligatorio	Descrizione
document	integer	Sì	Indice del documento nell’array documents (0-based). Es. 0 = primo documento
page	integer	Sì	Numero della pagina (1-based). Es. 1 = prima pagina
signatureType	string	No	Tipo firma: S Firma semplice, E FES, T Fes con OTP, V FEA, Q Firma Elettronica Qualificata, P Visto, O FEQ One-Shot, J Firma IO.
positionX	number	Sì	Posizione orizzontale del rettangolo, normalizzata tra 0 e 1 (0 = sinistra, 1 = destra). Es. 0.6 = 60% dalla sinistra
positionY	number	Sì	Posizione verticale del rettangolo, normalizzata tra 0 e 1 (0 = in alto, 1 = in basso). Es. 0.4 = 40% dall’alto
width	number	No	Larghezza del rettangolo, normalizzata 0–1. Es. 0.2 = 20% della larghezza pagina
height	number	No	Altezza del rettangolo, normalizzata 0–1. Es. 0.08 = 8% dell’altezza pagina
anchorKeyword	string	No	Parola chiave nel PDF per posizionare automaticamente la firma (alternativa a positionX/Y)
invisible	boolean	No	Firma invisibile
textContent	string	No	Testo mostrato nell’area di firma (firma grafica o digitale). Via API si imposta in ogni elemento di signatureCoordinates. Sono supportati i placeholder: {{signedByText}} (nome firmatario), {{signDate}} (data/ora firma), {{checkedByText}}, {{approvedByText}}, {{digitalSignedByText}} (testo azione). Es.: "Firmato digitalmente da {{signedByText}}\n{{signDate}}".
reason	string	No	Motivo della firma: testo inserito nei metadati PDF della firma (campo “Reason”, es. “Approvazione documento”, “Firma per accettazione”). Usato soprattutto in firma digitale.
location	string	No	Luogo della firma: testo inserito nei metadati PDF (campo “Location”, es. città o sede). Usato soprattutto in firma digitale.
rotation	integer	No	Rotazione dell’immagine di firma in gradi (es. 0, 90, 180, 270). Si applica al specimen prima del posizionamento nel riquadro. Default: 0.
scale	number	No	Fattore di scala dell’immagine/contenuto della firma nel riquadro (es. 1 = 100%, 0.5 = 50%). Default: 1.
offsetLeft, offsetTop	integer	No	Offset in pixel rispetto alla posizione di riferimento. Usati quando la coordinata è posizionata tramite ancora (anchorKeyword): si sommano alle coordinate (in pixel) del punto in cui è stato trovato il testo/ancora nel PDF. Consentono di spostare il riquadro rispetto all’ancora.
offsetX, offsetY	number	No	Offset normalizzati (stessa convenzione di positionX/positionY, valori 0–1 rispetto a larghezza/altezza pagina). Aggiunti alla posizione già calcolata (coordinate fisse o da ancora + offsetLeft/offsetTop) per un aggiustamento fine.
groupId	integer	No	ID di gruppo: stesso valore su più coordinate le associa allo stesso gruppo (es. per campi condizionali o per gestione congiunta di più riquadri). Valore numerico libero (es. 1, 2, 3).

Sistema di coordinate normalizzate (0–1): Per ottenere i pixel assoluti su una pagina PDF, moltiplicare positionX e width per la larghezza della pagina in punti, e positionY e height per l’altezza. Esempio: pagina A4 595×842 pt, rettangolo al 60% in orizzontale e 40% in verticale, larghezza 20%, altezza 8% → positionX: 0.6, positionY: 0.4, width: 0.2, height: 0.08.

---

3. destinationContacts (opzionale)

Consente di associare alla pratica uno o più contatti destinatari. Tali contatti ricevono notifiche via email nei seguenti casi:

Evento	Descrizione
Pratica completata	Tutte le firme sono state apposte; i destinatari ricevono un’email di completamento (con eventuali allegati secondo la configurazione).
Pratica rifiutata	Un firmatario ha rifiutato; i destinatari ricevono un’email di notifica del rifiuto.

I destinatari non ricevono invece notifiche in fase di creazione della pratica né sugli inviti ai firmatari (questi restano riservati ai singoli firmatari indicati in signers).

Attributo	Tipo	Obbligatorio	Descrizione
email	string	Sì	Email del contatto destinatario.

---

4. Nome, note, riepilogo

Parametro	Tipo	Descrizione
name	string	Nome identificativo della pratica
notes	string	Note aggiuntie da evidenziare nell'iter di firma (es. “Contratto Q4 2024”)
summary	string	Sommario da inserire nel dettaglio pratica

---

5. Scadenza

Parametro	Tipo	Descrizione
expirationDate	string	Data e ora di scadenza in formato ISO 8601 (es. 2024-12-31T23:59:59+01:00)
expirationDateDays	integer	Alternativa: numero di giorni dalla creazione dopo i quali la pratica scade

---

6. Notifiche e invio copia

Parametro	Tipo	Default	Descrizione
sendNotifications	boolean	true	Se true, il sistema invia email ai firmatari con il link per firmare (invito a firma). Se false, non vengono inviate queste email.
sendCopyIterCompleted	boolean	true	Se true, al completamento della pratica (tutte le firme apposte) viene inviata l’email di completamento (con eventuali allegati) ai destinatari configurati: mittente/sottoscrittore, firmatari, contatti in destinationContacts, ecc. Se false, non viene inviata questa comunicazione di completamento. L’effetto può dipendere dalla configurazione tenant (es. sendCopyIterCompletedEnabled) e dal tipo di workflow.

---

7. Webhook

Permettono al vostro sistema di ricevere notifiche HTTP quando cambiano gli stati della pratica (creata, firmata, rifiutata, scaduta, ecc.). Ogni evento viene inviato al vostro endpoint con metodo POST, corpo JSON e eventuale autenticazione in base a authMode.

Parametro	Tipo	Descrizione
webhook	object	Singolo webhook (vedi sotto). Usato per una sola URL di callback.
webhooks	array	Più webhook (stessa struttura). Consentono di notificare più endpoint per lo stesso evento.

Oggetto WebhookDTO

Attributo	Tipo	Obbligatorio	Descrizione
url	string	Sì	URL da chiamare. La richiesta è sempre POST con corpo JSON. Nell’URL sono supportati i placeholder: {{idFile}}, {{tenantCode}}, {{signerEmail}}, {{status}}, {{action}}.
authMode	string	No	Modalità di autenticazione. Valori: basic (Basic Auth), header (token in header, nome/valore da configurazione), oauth2 (Bearer token da configurazione). Se omesso, viene usato il default del tenant.
authConfig	string	No	Chiave di configurazione per le credenziali (per tenant). Usata con authMode header o oauth2 per recuperare header/token dalla configurazione; con basic si possono usare direttamente username e password.
username	string	No	Username per Basic Auth (usato se authMode = basic).
password	string	No	Password per Basic Auth (usato se authMode = basic).

Corpo della richiesta (POST)
Il sistema invia al vostro endpoint un JSON con una struttura di questo tipo (per riferimento):

{
  "idFile": 1234,
  "tenantCode": "TENANT01",
  "name": "Contratto cliente",
  "status": "L",
  "action": "S",
  "signerEmail": "[email protected]",
  "notes": "Eventuali note dell'azione",
  "protocol": "HTTPS",
  "externalId": "ID_ESTERNO_OPZIONALE",
  "time": "2024-10-23T10:09:00.000+02:00"
}

8. Placeholder e parametri

placeholders (opzionale)
Array di oggetti DocumentsPlaceholderDTO che definiscono campi da compilare sul documento (testo libero, data, firma grafica, checkbox, allegato, ecc.) in posizioni fisse o tramite ancora.

Posizione nell’API di invio:

• In FileInsertSimpleDTO: placeholders a livello di pratica (comuni a tutti i documenti/firmatari) e/o per ogni firmatario in signers[].placeholders.

Campi principali (per il dettaglio completo si rimanda allo Swagger / DocumentsPlaceholderDTO):

Campo	Tipo	Descrizione
type	char/string	Tipo placeholder: T testo libero, S firma grafica, D data firma, O data/ora, E data di nascita, I checkbox, Z allegato, F nome completo, 1/2 nome/cognome, X email, K telefono, U combo, R radio.
document	int	Indice del documento (0-based).
page	integer	Numero pagina.
positionX, positionY, width, height	number	Posizione e dimensioni (normalizzate 0–1).
code	string	Codice identificativo del placeholder.
required	boolean	Se obbligatorio.
idSigner	long	ID del firmatario a cui è assegnato (se per signer).
anchorKeyword	string	Testo/ancora nel PDF per il posizionamento.
defaultValue	string	Valore predefinito.
regex / regexErrorMessage	string	Validazione e messaggio di errore.

---

params (opzionale)
Array di WorkflowParameterSimpleDTO che definiscono parametri/metadati del workflow (chiave/valore, tipo, obbligatorietà). Servono a passare dati contestuali alla pratica (es. numero contratto, data, selezione) senza posizionarli sul PDF.

Posizione nell’API di invio: in FileInsertSimpleDTO come params a livello di pratica.

Campi principali (ereditati da WorkflowParameterInfoDTO + WorkflowParameterSimpleDTO; dettaglio completo in Swagger):

Campo	Tipo	Descrizione
code	string	Codice univoco del parametro (chiave).
value	string	Valore (max 250 byte).
label	string	Etichetta visualizzata.
type	string	Tipo: string, number, date, select.
required	boolean	Se obbligatorio.
visible	boolean	Se visibile in UI.
lookupValues	string	Opzioni per tipo select (JSON array di { value, label }).
format	string	Formato (es. per date).
maxLength	integer	Lunghezza massima.

---

9. Altre opzioni

Parametro	Tipo	Descrizione
draft	boolean	Se true, la pratica viene salvata come bozza: non si avvia il flusso di firma e non vengono inviate notifiche. Sarà possibile riprendere la modifica della pratica da interfaccia.
urgent	boolean	Segna la pratica come urgente. Default: false.
privacy	string	Livello di privacy della pratica. Valori ammessi: P (pubblico), A (aziendale, default), C (confidenziale), S (strettamente confidenziale).
idFlow	long	ID del flusso (se la pratica deve essere associata a un flusso esistente).
idWorkflowType	long	ID della tipologia di processo. Alternativa a workflowTypeCode.
workflowTypeCode	string	Codice della tipologia di processo. Se valorizzato e idWorkflowType è null, viene risolto l’ID corrispondente.
idModule	long	ID modulo (se la pratica usa un modulo).
idDocumentFormat	long	ID del formato documento (classificazione/tipologia documento).
documentFormat	string	Nome del formato (es. "PDF", "Contratto"). Usato per cercare il formato per nome/tenant se idDocumentFormat non è valorizzato.
limitationUsernames	array	Username degli utenti ai quali è limitata la visibilità della pratica.
limitationDepartmentCodes	array	Codici reparto per limitare la visibilità della pratica ai soli utenti di quelle unità organizzative.
limitationSerialNumbers	array	Matricole degli utenti ai quali è limitata la visibilità della pratica. Richiede che l'ambiente sia attivato per l'utilizzo delle matricole invece degli username
mpi	boolean	Modalità MPI (Massiva/Integrata): se true, la pratica è gestita in contesto MPI.
attachedReport	boolean	Se true, allega il audit log (es. in download o in email di completamento).
afterCompletedRedirect	string	URL di redirect a cui reindirigere il firmatario dopo il completamento della pratica.
afterDeniedRedirect	string	URL di redirect a cui reindirigere il firmatario dopo il rifiuto della pratica.
additionalDocuments	array	Documenti aggiuntivi (allegati). Stessa struttura di documents (UploadDocumentDTO); permette di aggiungere degli allegati alla pratica.
certificateMail	object	Configurazione invio mail con certificato (PEC). Oggetto CertificateMailDTO: pecSender (ContactDTO), pecRecipients (lista email), subject, message, ccUsers, ccUsersBackup, documentOrderNumber, filenamesToSend. Questa modalità deve essere abilitata a livello di installazione
templateParams	object	Parametri template (mappa chiave/valore) per la pratica. Sostituiti nelle email/notifiche e nei template documento. Anche per firmatario in signers[].templateParams.
firstAnchorDelimiter	string	Delimitatore di inizio per il posizionamento automatico di firma/placeholder tramite ancora nel testo del PDF (coppia con secondAnchorDelimiter).
secondAnchorDelimiter	string	Delimitatore di fine per il posizionamento automatico tramite ancora nel PDF.

---

Risposta (successo)

• Codice HTTP: 200 OK.
• Body: oggetto SigningProcessInfoDTO.

Campo	Tipo	Descrizione
idFile	number (long)	ID della pratica creata.
signers	array	Elenco dei firmatari che prenderanno parte all'iter di firma appena creato
canAutoAdvance	boolean	Se true, il workflow può avanzare automaticamente allo step successivo quando tutte le azioni dello step corrente sono state eseguite (es. firma in parallelo completata). Se false, è richiesto un avanzamento esplicito.

Campi principali di ogni elemento di signers (SimpleSignerOutputDTO):

Campo	Tipo	Descrizione
signingUrl	string	Link per firmare (per firmatario esterno o con magic link). Valorizzato solo per i firmatari che devono ancora firmare.
email	string	Email del firmatario.
firstName, lastName	string	Nome e cognome del firmatario.
action	string	Tipo di azione (un carattere: es. E = Firma Elettronica Semplice, P = Visto).
password	string	Eventuale password di accesso alla pratica (se richiesta e generata/inviata dal sistema).

Esempio di risposta:

{
  "idFile": 12345,
  "canAutoAdvance": false,
  "signers": [
    {
      "email": "[email protected]",
      "firstName": "Mario",
      "lastName": "Rossi",
      "action": "S",
      "signingUrl": "https://sign.askme.it/external-sign?token=...",
      "external": true
    }
  ]
}

Codici di errore

Codice	Significato
400	Bad Request – body malformato o validazione fallita (es. documenti mancanti, coordinate non valide, parametri obbligatori mancanti, codici duplicati nei params).
401	Unauthorized – token, Basic Auth o API Key mancanti o non validi.
403	Forbidden – utente non autorizzato all'azione (es. DOC_SUBMIT) o tenant non abilitato.
404	Not Found – risorsa non trovata (es. tipo workflow da workflowTypeCode/idWorkflowType, modulo, formato documento).
500	Internal Server Error – errore lato server; riprovare o contattare il supporto.

In caso di errore il body può contenere un oggetto con:

Campo	Tipo	Descrizione
status	integer	Codice HTTP.
details	string	Messaggio di errore (testo leggibile).
messageKey	string	Chiave messaggio per i18n.
code	string	Codice errore.
reference	string	Identificativo univoco della richiesta (per supporto).
timestamp	string	Data/ora dell'errore.
type	string	Tipo errore (es. common).

---

Esempi di richiesta

Esempio 1 – Minimo (un documento, un firmatario, coordinate firma)

{
  "documents": [
    {
      "filename": "contratto.pdf",
      "base64content": "JVBERi0xLjMNCiXi48/T..."
    }
  ],
  "name": "Contratto Cliente Rossi",
  "notes": "Contratto di vendita Q4 2024",
  "sendNotifications": true,
  "signers": [
    {
      "firstName": "Mario",
      "lastName": "Rossi",
      "email": "[email protected]",
      "action": "S",
      "signatureCoordinates": [
        {
          "document": 0,
          "page": 1,
          "signatureType": "S",
          "positionX": 0.6,
          "positionY": 0.4,
          "width": 0.2,
          "height": 0.08
        }
      ]
    }
  ]
}

Esempio 2 – Con scadenza e webhook

{
  "documents": [
    {
      "filename": "documento.pdf",
      "base64content": "JVBERi0xLjMNCi..."
    }
  ],
  "name": "Pratica con scadenza e webhook",
  "sendNotifications": true,
  "expirationDateDays": 30,
  "webhook": {
    "url": "https://your-server.com/webhook/askmesign",
    "authMode": "basic",
    "username": "webhook_user",
    "password": "webhook_secret"
  },
  "signers": [
    {
      "email": "[email protected]",
      "firstName": "Luigi",
      "lastName": "Verdi",
      "action": "S",
      "signatureCoordinates": [
        {
          "document": 0,
          "page": 1,
          "signatureType": "S",
          "positionX": 0.5,
          "positionY": 0.8,
          "width": 0.25,
          "height": 0.1
        }
      ]
    }
  ]
}

Esempio 3 – Documento da URL esterno

{
  "documents": [
    {
      "filename": "documento-da-url.pdf",
      "externalUrl": "https://your-cdn.example.com/files/contratto.pdf"
    }
  ],
  "name": "Pratica da URL",
  "sendNotifications": true,
  "signers": [
    {
      "email": "[email protected]",
      "action": "S",
      "signatureCoordinates": [
        {
          "document": 0,
          "page": 1,
          "signatureType": "S",
          "positionX": 0.6,
          "positionY": 0.4,
          "width": 0.2,
          "height": 0.08
        }
      ]
    }
  ]
}

Esempio 4 – Due documenti, due firmatari in sequenza

{
  "documents": [
    { "filename": "allegato1.pdf", "base64content": "..." },
    { "filename": "allegato2.pdf", "base64content": "...", "order": 1 }
  ],
  "name": "Doppia firma",
  "sendNotifications": true,
  "signers": [
    {
      "email": "[email protected]",
      "firstName": "Primo",
      "lastName": "Firmatario",
      "action": "S",
      "signatureCoordinates": [
        { "document": 0, "page": 1, "signatureType": "S", "positionX": 0.6, "positionY": 0.4, "width": 0.2, "height": 0.08 }
      ]
    },
    {
      "email": "[email protected]",
      "firstName": "Secondo",
      "lastName": "Firmatario",
      "action": "S",
      "signatureCoordinates": [
        { "document": 0, "page": 1, "signatureType": "S", "positionX": 0.6, "positionY": 0.5, "width": 0.2, "height": 0.08 },
        { "document": 1, "page": 1, "signatureType": "S", "positionX": 0.6, "positionY": 0.4, "width": 0.2, "height": 0.08 }
      ]
    }
  ]
}

---

2. Invio Email con Copia del File

Endpoint: POST /api/v2/files/send-copy

Questo endpoint permette di inviare via email una copia dei documenti di una pratica a uno o più destinatari. Il sistema allega automaticamente i file della pratica all'email, utilizzando un template di notifica dedicato. È possibile personalizzare oggetto e corpo del messaggio, e opzionalmente inviare una copia in CC al mittente (l'utente autenticato).

Caso d'uso: Dopo che un contratto è stato firmato da tutti i firmatari, l'azienda vuole inviare una copia del documento firmato al cliente e al responsabile amministrativo, con un messaggio personalizzato (es. "In allegato il contratto firmato"). L'operatore può anche ricevere una copia in CC per conferma dell'invio.

---

Autenticazione e headers

La richiesta deve includere gli header di autenticazione API:

Header	Obbligatorio	Descrizione
X-SignToken	Sì	Token API (es. 8GvIU4U1xZ36VXbxOVwxgU1jBgFlPQBPWbUZ)
X-SignUser	Sì	Username o identificativo utente (es. A462252)

Esempio:

POST /api/v2/files/send-copy HTTP/1.1
Host: sign.askme.it
Content-Type: application/json
X-SignToken: your-api-token
X-SignUser: your-username

{ ... body JSON ... }

---

Corpo della richiesta (body)

Il body è un oggetto JSON (SendFileCopyDTO).

Attributo	Tipo	Obbligatorio	Descrizione
idFile	number (long)	Sì	ID della pratica di cui inviare la copia dei documenti.
emails	array[string]	Sì	Array di indirizzi email dei destinatari. Deve contenere almeno un elemento.
subject	string	No	Oggetto dell'email. Se omesso, viene usato l'oggetto predefinito dal template.
message	string	No	Corpo del messaggio email personalizzato.
sendCopySender	boolean	No	Se true, invia una copia in CC anche all'utente autenticato che effettua la richiesta. Default: false.

---

Risposta (successo)

• Codice HTTP: 200 OK
• Body: true (boolean) — indica che l'invio è avvenuto con successo.

true

Codici di errore

Codice	Significato
400	Bad Request – idFile mancante oppure emails vuoto o non specificato.
401	Unauthorized – token o API Key mancanti o non validi.
403	Forbidden – utente non autenticato o non autorizzato ad accedere alla pratica specificata.
500	Internal Server Error – errore lato server (es. invio email fallito); riprovare o contattare il supporto.

---

Esempi di richiesta

Esempio 1 – Invio a un destinatario

{
  "idFile": 12345,
  "emails": [
    "[email protected]"
  ],
  "subject": "Copia del contratto firmato",
  "message": "In allegato trova il contratto firmato da tutti i firmatari.",
  "sendCopySender": false
}

Esempio 2 – Invio a più destinatari con copia al mittente

{
  "idFile": 12345,
  "emails": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ],
  "subject": "Documentazione firmata - Pratica #12345",
  "message": "Si trasmette in allegato la documentazione firmata per gli archivi.",
  "sendCopySender": true
}

---

3. Verifica Stato Account

Endpoint: GET /api/v2/account

Questo endpoint restituisce le informazioni complete sull'utente autenticato e sul suo account in Askme Sign. Include dati anagrafici, permessi, tenant disponibili, configurazioni di firma e preferenze di notifica. È utile sia per verificare la validità delle credenziali API sia per ottenere il contesto dell'utente corrente (permessi, tenant, configurazioni).

Caso d'uso: Un'applicazione esterna vuole verificare periodicamente che le credenziali API siano valide, ottenere i permessi dell'utente per abilitare/disabilitare funzionalità nella propria interfaccia, oppure recuperare l'elenco dei tenant disponibili per un utente multi-tenant.

---

Autenticazione e headers

La richiesta deve includere gli header di autenticazione API:

Header	Obbligatorio	Descrizione
X-SignToken	Sì	Token API (es. 8GvIU4U1xZ36VXbxOVwxgU1jBgFlPQBPWbUZ)
X-SignUser	Sì	Username o identificativo utente (es. A462252)

Esempio:

GET /api/v2/account HTTP/1.1
Host: sign.askme.it
X-SignToken: your-api-token
X-SignUser: your-username

---

Parametri della richiesta

Nessun parametro aggiuntivo: l'utente viene identificato automaticamente dagli header di autenticazione.

---

Risposta (successo)

• Codice HTTP: 200 OK
• Body: oggetto UserAccountDTO.

Campi principali

Campo	Tipo	Descrizione
idUser	number (long)	ID univoco dell'utente.
username	string	Username dell'utente.
firstName	string	Nome.
lastName	string	Cognome.
email	string	Email dell'utente.
phone	string	Numero di telefono.
phonePrefix	string	Prefisso telefonico.
fiscalCode	string	Codice fiscale.
external	boolean	Se true, l'utente è un firmatario esterno.
enabled	boolean	Se true, l'utente è attivo.
langKey	string	Lingua preferita (es. it, en).
status	char	Stato utente: A (presente), O (assente).
lastOnline	string (date)	Data/ora dell'ultimo accesso.
permissions	array[string]	Elenco dei permessi/autorità dell'utente (es. AS_DOC_SUB, AS_DOC_LST).
currentTenant	object	Informazioni sul tenant corrente (vedi sotto).
availableTenants	array	Elenco dei tenant disponibili per l'utente.
ldapUser	boolean	Se true, l'utente è di tipo LDAP.
twoFactorAuthEnabled	boolean	Se true, l'autenticazione a due fattori è abilitata.
feqRemoteEnabled	boolean	Se true, la firma elettronica qualificata remota è abilitata.
feqLocalEnabled	boolean	Se true, la firma elettronica qualificata locale è abilitata.
notificationsEnabled	boolean	Se true, le notifiche sono abilitate per l'utente.

Oggetto currentTenant

Campo	Tipo	Descrizione
idTenant	number (long)	ID del tenant.
code	string	Codice tenant.
name	string	Nome del tenant.

Esempio di risposta:

{
  "idUser": 1001,
  "username": "A462252",
  "firstName": "Mario",
  "lastName": "Rossi",
  "email": "[email protected]",
  "phone": "3331234567",
  "enabled": true,
  "external": false,
  "langKey": "it",
  "status": "A",
  "permissions": [
    "AS_DOC_SUB",
    "AS_DOC_LST",
    "AS_DOC_DOW",
    "AS_DOC_DEL"
  ],
  "currentTenant": {
    "idTenant": 1,
    "code": "TENANT01",
    "name": "Azienda SpA"
  },
  "availableTenants": [
    {
      "idTenant": 1,
      "code": "TENANT01",
      "name": "Azienda SpA"
    }
  ],
  "notificationsEnabled": true,
  "twoFactorAuthEnabled": false,
  "feqRemoteEnabled": true,
  "feqLocalEnabled": false,
  "ldapUser": false
}

Codici di errore

Codice	Significato
401	Unauthorized – token o API Key mancanti o non validi, oppure utente non trovato.
500	Internal Server Error – errore lato server; riprovare o contattare il supporto.

---

4. Lista File nell'Archivio

Endpoint: GET /api/v2/files/

Questo endpoint restituisce l'elenco paginato delle pratiche (file) visibili all'utente autenticato, con supporto per numerosi filtri (per stato, data, firmatario, urgenza, ecc.) e ordinamento. Utilizza il sistema di paginazione standard di Spring Data: i parametri page, size e sort vengono passati come query string.

Caso d'uso: Un'applicazione di gestione documentale vuole mostrare all'utente tutti i documenti inviati per la firma, con possibilità di filtrarli per stato, data di creazione, firmatario o nome pratica. Un sistema esterno può anche usare questo endpoint per monitorare periodicamente lo stato delle pratiche e sincronizzare il proprio database.

---

Autenticazione e headers

Header	Obbligatorio	Descrizione
X-SignToken	Sì	Token API (es. 8GvIU4U1xZ36VXbxOVwxgU1jBgFlPQBPWbUZ)
X-SignUser	Sì	Username o identificativo utente (es. A462252)

Esempio:

GET /api/v2/files/?page=0&size=20&sort=idFile,desc HTTP/1.1
Host: sign.askme.it
X-SignToken: your-api-token
X-SignUser: your-username

---

Parametri query (paginazione e ordinamento)

Parametro	Tipo	Default	Descrizione
page	integer	0	Numero della pagina (0-based).
size	integer	100	Numero di elementi per pagina.
sort	string	idFile,desc	Campo e direzione di ordinamento (es. tsIns,desc, name,asc). È possibile specificare più campi separandoli con &sort=.

Parametri query (filtri)

Tutti i filtri sono opzionali e vengono passati come query string.

Parametro	Tipo	Descrizione
idFile	number (long)	Filtra per ID pratica specifico.
query	string	Ricerca testuale su nome pratica e altri campi.
status	array[string]	Filtra per stato/i della pratica (es. status=L&status=R). Valori: L In lavorazione, F Firmato, R Rifiutato, E Scaduto, S Sospeso, V Annullato, U Caricato, A Completato, C Cestinato.
tsInsFrom	string (date)	Data inizio creazione (formato yyyy-MM-dd).
tsInsTo	string (date)	Data fine creazione (formato yyyy-MM-dd).
tsUpdFrom	string (date)	Data inizio ultimo aggiornamento.
tsUpdTo	string (date)	Data fine ultimo aggiornamento.
expirationDateMin	string (date)	Data scadenza minima.
expirationDateMax	string (date)	Data scadenza massima.
idUser	number (long)	Filtra per ID utente creatore.
userEmail	string	Filtra per email dell'utente creatore.
idSigner	array[long]	Filtra per ID firmatario/i.
urgent	boolean	Se true, mostra solo le pratiche urgenti.
digitalSigned	boolean	Se true, mostra solo pratiche con firma digitale.
protocol	string	Filtra per numero di protocollo.
flow	string	Filtra per flusso.
idFlow	number (long)	Filtra per ID flusso.
externalId	string	Filtra per ID sistema esterno.
metadataKey	string	Filtra per chiave metadato (parametro workflow).
metadataValue	string	Filtra per valore metadato (usare insieme a metadataKey).

---

Risposta (successo)

• Codice HTTP: 200 OK
• Body: oggetto Page contenente l'elenco delle pratiche e i metadati di paginazione.

Struttura della risposta paginata

Campo	Tipo	Descrizione
content	array	Array di oggetti pratica (vedi sotto).
totalElements	number	Numero totale di elementi corrispondenti ai filtri.
totalPages	number	Numero totale di pagine.
size	number	Dimensione della pagina richiesta.
number	number	Numero della pagina corrente (0-based).
numberOfElements	number	Numero di elementi nella pagina corrente.
first	boolean	true se è la prima pagina.
last	boolean	true se è l'ultima pagina.

Campi principali di ogni elemento in content

Campo	Tipo	Descrizione
idFile	number (long)	ID univoco della pratica.
name	string	Nome della pratica.
status	char	Stato della pratica (vedi sezione Codici Stato).
numDocuments	integer	Numero di documenti nella pratica.
expirationDate	string (date)	Data di scadenza.
protocol	string	Numero di protocollo (se presente).
urgent	boolean	Se true, la pratica è contrassegnata come urgente.
privacy	string	Livello di privacy (P, A, C, S).
digitalSigned	boolean	Se true, contiene firme digitali.
sealed	boolean	Se true, la pratica è sigillata.
tsIns	string (date)	Data/ora di creazione.
tsUpd	string (date)	Data/ora ultimo aggiornamento.
user	object	Informazioni sull'utente creatore (idUser, firstName, lastName, email).
signers	array	Elenco dei firmatari con stato dell'azione.
workflowType	object	Informazioni sulla tipologia di processo (se presente).
tenant	object	Informazioni sul tenant (in ambienti multi-tenant).

Esempio di risposta:

{
  "content": [
    {
      "idFile": 12345,
      "name": "Contratto Cliente Rossi",
      "status": "L",
      "numDocuments": 1,
      "expirationDate": "2025-06-30T23:59:59+02:00",
      "urgent": false,
      "privacy": "A",
      "digitalSigned": false,
      "tsIns": "2025-01-15T10:30:00+01:00",
      "tsUpd": "2025-01-15T10:30:00+01:00",
      "user": {
        "idUser": 1001,
        "firstName": "Mario",
        "lastName": "Rossi",
        "email": "[email protected]"
      },
      "signers": [
        {
          "email": "[email protected]",
          "firstName": "Luigi",
          "lastName": "Verdi",
          "action": "S"
        }
      ]
    }
  ],
  "totalElements": 150,
  "totalPages": 8,
  "size": 20,
  "number": 0,
  "numberOfElements": 20,
  "first": true,
  "last": false
}

Codici di errore

Codice	Significato
401	Unauthorized – token o API Key mancanti o non validi.
403	Forbidden – utente non autorizzato alla visualizzazione dell'archivio.
500	Internal Server Error – errore lato server; riprovare o contattare il supporto.

---

5. Download File Firmato

Endpoint: GET /api/v2/files/download/{idFile}

Questo endpoint consente di scaricare i documenti di una pratica. Se la pratica contiene un solo documento, il download restituisce il file direttamente (es. PDF). Se la pratica contiene più documenti, il sistema restituisce un archivio ZIP contenente tutti i file. In base alla configurazione del tenant, il download può includere anche il report di audit. Per i documenti con firma digitale CAdES, il file restituito avrà estensione .p7m.

Caso d'uso: Dopo che tutti i firmatari hanno completato il processo di firma (stato F), l'applicazione scarica automaticamente il documento firmato per archiviarlo nel sistema documentale aziendale. Il download può essere integrato in un workflow automatico attivato da un webhook di completamento.

---

Autenticazione e headers

Header	Obbligatorio	Descrizione
X-SignToken	Sì	Token API (es. 8GvIU4U1xZ36VXbxOVwxgU1jBgFlPQBPWbUZ)
X-SignUser	Sì	Username o identificativo utente (es. A462252)

Esempio:

GET /api/v2/files/download/12345 HTTP/1.1
Host: sign.askme.it
X-SignToken: your-api-token
X-SignUser: your-username

---

Parametri

Parametro	Posizione	Tipo	Obbligatorio	Descrizione
idFile	path	number (long)	Sì	ID della pratica di cui scaricare i documenti.

---

Risposta (successo)

• Codice HTTP: 200 OK
• Body: contenuto binario del file (stream).
• Content-Type: application/pdf (documento singolo), application/zip (più documenti) o altro in base al tipo di file.

Headers della risposta

Header	Descrizione
Content-Type	MIME type del file (es. application/pdf, application/zip).
Content-Length	Dimensione del file in byte.
Content-Disposition	attachment; filename="nomefile.pdf" — indica il nome del file per il download.

Note:

• Se il file è in formato CAdES (firma digitale P7M), il filename avrà estensione .p7m aggiunta automaticamente.
• Se la pratica contiene più documenti, il Content-Type sarà application/zip e il file conterrà tutti i documenti in un archivio ZIP.
• Se la configurazione prevede il download sempre in formato ZIP (documentsDownloadAlwaysZip), anche i file singoli verranno restituiti come archivio ZIP.

Codici di errore

Codice	Significato
401	Unauthorized – token o API Key mancanti o non validi.
403	Forbidden – utente non autorizzato al download (DOC_DOWNLOAD) o non ha accesso alla pratica.
404	Not Found – pratica non trovata o dati del documento eliminati.
500	Internal Server Error – errore lato server; riprovare o contattare il supporto.

---

6. Eliminazione File

Endpoint: DELETE /api/v2/files/{idFile}

Questo endpoint esegue l'eliminazione logica di una pratica dal sistema. L'operazione non rimuove fisicamente il record dal database, ma disabilita la pratica e cancella i dati dei documenti associati (contenuti, storico, annotazioni). I dati eliminati non sono recuperabili. L'operazione registra anche un evento di rimozione e, se configurati, esegue eventuali plugin/hook post-eliminazione.

Caso d'uso: Un documento inviato per errore o non più necessario deve essere rimosso dal sistema per motivi di privacy o conformità GDPR. Un sistema esterno può integrare la cancellazione nel proprio workflow di gestione del ciclo di vita dei documenti.

---

Autenticazione e headers

Header	Obbligatorio	Descrizione
X-SignToken	Sì	Token API (es. 8GvIU4U1xZ36VXbxOVwxgU1jBgFlPQBPWbUZ)
X-SignUser	Sì	Username o identificativo utente (es. A462252)

Esempio:

DELETE /api/v2/files/12345 HTTP/1.1
Host: sign.askme.it
X-SignToken: your-api-token
X-SignUser: your-username

---

Parametri

Parametro	Posizione	Tipo	Obbligatorio	Descrizione
idFile	path	number (long)	Sì	ID della pratica da eliminare.

---

Risposta (successo)

• Codice HTTP: 200 OK
• Body: true (boolean) — indica che l'eliminazione è avvenuta con successo.

true

Operazioni eseguite dal sistema:

1. Eliminazione dei contenuti dei documenti (dati binari, storico).
2. Impostazione del flag deletedData a true con timestamp di eliminazione.
3. Rimozione dei punti utente associati alla pratica.
4. Disabilitazione del record pratica nel database.
5. Esecuzione di eventuali plugin/hook configurati per l'evento REMOVE.

Codici di errore

Codice	Significato
401	Unauthorized – token o API Key mancanti o non validi.
403	Forbidden – utente non autorizzato all'eliminazione (DOC_DELETE) o non ha accesso alla pratica.
404	Not Found – pratica non trovata con l'ID specificato.
500	Internal Server Error – errore lato server; riprovare o contattare il supporto.

---

7. Webhook per Notifiche Stato

Endpoint: Configurabile dall'utente (specificato nel campo webhook o webhooks in fase di invio pratica)

Il sistema Askme Sign invia notifiche HTTP POST all'endpoint webhook configurato quando si verificano eventi significativi nel ciclo di vita della pratica: creazione, firma, rifiuto, scadenza, annullamento, ecc. Ogni notifica contiene un payload JSON con le informazioni sull'evento, sulla pratica e sul firmatario coinvolto.

I webhook vengono configurati al momento dell'invio della pratica (endpoint POST /api/v2/files/send) tramite i campi webhook (singolo endpoint) o webhooks (più endpoint). Per la struttura di configurazione si rimanda alla sezione Webhook del punto 1.

Caso d'uso: Un'applicazione vuole essere notificata in tempo reale quando un documento viene firmato, rifiutato o scade, per aggiornare automaticamente lo stato nel proprio database e avviare workflow successivi (es. archiviazione automatica del documento firmato, notifica interna al reparto, avvio di una nuova pratica).

---

Formato della notifica

Quando un evento si verifica, il sistema invia una richiesta HTTP POST all'URL configurato nel webhook, con corpo JSON e l'eventuale autenticazione specificata (authMode).

Struttura del payload JSON

Campo	Tipo	Descrizione
idFile	number (long)	ID univoco della pratica.
tenantCode	string	Codice del tenant a cui appartiene la pratica.
name	string	Nome della pratica.
status	char	Stato corrente della pratica dopo l'evento (vedi sezione Codici Stato).
action	char	Tipo di azione eseguita (vedi sezione Codici Azione).
signerEmail	string	Email del firmatario che ha eseguito l'azione.
notes	string	Note associate all'azione (es. motivazione del rifiuto). Presente solo per azioni diverse da sottomissione e rimozione.
protocol	string	Numero di protocollo della pratica (se presente).
externalId	string	ID esterno della pratica nel sistema sorgente (se presente).
time	string (date)	Data/ora dell'evento in formato ISO 8601 (es. 2024-10-23T10:09:00.000+0200).

Esempio di payload

{
  "idFile": 12345,
  "tenantCode": "TENANT01",
  "name": "Contratto Cliente Rossi",
  "status": "F",
  "action": "S",
  "signerEmail": "[email protected]",
  "notes": null,
  "protocol": "PROT-2024-001",
  "externalId": "CRM-98765",
  "time": "2024-10-23T10:09:00.000+0200"
}

---

Eventi che generano notifiche webhook

Evento	status	action	Descrizione
Pratica creata	L	I	La pratica è stata sottomessa e il processo di firma è iniziato.
Firma apposta	L o F	S, E, T, V, Q, O, J	Un firmatario ha apposto la propria firma. Se era l'ultimo firmatario, lo stato diventa F (Firmato).
Pratica rifiutata	R	D	Un firmatario ha rifiutato la pratica.
Pratica scaduta	E	—	La pratica ha superato la data di scadenza senza essere completata.
Pratica annullata	V	N	La pratica è stata annullata.
Visto apposto	L o F	P	Un firmatario ha apposto un visto.
Approvazione	L o F	W	Un firmatario ha approvato.

---

Gestione dei tentativi di invio

Il sistema gestisce automaticamente i retry in caso di fallimento della chiamata webhook. Per ogni esecuzione vengono registrati:

Campo	Descrizione
numTries	Numero di tentativi effettuati.
responseCode	Codice HTTP della risposta ricevuta dal vostro endpoint.
responseMessage	Messaggio della risposta HTTP.
success	true se l'invio è andato a buon fine.
tsLastExecution	Data/ora dell'ultimo tentativo.
tsNextPlannedExecution	Data/ora del prossimo tentativo pianificato (se fallito).

---

Personalizzazione del payload

È possibile configurare un template personalizzato per il body della notifica webhook a livello di tenant, utilizzando la chiave di configurazione webhook.body.[authConfig].content. Nel template sono supportate le seguenti variabili:

Variabile	Descrizione
$idFile	ID della pratica.
$tenantCode	Codice tenant.
$name	Nome della pratica.
$status	Stato della pratica.
$action	Azione eseguita.
$externalId	ID esterno.
$time	Timestamp dell'evento.

Se non è configurato un template personalizzato, viene utilizzato il payload JSON standard descritto sopra.

---

Codici Stato Comuni

Status della pratica

Codice	Costante	Descrizione
L	LAV	In lavorazione – la pratica è attiva e in attesa di firma/azione da parte di uno o più firmatari.
F	SIGNED	Firmato – tutti i firmatari hanno completato le azioni richieste. La pratica è chiusa con successo.
R	RIF	Rifiutato – un firmatario ha rifiutato la pratica.
A	APP	Completato – la pratica è stata completata.
S	SOS	Sospeso – la pratica è temporaneamente sospesa.
E	EXP	Scaduto – la pratica ha superato la data di scadenza senza essere completata.
U	UPLOADED	Caricato – il documento è stato caricato ma il processo di firma non è ancora avviato.
V	VOID	Annullato – la pratica è stata annullata.
C	CES	Cestinato – la pratica è stata cestinata/eliminata.

Action

Codice	Costante	Descrizione
I	SUBMIT	Sottomissione – la pratica è stata creata e inviata.
S	SIGNATURE	Firma elettronica semplice – firma base senza requisiti di identificazione forte.
E	SIGNATURE_FES	FES – Firma Elettronica Semplice (conforme eIDAS).
T	SIGNATURE_OTP	FES con OTP – firma elettronica semplice con verifica via codice OTP.
V	SIGNATURE_FEA	FEA – Firma Elettronica Avanzata.
Q	SIGNATURE_FEQ	FEQ – Firma Elettronica Qualificata.
O	ONE_SHOT	FEQ One-Shot – firma qualificata con certificato usa e getta.
M	SIGNATURE_AUTO	Firma automatica – firma apposta automaticamente dal sistema.
R	REMOTE_DIGITAL_SIGNATURE	Firma digitale remota – firma digitale con certificato remoto.
L	LOCAL_DIGITAL_SIGNATURE	Firma digitale locale PAdES – firma digitale con certificato locale.
J	SIGNATURE_IO	Firma IO – firma tramite app IO.
P	STAMP	Visto – apposizione di un visto/timbro.
W	APPROVAL	Approvazione – azione di approvazione nel workflow.
D	DENY	Rifiuto – il firmatario ha rifiutato la pratica.
N	VOIDED	Annullamento – la pratica è stata annullata.
Z	REMOVE	Rimozione – la pratica è stata rimossa.

---

Best Practices

1. Gestione delle credenziali: Conservare in modo sicuro API Key e username, preferibilmente in variabili d'ambiente
2. Paginazione: Utilizzare sempre la paginazione quando si recuperano liste di file per evitare timeout
3. Webhook: Implementare endpoint webhook per gestire notifiche asincrone sullo stato dei documenti
4. Retry logic: Implementare meccanismi di retry per chiamate API che potrebbero fallire temporaneamente
5. Validazione base64: Assicurarsi che il contenuto PDF sia correttamente codificato in base64 prima dell'invio
6. Coordinate firma: Le coordinate sono normalizzate (0-1), moltiplicarle per le dimensioni della pagina per ottenere pixel assoluti

---

Flusso Tipico di Lavoro

1. Preparazione: Codificare il documento PDF in base64
2. Invio: Chiamare /api/v2/files/send con documento e firmatari
3. Notifica: Il sistema invia email ai firmatari (se sendNotifications: true)
4. Monitoraggio: Ricevere webhook o polling su /api/v2/files/ per verificare lo stato
5. Download: Quando status diventa "L", scaricare con /api/v2/files/download/:idFile
6. Archiviazione: Salvare il documento firmato nel proprio sistema
7. Pulizia: Opzionalmente eliminare il file dal sistema con DELETE