API Endpoints

Questa sezione documenta tutti gli endpoint disponibili per Askme Sign API v2, con descrizioni dettagliate dei parametri e delle risposte.

Base URL

https://sign.askme.it/api/v2

Autenticazione

Tutti gli endpoint richiedono gli header di autenticazione API Key:

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

Header	Obbligatorio	Descrizione
`X-SignToken`	Sì	Token API per l'autenticazione
`X-SignUser`	Sì	Username o identificativo utente

Per maggiori dettagli sulla procedura di autenticazione, consulta la pagina Autenticazione.

Pratiche

Creare una Pratica

Crea una nuova pratica (processo di firma) inviando uno o più documenti con i relativi firmatari, coordinate di firma, scadenza e opzioni di notifica.

POST /files/send

Autorizzazioni richieste: DOC_SUBMIT

Parametri (Body)

Il body è un oggetto JSON di tipo FileInsertSimpleDTO.

Nome	Tipo	Obbligatorio	Descrizione
`documents`	array	Sì	Array di documenti da firmare. Ogni elemento contiene `base64content` o `externalUrl`, `filename`, `order`.
`documents[].base64content`	string	Condizionale	Contenuto del file in Base64. Obbligatorio se non si usa `externalUrl`.
`documents[].externalUrl`	string	Condizionale	URL pubblico del documento. Alternativa a `base64content`.
`documents[].filename`	string	Consigliato	Nome del file (es. `contratto.pdf`).
`documents[].order`	integer	No	Ordine del documento nella pratica (0-based).
`signers`	array	Sì	Array dei firmatari.
`signers[].email`	string	Condizionale	Email del firmatario. Obbligatorio se `username` non è specificato.
`signers[].firstName`	string	Condizionale	Nome del firmatario. Obbligatorio se `username` non è specificato.
`signers[].lastName`	string	Condizionale	Cognome del firmatario. Obbligatorio se `username` non è specificato.
`signers[].action`	string	Sì	Tipo di firma: `S` Semplice, `E` FES, `T` FES+OTP, `V` FEA, `Q` FEQ, `P` Visto, `O` FEQ One-Shot, `J` Firma IO.
`signers[].username`	string	Condizionale	Username se firmatario interno Askme Sign.
`signers[].signatureCoordinates`	array	No	Coordinate di posizionamento della firma sul documento.
`signers[].signatureCoordinates[].document`	integer	Sì	Indice del documento (0-based).
`signers[].signatureCoordinates[].page`	integer	Sì	Numero della pagina (1-based).
`signers[].signatureCoordinates[].positionX`	number	Sì	Posizione orizzontale (0–1).
`signers[].signatureCoordinates[].positionY`	number	Sì	Posizione verticale (0–1).
`signers[].signatureCoordinates[].width`	number	No	Larghezza del riquadro (0–1).
`signers[].signatureCoordinates[].height`	number	No	Altezza del riquadro (0–1).
`signers[].signatureCoordinates[].signatureType`	string	No	Tipo firma per questa coordinata (sovrascrive `action`).
`name`	string	Condizionale	Nome identificativo della pratica. Obbligatorio se non definito nella tipologia.
`notes`	string	No	Note aggiuntive per l'iter di firma.
`summary`	string	No	Sommario della pratica.
`sendNotifications`	boolean	No	Se `true` (default), invia email ai firmatari con il link per firmare.
`sendCopyIterCompleted`	boolean	No	Se `true` (default), invia email di completamento a pratica firmata.
`expirationDate`	string	No	Data scadenza in formato ISO 8601 (es. `2025-12-31T23:59:59+01:00`).
`expirationDateDays`	integer	No	Giorni alla scadenza dalla data di creazione. Alternativa a `expirationDate`.
`webhook`	object	No	Webhook per ricevere notifiche sugli eventi della pratica.
`webhook.url`	string	Sì	URL di callback (POST). Supporta placeholder: `{{idFile}}`, `{{status}}`, `{{signerEmail}}`.
`webhook.authMode`	string	No	Modalità autenticazione: `basic`, `header`, `oauth2`.
`webhook.username`	string	No	Username per Basic Auth.
`webhook.password`	string	No	Password per Basic Auth.
`draft`	boolean	No	Se `true`, salva come bozza senza avviare il processo.
`urgent`	boolean	No	Segna la pratica come urgente. Default: `false`.
`privacy`	string	No	Livello di privacy: `P` pubblico, `A` aziendale (default), `C` confidenziale, `S` strettamente confidenziale.
`destinationContacts`	array	No	Contatti in copia conoscenza (ricevono email a completamento/rifiuto).
`destinationContacts[].email`	string	Sì	Email del contatto destinatario.
`placeholders`	array	No	Campi compilabili sul documento (testo, data, checkbox, allegato).
`params`	array	No	Parametri/metadati del workflow (chiave/valore).
`workflowTypeCode`	string	No	Codice della tipologia di processo.

