Vai al contenuto

API

Questo documento introduce le API Web per eLegere.

Le API Web di eLegere permettono ai client web di richiedere dati dalle applicazioni eLegere. I dati restituiti dipendono dal livello di accesso autorizzato dalla sessione dell'utente: se l'utente non ha l'autorizzazione specifica, l'API non restituirà alcuni dati.

Note

L'API restituisce tutte le risposte come oggetti JSON oppure come stream contenuto (content stream).

Ogni volta che la tua integrazione di terze parti richiede dati tramite l'API, gli oggetti JSON restituiti codificano i differenti tipi di dati secondo formati specifici. Consulta la reference Tipi di dato eLegere per maggiorni informazioni sui formati dei tipi di dato eLegere.

Tip

Se un metodo richiede l'Id di un'applicazione, controlla la sezione Recupero ID Applicazione per imparare come recuperare l'Id di un'applicazione.

Altri tipi di Id: devi recuperare l'Id necessario controllando il database meta-dati di eLegere.

Note

Ci sono delle limitazioni sia per le richieste URL che per i Body delle richieste POST:

  • Le stringhe URL per le richieste hanno la lunghezza massima di *2048 caratteri.
  • L'API accetta Body per le richieste fino a un massimo di 60 Mb.

Queste limitazioni sono indipendenti da eLegere.

Info

Consulta Convenzioni e Codici Stato HTTP per imparare i termini delle convenzioni e i codici stato HTTP delle risposte.

Warning

Nella descrizione degli Header, il SessionToken sta per l'access_token nel corpo della richiesta.

Authentication

Autenticazione

Il metodo permette agli utenti di autenticarsi nell'ambiente di eLegere. Il servizio restitutisce un Session token con tutto ciò che è richiesto per l'autenticazione.

Richiesta
Metodo POST
URL {base_url}/identityprovider/connect/token
Protocolli HTTPS
ContentType application/x-www-form-urlencoded
Headers Non sono richiesti headers
Return Oggetto JSON
Corpo:
1
client_id=elegereapiv1&username={email}&password={user password}&grant_type=password&scope=openid apiv1 nosession

Esempi

Crea una richiesta WEB per autorizzare l'accesso dell'utente e ottenere un Session Token per eseguire il login. Il JSON contiene il Session Token, il tempo di scadenza in millisecondi, il tipo e lo scopo.

Corpo della richiesta:

1
2
3
POST /identityprovider/connect/token
Content-Type: application/x-www-form-urlencoded
client_id=elegereapiv1&username={email}&password={user password}&grant_type=password&scope=openid apiv1 nosession

Corpo della risposta:

1
2
3
4
5
6
7
8
//HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8
{
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZC...",
    "expires_in":3600,
    "token-type": "",
    "scope": ""
}

Get Items

Dati

Il metodo interroga un'applicazione tramite WorkspaceId, ApplicationId e Session Token per ottenere i dati che contiene. Consultare Composizione dei filtri per le Query per maggiori informazioni sugli operatori e le opzioni che eLegere supporta per le query degli elementi.

Richiesta
Metodo POST
URL {base_url}/SmartExplorerApi/api/items
Protocolli HTTPS
ContentType application/json
Headers ApplicationId, SessionToken, WorkspaceId
Return Array di oggetti JSON
Corpo:
1
{"query":"$top=200&$skip=0&$orderby=DT_CREATION desc&$filter=nomeCampo Operatore_ODATA 'valore'"}

Esempi

La richiesta fornisce il Session Token per l'accesso, il formato del file di risposta, il Workspace Id (i.e. il Dominio) e l'Id dell'applicazione per permettere all'API di ottenere i dati. Il corpo contiene la stringa con la query. La query fornisce i parametri per il massimo di elementi (top) da riportare, le eccezioni e l'ordine e i campi per l'ordinamento.

Corpo della richiesta:

1
2
3
4
5
6
7
8
// POST /SmartExplorerApi/api/items
// Content-Type: application/json
// ApplicationId: "49ed-b7f3-ef6a2d3177f2"
// SessionToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c..."
// WorkspaceId: "3a98b7ec-8f6c-49ed-b7f3-ef6a2d3177f2"


{"query":"$top=200&$skip=0&$orderby=DT_CREATION desc"}

Corpo della risposta:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8

[
  {
    "Id": 1,
    "Field1": "Value 1",
    "Field2": 2,
    "Field3": true,
    "CT_ATTACHMENTS": null,
    "DT_CREATION": null,
    "DT_LAST_UPDATE": null,
    "ROW_ORDER": null,
    "TIMESTAMP": "AAAAAQ==",
    "USER_ID_CREATION": null,
    "USER_ID_LAST_UPDATE": null
  }
]

