Documenti di sistema

I Documenti di sistema sono documenti PDF caricati una sola volta e condivisi con tutta l'organizzazione, riutilizzabili nelle pratiche senza doverli ricaricare ad ogni invio (informative privacy, condizioni generali, moduli standard aziendali). Concetti, permessi e gestione da interfaccia sono descritti nel capitolo Documenti di sistema del manuale utente.

Denominazione lato API

Per ragioni di compatibilità storica, lato API l'entità è ancora denominata module: gli endpoint si trovano sotto /api/v2/modules e i campi di riferimento si chiamano idModule e moduleCode.

Permessi

I permessi citati in questa pagina corrispondono ai seguenti codici (quelli restituiti dall'endpoint /account):

Permesso	Codice	Descrizione
`ADM_SYSTEM_DOCUMENTS`	`AS_ADM_SYSDOC`	Amministrazione documenti di sistema
`DOC_SUBMIT`	`AS_DOC_SUB`	Sottomissione documenti
`DOC_SIGN`	`AS_DOC_SGN`	Firma documenti
`ADM_WORKFLOWS`	`AS_ADM_WOR`	Amministrazione tipologie di processo
`ADM_WORKFLOW_TYPE_LIMITATION`	`AS_ADM_WF_LMT`	Amministrazione limitazioni tipologie

Le regole di visibilità multi-tenant descritte nel manuale valgono anche per le API: un utente vede i Documenti di sistema delle proprie organizzazioni più quelli globali, e non può leggere né modificare documenti di organizzazioni a cui non appartiene. Un riferimento a un documento non visibile restituisce 404 Not Found. I documenti globali possono essere creati e modificati solo dal superadmin o da un amministratore documenti di sistema senza organizzazione.

Riepilogo endpoint

Metodo	Endpoint	Descrizione	Permessi
`GET`	`/modules/`	Elenco paginato e filtrabile	`ADM_SYSTEM_DOCUMENTS`, `DOC_SIGN`, `DOC_SUBMIT`
`GET`	`/modules/{idModule}`	Dettaglio	`ADM_SYSTEM_DOCUMENTS`, `DOC_SIGN`, `DOC_SUBMIT`
`GET`	`/modules/{idModule}/template`	Scarica il PDF	— (utente autenticato)
`GET`	`/modules/{idModule}/template/pages`	Informazioni sulle pagine	`ADM_SYSTEM_DOCUMENTS`, `DOC_SIGN`, `DOC_SUBMIT`, `ADM_WORKFLOWS`, `ADM_WORKFLOW_TYPE_LIMITATION`
`POST`	`/modules/`	Inserimento	`ADM_SYSTEM_DOCUMENTS`
`PUT`	`/modules/`	Aggiornamento	`ADM_SYSTEM_DOCUMENTS`
`DELETE`	`/modules/{idModule}`	Eliminazione logica	`ADM_SYSTEM_DOCUMENTS`

Elenco Documenti di sistema

Recupera l'elenco paginato dei Documenti di sistema visibili all'utente autenticato, con supporto per filtri e ordinamento.

GET /modules/

Autorizzazioni richieste: ADM_SYSTEM_DOCUMENTS, DOC_SIGN o DOC_SUBMIT.

Parametri (Query) — Paginazione

Nome	Tipo	Obbligatorio	Default	Descrizione
`page`	integer	No	`0`	Numero pagina (0-based).
`size`	integer	No	tutti	Elementi per pagina. Se omesso, restituisce tutti gli elementi.
`sort`	string	No	—	Ordinamento (es. `tsIns,desc`, `name,asc`). Ripetibile per più criteri.

Parametri (Query) — Filtri

Nome	Tipo	Obbligatorio	Descrizione
`name`	string	No	Ricerca per nome (contiene, case-insensitive).
`code`	string	No	Ricerca per codice (contiene, case-insensitive).
`description`	string	No	Ricerca per descrizione (contiene, case-insensitive).
`idTenant`	number	No	Solo i documenti di quella organizzazione (esclusi i globali). L'organizzazione deve essere tra quelle dell'utente.
`tsInsFrom`	string	No	Data creazione da (formato `yyyy-MM-dd`).
`tsInsTo`	string	No	Data creazione a.
`tsUpdFrom`	string	No	Data aggiornamento da.
`tsUpdTo`	string	No	Data aggiornamento a.

Esempio di Richiesta

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

Risposta (200 OK)

{
  "content": [
    {
      "idModule": 42,
      "code": "INFORMATIVA_PRIVACY",
      "name": "Informativa Privacy",
      "description": "Informativa privacy da allegare ai contratti",
      "originalFilename": "informativa-privacy.pdf",
      "pages": 2,
      "mimeType": "application/pdf",
      "withContent": true,
      "global": false,
      "idTenant": 1,
      "tenant": {
        "idTenant": 1,
        "code": "TENANT01",
        "name": "Azienda SpA"
      },
      "tsIns": "2025-01-15T10:30:00+01:00",
      "tsUpd": "2025-02-01T09:00:00+01:00",
      "active": true
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "size": 20,
  "number": 0,
  "first": true,
  "last": true
}

Campo	Tipo	Descrizione
`idModule`	number	ID univoco del Documento di sistema. Utilizzabile come `idModule` nei riferimenti.
`code`	string	Codice identificativo facoltativo (il campo Codice della maschera di amministrazione). Utilizzabile come `moduleCode` nei riferimenti.
`name`	string	Nome con cui il documento viene proposto in fase di scelta.
`description`	string	Testo descrittivo libero.
`originalFilename`	string	Nome del file PDF originale caricato (usato come nome file al download).
`pages`	integer	Numero di pagine del PDF.
`mimeType`	string	MIME type del contenuto (`application/pdf`).
`withContent`	boolean	Se il documento ha un contenuto PDF associato.
`global`	boolean	Se `true`, il documento è globale (visibile a tutti gli utenti dell'installazione).
`idTenant`	number	ID dell'organizzazione proprietaria; assente se il documento è globale.
`tenant`	object	Dati essenziali dell'organizzazione proprietaria (`idTenant`, `code`, `name`).
`tsIns`	string	Data/ora di creazione.
`tsUpd`	string	Data/ora dell'ultima modifica.
`active`	boolean	Se `false`, il documento è stato eliminato logicamente.

Dettaglio Documento di sistema

Recupera il dettaglio completo di un singolo Documento di sistema.

GET /modules/{idModule}

Autorizzazioni richieste: ADM_SYSTEM_DOCUMENTS, DOC_SIGN o DOC_SUBMIT + visibilità sul documento.

Parametri (URL)

Nome	Tipo	Obbligatorio	Descrizione
`idModule`	number	Sì	ID del Documento di sistema.

Esempio di Richiesta

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

Risposta (200 OK)

Stessa struttura dell'elemento restituito dall'elenco, con in più:

Campo	Tipo	Descrizione
`placeholders`	array	Placeholder configurati sul documento (vedi Placeholder).
`notesCoordinates`	array	Annotazioni configurate sul documento.

Scaricare il PDF

Restituisce il contenuto PDF del Documento di sistema.

GET /modules/{idModule}/template

Autorizzazioni richieste: utente autenticato con visibilità sul documento.

Esempio di Richiesta

curl -X GET "https://sign.askme.it/api/v2/modules/42/template" \
  -H "X-SignToken: your-api-token" \
  -H "X-SignUser: your-username" \
  -o informativa-privacy.pdf

Risposta (200 OK)

Header	Valore
`Content-Type`	`application/pdf`
`Content-Disposition`	`attachment; filename="informativa-privacy.pdf"`

Informazioni sulle pagine

Restituisce le dimensioni di ogni pagina del PDF. È l'endpoint usato dall'editor per calcolare la posizione di firme e placeholder quando si seleziona un Documento di sistema.

GET /modules/{idModule}/template/pages

Autorizzazioni richieste: ADM_SYSTEM_DOCUMENTS, DOC_SIGN, DOC_SUBMIT, ADM_WORKFLOWS o ADM_WORKFLOW_TYPE_LIMITATION + visibilità sul documento.

Esempio di Richiesta

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

Risposta (200 OK)

Un elemento per pagina, con le dimensioni in punti PDF:

[
  { "width": 595.0, "height": 842.0 },
  { "width": 595.0, "height": 842.0 }
]

Creare un Documento di sistema

Crea un nuovo Documento di sistema. Il PDF va prima caricato tramite l'endpoint di Upload Documento: il filename restituito dall'upload va indicato nel body.

POST /modules/

Autorizzazioni richieste: ADM_SYSTEM_DOCUMENTS.

Parametri (Body)

Nome	Tipo	Obbligatorio	Descrizione
`name`	string	Sì	Nome con cui il documento viene proposto in fase di scelta.
`filename`	string	Sì	Nome del file temporaneo restituito dall'endpoint di upload. Il contenuto deve essere un PDF.
`withContent`	boolean	Sì	Impostare `true`: indica che il documento ha un contenuto PDF associato.
`code`	string	No	Codice identificativo tecnico. Consigliato per le integrazioni: è il valore utilizzabile come `moduleCode`.
`description`	string	No	Testo descrittivo libero.
`originalFilename`	string	No	Nome del file originale, usato come nome file al download.
`idTenant`	number	No	Organizzazione proprietaria. Se omesso, viene usata l'organizzazione corrente dell'utente.
`global`	boolean	No	Se `true`, crea un documento globale (richiede l'abilitazione a gestire i documenti globali: superadmin o amministratore senza organizzazione).

Esempio di Richiesta

curl -X POST "https://sign.askme.it/api/v2/modules/" \
  -H "X-SignToken: your-api-token" \
  -H "X-SignUser: your-username" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Informativa Privacy",
    "code": "INFORMATIVA_PRIVACY",
    "description": "Informativa privacy da allegare ai contratti",
    "filename": "informativa-privacy_20250115103000.pdf",
    "originalFilename": "informativa-privacy.pdf",
    "withContent": true
  }'

Risposta (200 OK)

Campo	Tipo	Descrizione
—	number	`idModule` del Documento di sistema creato.

Errori principali

Chiave (`messageKey`)	Causa
`error.module.missingData`	`filename` mancante.
`error.module.invalidDocumentType`	Il file caricato non è un PDF.
`error.module.globalNotAllowed`	L'utente non è abilitato a gestire i documenti globali.
`error.module.organizationRequired`	Nessuna organizzazione determinabile e utente non abilitato ai globali.

Aggiornare un Documento di sistema

Aggiorna un Documento di sistema esistente. Il body è lo stesso dell'inserimento, con in più idModule obbligatorio.

PUT /modules/

Autorizzazioni richieste: ADM_SYSTEM_DOCUMENTS + permesso di modifica sul documento.

Nome	Tipo	Obbligatorio	Descrizione
`idModule`	number	Sì	ID del Documento di sistema da aggiornare.
`filename`	string	No	Solo per sostituire il PDF: nome del file temporaneo restituito dall'upload. Se omesso, il contenuto attuale viene mantenuto.

Esempio di Richiesta

curl -X PUT "https://sign.askme.it/api/v2/modules/" \
  -H "X-SignToken: your-api-token" \
  -H "X-SignUser: your-username" \
  -H "Content-Type: application/json" \
  -d '{
    "idModule": 42,
    "name": "Informativa Privacy 2025",
    "code": "INFORMATIVA_PRIVACY",
    "withContent": true
  }'

Risposta (200 OK)

true

Eliminare un Documento di sistema

Esegue l'eliminazione logica del Documento di sistema: il documento non è più proposto in fase di scelta, ma le pratiche già create che lo utilizzano non sono impattate.

DELETE /modules/{idModule}

Autorizzazioni richieste: ADM_SYSTEM_DOCUMENTS + permesso di modifica sul documento.

Esempio di Richiesta

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

Risposta (200 OK)

true

Permessi​

Riepilogo endpoint​

Elenco Documenti di sistema​

Parametri (Query) — Paginazione​

Parametri (Query) — Filtri​

Dettaglio Documento di sistema​

Parametri (URL)​

Scaricare il PDF​

Informazioni sulle pagine​

Creare un Documento di sistema​

Parametri (Body)​

Aggiornare un Documento di sistema​

Eliminare un Documento di sistema​

Permessi

Riepilogo endpoint

Elenco Documenti di sistema

Parametri (Query) — Paginazione

Parametri (Query) — Filtri

Dettaglio Documento di sistema

Parametri (URL)

Scaricare il PDF

Informazioni sulle pagine

Creare un Documento di sistema

Parametri (Body)

Aggiornare un Documento di sistema

Eliminare un Documento di sistema