Esempio di Richiesta

curl -X POST "https://sign.askme.it/api/v2/files/send" \
  -H "X-SignToken: your-api-token" \
  -H "X-SignUser: your-username" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "filename": "contratto.pdf",
        "base64content": "JVBERi0xLjMNCiXi48/T..."
      }
    ],
    "name": "Contratto di Servizio Q1 2025",
    "notes": "Contratto annuale di manutenzione",
    "sendNotifications": true,
    "expirationDateDays": 30,
    "signers": [
      {
        "firstName": "Mario",
        "lastName": "Rossi",
        "email": "[email protected]",
        "action": "S",
        "signatureCoordinates": [
          {
            "document": 0,
            "page": 1,
            "signatureType": "S",
            "positionX": 0.6,
            "positionY": 0.8,
            "width": 0.2,
            "height": 0.08
          }
        ]
      }
    ]
  }'

Risposta (200 OK)

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

Campo	Tipo	Descrizione
`idFile`	number	ID univoco della pratica creata.
`canAutoAdvance`	boolean	Se `true`, il workflow avanza automaticamente allo step successivo.
`signers`	array	Elenco dei firmatari con i rispettivi link per firmare.
`signers[].signingUrl`	string	Link per il firmatario esterno per procedere alla firma.
`signers[].password`	string	Password di accesso (se richiesta e generata dal sistema).

Ottenere Dettagli Pratica

Recupera lo stato e i dettagli completi di una pratica, inclusi documenti, firmatari, storico eventi, annotazioni e metadati.

GET /files/{idFile}

Autorizzazioni richieste: DOC_LST, DOC_PERSONAL, DOC_SIGN o UNIT_DOC_ADMIN + permesso di visualizzazione sulla pratica.

Parametri (URL)

Nome	Tipo	Obbligatorio	Descrizione
`idFile`	number	Sì	ID della pratica.

Parametri (Query)

Nome	Tipo	Obbligatorio	Default	Descrizione
`idUser`	number	No	—	ID dell'utente per il quale registrare l'evento di apertura.
`nextSteps`	boolean	No	`false`	Se `true`, include le informazioni sui prossimi step del workflow.
`lockDocument`	boolean	No	`false`	Se `true`, blocca il documento per l'utente corrente (utile in contesti multi-firmatario).

Esempio di Richiesta

curl -X GET "https://sign.askme.it/api/v2/files/12345" \
  -H "X-SignToken: your-api-token" \
  -H "X-SignUser: your-username"

Risposta (200 OK)

{
  "idFile": 12345,
  "name": "Contratto di Servizio Q1 2025",
  "notes": "Contratto annuale di manutenzione",
  "status": "L",
  "numDocuments": 1,
  "urgent": false,
  "privacy": "A",
  "digitalSigned": false,
  "expirationDate": "2025-06-30T23:59:59+02:00",
  "tsIns": "2025-01-15T10:30:00+01:00",
  "tsUpd": "2025-01-15T10:30:00+01:00",
  "user": {
    "idUser": 1001,
    "firstName": "Admin",
    "lastName": "User",
    "email": "[email protected]"
  },
  "signers": [
    {
      "email": "[email protected]",
      "firstName": "Mario",
      "lastName": "Rossi",
      "action": "S",
      "status": "L"
    }
  ],
  "documents": [
    {
      "idDocument": 5001,
      "filename": "contratto.pdf",
      "contentType": "application/pdf",
      "order": 0
    }
  ],
  "events": [
    {
      "action": "I",
      "tsIns": "2025-01-15T10:30:00+01:00",
      "description": "Pratica creata"
    }
  ],
  "metadata": [],
  "tags": [],
  "canAdvance": true,
  "deletedData": false
}