Get Items Count

Dati

Il metodo interroga l'applicazione tramite WorkspaceId, ApplicationId e Session Token per contare il numero esatto di elementi nell'applicazione che soddisfano i criteri.

Richiesta
Metodo POST
URL {base_url}/SmartExplorerApi/api/items
Protocolli HTTPS
ContentType application/json
Headers ApplicationId, SessionToken, WorkspaceId
Return Oggetto JSON
Corpo:
1
{"query":"$inlinecount=allpages"}

Esempi

La richiesta fornisce il Session Token per l'accesso, il formato del file di risposta, il Workspace Id (i.e. il Dominio) e l'Id dell'applicazione per permettere all'API di ottenere le informazioni. La risposta riporta il numero di elementi che soddisfa i criteri specificati nel corpo.

Corpo della richiesta:

1
2
3
4
5
6
7
// POST /SmartExplorerApi/api/items
// Content-Type: application/json
// ApplicationId: "49ed-b7f3-ef6a2d3177f2"
// SessionToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c..."
// WorkspaceId: "3a98b7ec-8f6c-49ed-b7f3-ef6a2d3177f2"

{ "query": "$inlinecount=allpages" }

Corpo della risposta:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8

{
  "Timestamp": 637534770772767600,
  "Items": [
    {
      "_FieldCount_": 876
    }
  ]
}

Save

Dati

Il metodo interroga un'applicazione tramite il WorkspaceId, ApplicationId e il Session Token per creare o aggiornare una riga sulla tabella dell'applicazione.

Se vuoi creare una nuova riga, inserisci un numero progressivo negativo come Id della riga.

E.g. Se salvi tre nuove righe, inserisci -1 come Id della prima riga, -2 per il secondo e così via. Il servizio assegnerà un Id appropriato sul database dopo il salvataggio.

Se vuoi aggiornare un elemento:

1) Chiama il metodo API Ottenere Elementi (Get Items) per recuperare le informazioni della riga da aggiornare.

2) Recupera il valore della chiave TIMESTAMP dall'oggetto restituito per le righe da aggiornare.

3) Chiama il metodo Salvataggio (Save); inserisci nel TIMESTAMP i valori dal passo (2) negli oggetti da salvare.

Richiesta
Metodo POST
URL {base_url}/SmartExplorerApi/api/items/save
Protocolli HTTPS
ContentType application/json
Headers ApplicationId, SessionToken, WorkspaceId
Return Array di oggetti JSON
Corpo:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "Rows": [
    {
      "Row": {
        "Name": "John",
        "Surname": "Doe",
        "Id": -1,
        "IdRow": 22,
        "TIMESTAMP": null
      },
      "Details": []
    }
  ]
}

Esempi

La richiesta contiene le informazioni della riga come oggetto: ciascun campo della riga e il valore corrispondente a una chiave dell'oggetto. La risposta fornisce un oggetto che descrive se il processo di salvataggio è andato a buon fine (i.e. la chiave "IsSaveSuccesfully"), cosa è stato salvato, creato, editato o modificato e un link alla riga di Master (i.e. la chiave "MasterRowLink" nell'oggetto).

Corpo della richiesta:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// POST /SmartExplorerApi/api/save
// Content-Type: application/json
// ApplicationId: "65abe727-93bc-47e0-a372-21f399c37e69"
// SessionToken: "eyJhbGciOiJSUzI1NiIsImtpZCI6IjM..."
// WorkspaceId: "87bab64d-f1ad-4496-b66a-25748206458c"

{
  "Rows": [
    {
      "Row": {
        "Name": "John",
        "Surname": "Doe",
        "Id": -1,
        "IdRow": 11,
        "TIMESTAMP": null
      },
      "Details": [
        {
          "RelationKey": "a5637422-8d21-48e7-a032-c9eba7713d9f",
          "Rows": [
            {
              "Address:": "via Fratelli Cuzio 42",
              "City:": "Pavia",
              "ZIP": "27100",
              "IdRow": 20,
              "Id": -1,
              "TIMESTAMP": null
            }
          ]
        }
      ]
    }
  ]
}

Corpo della risposta:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8

{
  "IsSaveSuccesfully": true,
  "ReturnStates": [],
  "ReturnData": {
    "PrimaryKeyData": {
      "-1": {
        "newKeys": {
          "7acaf2c9-aa5b-424b-88f1-018d30d867e9": "12"
        }
      }
    }
  },

  "MasterToRecalculate": [],
  "CreatedItems": 1,
  "UpdatedItems": 0,
  "DeletedItems": 0,
  "LockedItems": 0,
  "MasterRowLink": "https://...",
  "RowIdentifier": "IdRow",
  "StorageName": "sStorageExample",
  "SavedItems": null
}