Campo	Tipo	Descrizione
`idFile`	number	ID univoco della pratica.
`name`	string	Nome della pratica.
`notes`	string	Note della pratica.
`summary`	string	Sommario della pratica.
`status`	char	Stato della pratica (`L` In lavorazione, `F` Firmato, `R` Rifiutato, `E` Scaduto, ecc.).
`numDocuments`	integer	Numero di documenti nella pratica.
`urgent`	boolean	Se la pratica è urgente.
`privacy`	string	Livello di privacy (`P`, `A`, `C`, `S`).
`digitalSigned`	boolean	Se contiene firme digitali.
`sealed`	boolean	Se la pratica è sigillata.
`expirationDate`	string	Data di scadenza.
`protocol`	string	Numero di protocollo.
`tsIns`	string	Data/ora di creazione.
`tsUpd`	string	Data/ora ultimo aggiornamento.
`user`	object	Utente creatore (`idUser`, `firstName`, `lastName`, `email`).
`signers`	array	Elenco dei firmatari con stato e azione.
`documents`	array	Elenco dei documenti allegati.
`events`	array	Storico degli eventi della pratica.
`history`	array	Storico delle versioni dei documenti.
`placeholders`	array	Campi compilabili configurati.
`metadata`	array	Parametri/metadati del workflow.
`tags`	array	Tag associati alla pratica.
`webhook`	object	Configurazione webhook (se presente).
`destinationContacts`	array	Contatti destinatari in copia.
`canAdvance`	boolean	Se il workflow può avanzare.
`deletedData`	boolean	Se i dati dei documenti sono stati eliminati.

Risposta (404 Not Found)

Restituito se la pratica non esiste o è stata disattivata (active = false).

Elenco Pratiche

Recupera l'elenco paginato delle pratiche visibili all'utente autenticato, con supporto per filtri e ordinamento.

GET /files/

Autorizzazioni richieste: DOC_LST, UNIT_DOC_ADMIN o DOC_PERSONAL.

Parametri (Query) — Paginazione

Nome	Tipo	Obbligatorio	Default	Descrizione
`page`	integer	No	`0`	Numero pagina (0-based).
`size`	integer	No	`100`	Elementi per pagina.
`sort`	string	No	`idFile,desc`	Ordinamento (es. `tsIns,desc`, `name,asc`). Ripetibile per più criteri.

Parametri (Query) — Filtri

Nome	Tipo	Obbligatorio	Descrizione
`idFile`	number	No	Filtra per ID pratica.
`query`	string	No	Ricerca testuale su nome e altri campi.
`status`	string	No	Stato/i della pratica. Ripetibile (es. `status=L&status=F`). Valori: `L`, `F`, `R`, `E`, `S`, `V`, `U`, `A`, `C`.
`tsInsFrom`	string	No	Data creazione da (formato `yyyy-MM-dd`).
`tsInsTo`	string	No	Data creazione a (formato `yyyy-MM-dd`).
`tsUpdFrom`	string	No	Data aggiornamento da.
`tsUpdTo`	string	No	Data aggiornamento a.
`expirationDateMin`	string	No	Scadenza minima.
`expirationDateMax`	string	No	Scadenza massima.
`idUser`	number	No	Filtra per ID utente creatore.
`userEmail`	string	No	Filtra per email utente creatore.
`idSigner`	number	No	Filtra per ID firmatario. Ripetibile.
`urgent`	boolean	No	Solo pratiche urgenti.
`digitalSigned`	boolean	No	Solo pratiche con firma digitale.
`protocol`	string	No	Filtra per protocollo.
`externalId`	string	No	Filtra per ID sistema esterno.
`metadataKey`	string	No	Filtra per chiave metadato.
`metadataValue`	string	No	Filtra per valore metadato (con `metadataKey`).

Esempio di Richiesta

curl -X GET "https://sign.askme.it/api/v2/files/?page=0&size=20&sort=tsIns,desc&status=L" \
  -H "X-SignToken: your-api-token" \
  -H "X-SignUser: your-username"

Risposta (200 OK)

{
  "content": [
    {
      "idFile": 12345,
      "name": "Contratto di Servizio Q1 2025",
      "status": "L",
      "numDocuments": 1,
      "urgent": false,
      "privacy": "A",
      "tsIns": "2025-01-15T10:30:00+01:00",
      "user": {
        "idUser": 1001,
        "firstName": "Admin",
        "lastName": "User",
        "email": "[email protected]"
      },
      "signers": [
        {
          "email": "[email protected]",
          "firstName": "Mario",
          "lastName": "Rossi",
          "action": "S"
        }
      ]
    }
  ],
  "totalElements": 150,
  "totalPages": 8,
  "size": 20,
  "number": 0,
  "numberOfElements": 20,
  "first": true,
  "last": false
}

Campo	Tipo	Descrizione
`content`	array	Array degli elementi nella pagina corrente.
`totalElements`	number	Totale elementi corrispondenti ai filtri.
`totalPages`	number	Totale pagine.
`size`	number	Dimensione pagina richiesta.
`number`	number	Numero pagina corrente (0-based).
`first`	boolean	`true` se è la prima pagina.
`last`	boolean	`true` se è l'ultima pagina.

Ottenere il Link di Firma

Restituisce il magic link di una pratica, utile per recuperare l'URL di firma da condividere con i firmatari esterni.

GET /files/{idFile}/link

Autorizzazioni richieste: permesso di visualizzazione sulla pratica.

Parametri (URL)

Nome	Tipo	Obbligatorio	Descrizione
`idFile`	number	Sì	ID della pratica.

Esempio di Richiesta

curl -X GET "https://sign.askme.it/api/v2/files/12345/link" \
  -H "X-SignToken: your-api-token" \
  -H "X-SignUser: your-username"

Risposta (200 OK)

"https://sign.askme.it/external-sign?token=abc123def456..."

Documenti

Upload Documento (Multipart)

Carica un documento sul server prima di utilizzarlo in una pratica. Il file caricato viene elaborato (conversione PDF, verifica firme) e restituisce un identificativo da usare nel campo uploadedFilename dell'endpoint di creazione pratica.

POST /documents/upload

Autorizzazioni richieste: DOC_SUBMIT.

Content-Type: multipart/form-data

Parametri (Form Data)

Nome	Tipo	Obbligatorio	Default	Descrizione
`file`	file	Sì	—	File da caricare (PDF, DOCX, ecc.).
`convert`	boolean	No	`true`	Se `true`, converte il documento in formato PDF standard.
`verifySignatures`	boolean	No	`false`	Se `true`, verifica le firme digitali eventualmente presenti.

Esempio di Richiesta

curl -X POST "https://sign.askme.it/api/v2/documents/upload" \
  -H "X-SignToken: your-api-token" \
  -H "X-SignUser: your-username" \
  -F "file=@/path/to/contratto.pdf" \
  -F "convert=true" \
  -F "verifySignatures=false"

Risposta (200 OK)

{
  "uuid": null,
  "filename": "contratto_20250115103000.pdf",
  "originalFilename": "contratto.pdf",
  "pages": 3,
  "isP7m": false,
  "convertedPdfa": false,
  "rotated": false,
  "external": false,
  "readonly": false,
  "hasAcrofields": false,
  "pagesSize": [
    { "page": 1, "width": 595, "height": 842 },
    { "page": 2, "width": 595, "height": 842 },
    { "page": 3, "width": 595, "height": 842 }
  ],
  "signatures": []
}

Campo	Tipo	Descrizione
`filename`	string	Nome del file elaborato. Da usare come `uploadedFilename` nell'endpoint di creazione pratica.
`originalFilename`	string	Nome originale del file caricato.
`pages`	integer	Numero di pagine del documento.
`isP7m`	boolean	Se il file è in formato P7M (firma CAdES).
`convertedPdfa`	boolean	Se il file è stato convertito in PDF/A.
`rotated`	boolean	Se il documento è stato ruotato.
`readonly`	boolean	Se il documento è in sola lettura.
`hasAcrofields`	boolean	Se il PDF contiene campi AcroForm.
`pagesSize`	array	Dimensioni di ogni pagina (larghezza/altezza in punti PDF).
`signatures`	array	Firme digitali trovate nel documento (se `verifySignatures=true`).