Delete

Dati

Il metodo interroga un'applicazione tramite il WorkspaceId, ApplicationId e il Session Token per cancellare una riga dalla tabella dell'applicazione.

Cancella una riga inserendo il suo Id nella chiave Id dell'oggetto e il suo Timestamp nella chiave TIMESTAMP.

Il metodo cancella riga con quel particolare Id e Timestamp.

Richiesta
Metodo POST
URL {base_url}/SmartExplorerApi/api/items/delete
Protocolli HTTPS
ContentType application/json
Headers ApplicationId, SessionToken, WorkspaceId
Return Array di oggetti JSON
Corpo:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
[
  {
    "Rows": [
      {
        "Row": {
          "Id": 1,
          "TIMESTAMP": 638333257746117400
        },
        "Details": []
      }
    ]
  }
]

Esempi

La richiesta contiene l'Id della riga e il suo Timestamp. Questi due valori sono essenziali per identificare quale riga è da cancellare.

Dopo la cancellazione, l'oggetto di risposta riporta se l'operaziona ha avuto successo tramite il valore della chiave IsSaveSuccesfully.

Corpo della richiesta:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
// POST /SmartExplorerApi/api/delete
// Content-Type: application/json
// ApplicationId: "65abe727-93bc-47e0-a372-21f399c37e69"
// SessionToken: "eyJhbGciOiJSUzI1NiIsImtpZCI6IjM..."
// WorkspaceId: "87bab64d-f1ad-4496-b66a-25748206458c"

{
  "Rows": [
    {
      "Row": {
        "Id": 55,
        "TIMESTAMP": 638333257746117400
      },
      "Details": []
    }
  ]
}

Corpo della risposta:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8

{
    "IsSaveSuccesfully": true,
    "ReturnStates": [],
    "MasterToRecalculate": [],
    "CreatedItems": 0,
    "UpdatedItems": 0,
    "DeletedItems": 1,
    "LockedItems": 0,
    "MasterRowLink": "https://...",
    "RowIdentifier": "IdRow",
    "StorageName": "sStorageExample",
    "SavedItems": null
}

Get Attachments List

Dati

Il metodo recupera la lista degli allegati di una riga in un'applicazione iniziando dall'Id della riga e l'Id della cartella allegati.

Note

Puoi ottenere l'Id della riga tramite il metodo Ottenere Elementi (Get Items). Sostituiscilo nell'URL per identificare la lista degli allegati della riga.

Info

L'ultima parte dell'URL and FolderId eq FOLDERID è opzionale. Hai bisogno del FOLDERID solo per recuperare la lista di allegati se annidati nell'alberto cartelle allegati della riga. Consultare Composizione dei filtri per le Query per maggiori informazioni sugli operatori e le opzioni che eLegere supporta per le query degli elementi.

Richiesta
Metodo GET
URL {base_url}/SmartExplorerApi/api/attachments?$filter=ParentId eq ROWID and FolderId eq FOLDERID
Protocolli HTTPS
ContentType application/json
Headers ApplicationId, SessionToken, WorkspaceId
Return Array di oggetti JSON

Esempi

Il metodo recupera la lista degli allegati di una riga partendo dall'Id della riga. L'array dell'oggetto contiene un oggetto per ciascun allegato. Ciascun oggetto specifica le informazioni di ciascun allegato.

Corpo della richiesta:

1
2
3
4
5
GET /SmartExplorerApi/api/attachments?$filter=ParentId eq 1 and FolderId eq 4
Content-Type: application/json
ApplicationId: "49ed-b7f3-ef6a2d3177f2"
SessionToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c..."
WorkspaceId: "3a98b7ec-8f6c-49ed-b7f3-ef6a2d3177f2"

Corpo della risposta:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8

[
  {
    "Description": "file.xml",
    "DT_CREATION": 20220713125300,
    "DT_LAST_UPDATE": null,
    "Id": 1242,
    "FolderId": null,
    "IsFolder": false,
    "Name": "file.xml",
    "ParentId": 1,
    "TypeImage": "text/xml",
    "USER_ID_CREATION": "vesenda@elegere.com",
    "USER_ID_LAST_UPDATE": 20230405133245
  }
]

Download Attachment

Dati

Il metodo accede tramite Session Token e recupera l'allegato desiderato tramite il suo Id sul database.

Note

Puoi scaricare sia allegati singoli sia cartelle. Se la richiesta punta a una cartella, l'API restituisce un archivio .zip con tutti gli allegati della cartella.

Note