Upload Documento (Base64)

Versione alternativa dell'upload che accetta il documento codificato in Base64 nel body JSON anziché come multipart. Utile per integrazioni server-to-server.

POST /documents/upload/encoded

Autorizzazioni richieste: DOC_SUBMIT.

Content-Type: application/json

Parametri (Body)

Nome	Tipo	Obbligatorio	Descrizione
`filename`	string	Sì	Nome del file (es. `contratto.pdf`).
`base64content`	string	Sì	Contenuto del file codificato in Base64.
`convert`	boolean	No	Se `true`, converte il documento in PDF.
`verifySignatures`	boolean	No	Se `true`, verifica le firme digitali presenti.

Esempio di Richiesta

curl -X POST "https://sign.askme.it/api/v2/documents/upload/encoded" \
  -H "X-SignToken: your-api-token" \
  -H "X-SignUser: your-username" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "contratto.pdf",
    "base64content": "JVBERi0xLjMNCiXi48/T...",
    "convert": true,
    "verifySignatures": false
  }'

Risposta (200 OK)

Stessa struttura della risposta dell'Upload Documento (Multipart).

Elenco Documenti di una Pratica

Recupera l'elenco dei singoli documenti contenuti in una pratica, con informazioni su pagine, tipo, ordine e stato.

GET /files/{idFile}/documents

Autorizzazioni richieste: permesso di visualizzazione sulla pratica.

Parametri (URL)

Nome	Tipo	Obbligatorio	Descrizione
`idFile`	number	Sì	ID della pratica.

Esempio di Richiesta

curl -X GET "https://sign.askme.it/api/v2/files/12345/documents" \
  -H "X-SignToken: your-api-token" \
  -H "X-SignUser: your-username"

Risposta (200 OK)

[
  {
    "idDocument": 5001,
    "idFile": 12345,
    "name": "contratto.pdf",
    "pages": 3,
    "mimeType": "application/pdf",
    "documentOrder": 0,
    "visible": true,
    "attachment": false,
    "readonly": false,
    "digitalSigned": false,
    "external": false,
    "blobExist": true,
    "tsIns": "2025-01-15T10:30:00+01:00",
    "pagesSize": [
      { "page": 1, "width": 595, "height": 842 }
    ]
  }
]

Campo	Tipo	Descrizione
`idDocument`	number	ID univoco del documento. Da usare per download/viewer del singolo documento.
`idFile`	number	ID della pratica di appartenenza.
`name`	string	Nome del file.
`pages`	integer	Numero di pagine.
`mimeType`	string	MIME type del documento.
`documentOrder`	integer	Ordine del documento nella pratica (0-based).
`visible`	boolean	Se il documento è visibile all'utente.
`attachment`	boolean	Se è un allegato (non documento principale).
`readonly`	boolean	Se il documento è in sola lettura.
`digitalSigned`	boolean	Se contiene firme digitali.
`external`	boolean	Se il documento proviene da fonte esterna.
`externalUrl`	string	URL esterno (se `external=true`).
`docExternalId`	string	ID esterno del documento.
`blobExist`	boolean	Se il contenuto binario è disponibile.
`tsIns`	string	Data/ora di inserimento.
`pagesSize`	array	Dimensioni di ogni pagina.

Visualizzare un Documento (Viewer)

Restituisce il contenuto PDF di un singolo documento per la visualizzazione inline nel browser. Per visualizzare tutti i documenti di una pratica in un unico stream, usare l'endpoint alternativo GET /files/viewer/{idFile}.

GET /documents/viewer/{idDocument}

Autorizzazioni richieste: permesso di visualizzazione sul documento.

Parametri (URL)

Nome	Tipo	Obbligatorio	Descrizione
`idDocument`	number	Sì	ID del documento (ottenuto dall'Elenco Documenti).

Esempio di Richiesta

curl -X GET "https://sign.askme.it/api/v2/documents/viewer/5001" \
  -H "X-SignToken: your-api-token" \
  -H "X-SignUser: your-username" \
  -o preview-documento.pdf

Risposta (200 OK)

Header	Valore
`Content-Type`	`application/pdf`
`Content-Length`	Dimensione in byte
`Content-Disposition`	`inline; filename="contratto.pdf"`

Viewer a livello pratica

Per visualizzare tutti i documenti della pratica in un'unica chiamata:

GET /files/viewer/{idFile}

Restituisce il PDF combinato (o ZIP se più documenti) con Content-Disposition: inline.

Download Singolo Documento

Scarica un singolo documento specifico di una pratica (a differenza di GET /files/download/{idFile} che scarica tutti i documenti).

GET /documents/download/{idDocument}

Autorizzazioni richieste: DOC_DOWNLOAD + permesso di visualizzazione sul documento.

Parametri (URL)

Nome	Tipo	Obbligatorio	Descrizione
`idDocument`	number	Sì	ID del documento (ottenuto dall'Elenco Documenti).

Esempio di Richiesta

curl -X GET "https://sign.askme.it/api/v2/documents/download/5001" \
  -H "X-SignToken: your-api-token" \
  -H "X-SignUser: your-username" \
  -o contratto-firmato.pdf

Risposta (200 OK)

Header	Valore
`Content-Type`	`application/pdf`
`Content-Length`	Dimensione in byte
`Content-Disposition`	`attachment; filename="contratto.pdf"`

Firma digitale CAdES

Per documenti con firma CAdES, l'estensione .p7m viene aggiunta automaticamente al filename. Se il documento è un PDF con firma non-CAdES, l'estensione .pdf viene aggiunta se non presente.

Firme

Inviare Copia del Documento Firmato

Invia via email una copia dei documenti di una pratica a uno o più destinatari, con possibilità di personalizzare oggetto e corpo del messaggio.

POST /files/send-copy

Autorizzazioni richieste: DOC_LST, UNIT_DOC_ADMIN o DOC_PERSONAL.

Parametri (Body)

Nome	Tipo	Obbligatorio	Descrizione
`idFile`	number	Sì	ID della pratica di cui inviare la copia.
`emails`	array[string]	Sì	Indirizzi email dei destinatari (almeno uno).
`subject`	string	No	Oggetto dell'email. Se omesso, usa il template predefinito.
`message`	string	No	Corpo del messaggio email personalizzato.
`sendCopySender`	boolean	No	Se `true`, invia una copia in CC all'utente autenticato. Default: `false`.

Esempio di Richiesta

curl -X POST "https://sign.askme.it/api/v2/files/send-copy" \
  -H "X-SignToken: your-api-token" \
  -H "X-SignUser: your-username" \
  -H "Content-Type: application/json" \
  -d '{
    "idFile": 12345,
    "emails": [
      "[email protected]",
      "[email protected]"
    ],
    "subject": "Copia del contratto firmato",
    "message": "In allegato trova il contratto firmato da tutti i firmatari.",
    "sendCopySender": true
  }'

Risposta (200 OK)

true

Campo	Tipo	Descrizione
—	boolean	`true` se l'invio è avvenuto con successo.

Ottenere Audit Trail

Scarica il report di audit trail (cronologia completa) di una pratica in formato PDF. Il report contiene tutti gli eventi registrati: creazione, apertura, firma, rifiuto, download, con timestamp e dettagli dell'utente.

GET /files/{idFile}/report/download

Autorizzazioni richieste: DOC_LST, UNIT_DOC_ADMIN, DOC_PERSONAL o DOC_SIGN + permesso di visualizzazione sulla pratica.

Parametri (URL)

Nome	Tipo	Obbligatorio	Descrizione
`idFile`	number	Sì	ID della pratica.

Esempio di Richiesta

curl -X GET "https://sign.askme.it/api/v2/files/12345/report/download" \
  -H "X-SignToken: your-api-token" \
  -H "X-SignUser: your-username" \
  -o audit-trail-12345.pdf

Risposta (200 OK)

La risposta è un file PDF binario (stream) con gli header:

Header	Valore
`Content-Type`	`application/pdf`
`Content-Length`	Dimensione in byte
`Content-Disposition`	`attachment; filename="report_12345.pdf"`

Visualizzazione inline

Per visualizzare il report nel browser senza scaricarlo, usare l'endpoint alternativo:

GET /files/{idFile}/report

Questo endpoint restituisce lo stesso PDF ma con Content-Disposition: inline.

Download e Eliminazione

Download File Firmato

Scarica i documenti di una pratica. Se la pratica contiene un solo documento, restituisce il file diretto. Se contiene più documenti, restituisce un archivio ZIP.

GET /files/download/{idFile}

Autorizzazioni richieste: DOC_DOWNLOAD + permesso di visualizzazione sulla pratica.

Parametri (URL)

Nome	Tipo	Obbligatorio	Descrizione
`idFile`	number	Sì	ID della pratica da scaricare.

Esempio di Richiesta

curl -X GET "https://sign.askme.it/api/v2/files/download/12345" \
  -H "X-SignToken: your-api-token" \
  -H "X-SignUser: your-username" \
  -o contratto-firmato.pdf

Risposta (200 OK)

Header	Valore
`Content-Type`	`application/pdf` (singolo documento) o `application/zip` (più documenti)
`Content-Length`	Dimensione in byte
`Content-Disposition`	`attachment; filename="contratto.pdf"`

Firma digitale CAdES

Per documenti con firma digitale CAdES, il filename avrà estensione .p7m aggiunta automaticamente.

Eliminazione File

Esegue l'eliminazione logica di una pratica. I dati dei documenti (contenuti, storico, annotazioni) vengono rimossi definitivamente. Il record della pratica viene disabilitato.

DELETE /files/{idFile}

Autorizzazioni richieste: DOC_DELETE + permesso di visualizzazione sulla pratica.

Parametri (URL)

Nome	Tipo	Obbligatorio	Descrizione
`idFile`	number	Sì	ID della pratica da eliminare.

Esempio di Richiesta

curl -X DELETE "https://sign.askme.it/api/v2/files/12345" \
  -H "X-SignToken: your-api-token" \
  -H "X-SignUser: your-username"

Risposta (200 OK)

true

Account

Verifica Stato Account

Restituisce le informazioni sull'utente autenticato: dati anagrafici, permessi, tenant disponibili, configurazioni di firma.

GET /account

Parametri

Nessun parametro richiesto. L'utente viene identificato dagli header di autenticazione.

Esempio di Richiesta

curl -X GET "https://sign.askme.it/api/v2/account" \
  -H "X-SignToken: your-api-token" \
  -H "X-SignUser: your-username"

Risposta (200 OK)

{
  "idUser": 1001,
  "username": "A462252",
  "firstName": "Mario",
  "lastName": "Rossi",
  "email": "[email protected]",
  "enabled": true,
  "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
}

Campo	Tipo	Descrizione
`idUser`	number	ID univoco dell'utente.
`username`	string	Username dell'utente.
`firstName`	string	Nome.
`lastName`	string	Cognome.
`email`	string	Email.
`enabled`	boolean	Se l'utente è attivo.
`status`	char	`A` presente, `O` assente.
`permissions`	array[string]	Permessi dell'utente.
`currentTenant`	object	Tenant corrente (`idTenant`, `code`, `name`).
`availableTenants`	array	Tenant disponibili.
`notificationsEnabled`	boolean	Se le notifiche sono abilitate.
`twoFactorAuthEnabled`	boolean	Se il 2FA è abilitato.
`feqRemoteEnabled`	boolean	Se la FEQ remota è abilitata.

Gestione Errori

Formato della risposta di errore

Tutti gli endpoint restituiscono un oggetto AskmeSignApiError in caso di errore:

{
  "status": 400,
  "details": "Documenti mancanti o non validi",
  "messageKey": "error.file.missingData",
  "code": "VALIDATION_ERROR",
  "reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2025-01-15T10:30:00+01:00",
  "type": "common"
}

Campo	Tipo	Descrizione
`status`	integer	Codice HTTP.
`details`	string	Messaggio di errore leggibile.
`messageKey`	string	Chiave per internazionalizzazione.
`code`	string	Codice errore applicativo.
`reference`	string	UUID univoco della richiesta (per il supporto).
`timestamp`	string	Data/ora dell'errore.
`type`	string	Tipo errore (es. `common`).

Codici di Errore HTTP

Codice	Descrizione
`200`	Successo
`400`	Bad Request – body malformato, validazione fallita, parametri mancanti.
`401`	Unauthorized – token o API Key mancanti o non validi.
`403`	Forbidden – utente non autorizzato all'azione richiesta.
`404`	Not Found – risorsa non trovata (pratica, workflow type, modulo).
`500`	Internal Server Error – errore lato server; riprovare o contattare il supporto.

Codici di Riferimento

Status della pratica

Codice	Descrizione
`L`	In lavorazione – in attesa di firma.
`F`	Firmato – tutte le firme completate.
`R`	Rifiutato – un firmatario ha rifiutato.
`A`	Completato – pratica completata.
`S`	Sospeso – temporaneamente sospesa.
`E`	Scaduto – scadenza superata.
`U`	Caricato – documento caricato, processo non avviato.
`V`	Annullato – pratica annullata.
`C`	Cestinato – pratica cestinata.

Tipi di azione/firma

Codice	Descrizione
`S`	Firma elettronica semplice
`E`	FES (Firma Elettronica Semplice conforme eIDAS)
`T`	FES con OTP
`V`	FEA (Firma Elettronica Avanzata)
`Q`	FEQ (Firma Elettronica Qualificata)
`O`	FEQ One-Shot
`M`	Firma automatica
`R`	Firma digitale remota
`L`	Firma digitale locale (PAdES)
`J`	Firma IO
`P`	Visto
`W`	Approvazione
`D`	Rifiuto
`N`	Annullamento

OpenAPI / Swagger

La specifica OpenAPI completa è disponibile come file JSON:

https://docs.askme.it/api-docs-sign.json

Prossimi Passi

Consulta l'Overview API per casi d'uso dettagliati con esempi avanzati
Leggi la guida sull'Autenticazione per configurare le credenziali

Base URL​

Autenticazione​

Pratiche​

Creare una Pratica​

Parametri (Body)​

Ottenere Dettagli Pratica​

Parametri (URL)​

Parametri (Query)​

Elenco Pratiche​

Parametri (Query) — Paginazione​

Parametri (Query) — Filtri​

Ottenere il Link di Firma​

Parametri (URL)​

Documenti​

Upload Documento (Multipart)​

Parametri (Form Data)​

Upload Documento (Base64)​

Parametri (Body)​

Elenco Documenti di una Pratica​

Parametri (URL)​

Visualizzare un Documento (Viewer)​

Parametri (URL)​

Download Singolo Documento​

Parametri (URL)​

Firme​

Inviare Copia del Documento Firmato​

Parametri (Body)​

Ottenere Audit Trail​

Parametri (URL)​

Download e Eliminazione​

Download File Firmato​

Parametri (URL)​

Eliminazione File​

Parametri (URL)​

Account​

Verifica Stato Account​

Parametri​

Gestione Errori​

Formato della risposta di errore​

Codici di Errore HTTP​

Codici di Riferimento​

Status della pratica​

Tipi di azione/firma​

OpenAPI / Swagger​

Prossimi Passi​

Base URL

Autenticazione

Pratiche

Creare una Pratica

Parametri (Body)

Ottenere Dettagli Pratica

Parametri (URL)

Parametri (Query)

Elenco Pratiche

Parametri (Query) — Paginazione

Parametri (Query) — Filtri

Ottenere il Link di Firma

Parametri (URL)

Documenti

Upload Documento (Multipart)

Parametri (Form Data)

Upload Documento (Base64)

Parametri (Body)

Elenco Documenti di una Pratica

Parametri (URL)

Visualizzare un Documento (Viewer)

Parametri (URL)

Download Singolo Documento

Parametri (URL)

Firme

Inviare Copia del Documento Firmato

Parametri (Body)

Ottenere Audit Trail

Parametri (URL)

Download e Eliminazione

Download File Firmato

Parametri (URL)

Eliminazione File

Parametri (URL)

Account

Verifica Stato Account

Parametri

Gestione Errori

Formato della risposta di errore

Codici di Errore HTTP

Codici di Riferimento

Status della pratica

Tipi di azione/firma

OpenAPI / Swagger

Prossimi Passi