Nella richiesta, rk è la parent key della relazione Master-Dettaglio. rk è opzionale nella richiesta. Devi specificare rk nella richiesta se e solo se scarichi un allegato da un riga di Dettaglio. Altrimenti, la richiesta si riferisce solo alla riga della tabella di Master.

Richiesta
Metodo POST
URL {base_url}/SmartExplorerApi/api/attachments/download
Protocolli HTTPS
ContentType application/json
Headers ApplicationId, SessionToken, WorkspaceId
Return Stream File

Esempi

Il metodo recupera un allegato partendo dall'Id della riga. Nell'esempio sotto, il metodo recupera un file XML allegato a una riga.

Corpo della richiesta:

1
2
3
4
5
6
7
// GET /SmartExplorerApi/api/attachment/download
// Content-Type: application/json
// ApplicationId: "49ed-b7f3-ef6a2d3177f2"
// SessionToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c..."
// WorkspaceId: "3a98b7ec-8f6c-49ed-b7f3-ef6a2d3177f2"

{ "ids": [1, 2], "rk": "" }

Corpo della risposta:

1
2
3
4
5
// HTTP/1.1 200 OK
// Content-Type: application/xml;


Content-Disposition: attachment; filename="file.xml"

Run Action

Dati

Il metodo lancia una delle Custom Action realizzate per l'applicazione scelta. Il metodo identifica l'azione da lanciare tramite l'actionId dell'azione.

Richiesta
Metodo POST
URL {base_url}/SmartExplorerApi/api/action/run
Protocolli HTTPS
ContentType application/json
Headers ApplicationId, SessionToken, WorkspaceId
Return Oggetto JSON
Corpo:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "actionId": "GUID",
  "parametersMap": [
    {
      "Name": "ProcedureName",
      "Value": "name of stored procedure"
    },
    {
      "Name": "Parameters",
      "Value": [
        {
          "key": "p1",
          "value": "p1 value"
        },
        {
          "key": "p2",
          "value": "p2 value"
        },
        {
          "key": "pn",
          "value": "pn value"
        }
      ]
    }
  ]
}

Esempi

Il metodo esegue la Custom Action specificata e restituisce un oggetto che riporta il risultato dell'azione. Se la chiave IsSuccessful ha valore true, la Custom Action ha funzionato correttamente.

Corpo della richiesta:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
// POST /SmartExplorerApi/api/action/run
// Content-Type: application/json
// ApplicationId: "49ed-b7f3-ef6a2d3177f2"
// SessionToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c..."
// WorkspaceId: "b5b1a6ae6b314c4593c112d8d079d6d0"

{
  "actionId": "710333fc-7098-48e4-bb94-008d260a514f",
  "parametersMap": [
    {
      "Name": "Parameters",
      "Value": [
        {
          "key": "Quantity",
          "value": "10"
        }
      ]
    }
  ]
}

Corpo della risposta:

1
2
3
4
5
6
7
8
9
// HTTP/1.1 200 OK
// Content-Type: application/xml;

{
  "Message": "Operation success",
  "IsSuccessful": true,
  "Result": "",
  "IsAsync": false
}

Send Email

Utilità

Il metodo interroga il servizio per inviare una mail contenente il destinatario, l'oggetto, il corpo testo e providerId (opzionale) nella richiesta. Il providerId è un GUID che specifica quale provider email usare dalle impostazioni provider email dell'installazione di eLegere. Se la richiesta non contiene nessun providerId, la API Inviare Email usa il providerId predefinito di eLegere configurato durante l'installazione.

Richiesta
Metodo POST
URL {base_url}/ewebaggregator/api/v1/email/queue
Protocolli HTTPS
ContentType application/json
Headers Authorization, WorkspaceId
Return Nessun oggetto restituito
Corpo:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// POST {base_url}/ewebaggregator/api/v1/email/queue

// Content-Type: application/json
// WorkspaceId: [WORKSPACEID]
// Authorization: Bearer [SESSIONTOKEN]

{
  "providerId": "string",
  "to": ["string"],
  "subject": "string",
  "body": "string"
}

Esempi

Il servizio riceve la richiesta con le informazioni sui destinatari, l'oggetto e il corpo del testo. Nell'esempio, la richiesta non contiene il providerId: userà il provider predefinito dell'installazione di eLegere.

Corpo della richiesta:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// POST myinstallation.elegereapp.com/ewebaggregator/api/v1/email/queue

// Content-Type: application/json
// WorkspaceId: "b5b1a6ae6b314c4593c112d8d079d6d0"
// Authorization: Bearer "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c..."

{
  "to": ["j.doe@vesenda.com", "d.doe@vesenda.com"],
  "subject": "Send Email API Example",
  "body": "Messages sent with Send Email API."
}

Corpo della risposta:

1
// Corpo risposta vuoto