Elenco Documenti

In Questa Pagina

API calls

Effettuare chiamate API a ProcessMind

Questa guida offre esempi e best practice per usare le API di ProcessMind. Che tu debba recuperare dati, inviare info o automatizzare workflow, sapere come interagire con la nostra API è essenziale.

Variabili di autenticazione

apiKey Per tutte le richieste API, devi inserire la tua API key negli header della richiesta per l’autenticazione. Puoi ottenere la API key nelle impostazioni del tuo account ProcessMind.
tenantId Alcuni endpoint API richiedono un Tenant ID per specificare il contesto della richiesta. Questo ID è unico per la tua organizzazione e si trova nelle impostazioni dell’account.
datatableId Quando lavori con dataset, devi fornire il Datatable ID per identificare la datatable con cui interagisci. Questo ID è disponibile nel menu impostazioni del dataset [Get Data Table ID] in ProcessMind.

Caricamento diretto dei file

ProcessMind permette il caricamento diretto di file nelle datatable tramite presigned URL. Questo metodo ti consente di caricare file in modo sicuro senza esporre la tua API key o altre informazioni sensibili. Ricorda che i presigned URL hanno una durata limitata e vanno utilizzati subito dopo il recupero. Per ottenere l’URL di caricamento diretto è necessario fare una richiesta GET all’endpoint. Puoi ottenere questo URL nel menu impostazioni dataset [Get upload URL] in ProcessMind. Qui puoi impostare una durata massima tra 1 ora, 1 settimana o 1 mese.

Panoramica endpoint

Method	Endpoint	Descrizione
GET	`/tenant/{tenantId}/datatable/ {datatableId}/uploads/presignedurl`	Restituisce una URL temporanea pre-signed per caricare un file su una datatable.
GET	`/tenant/{tenantId}/datasets`	Restituisce l’elenco dei dataset per il tenant dato.
GET	`/tenant/{tenantId}`	Restituisce i dettagli del tenant indicato.
GET	`/tenant/{tenantId}/organization`	Restituisce informazioni sull’organizzazione del tenant.

Base URL

Tutte le richieste API vanno inviate al seguente base URL: https://api.processmind.com

Ottenere un Pre‑signed Upload URL

Endpoint: GET /tenant/{tenantId}/datatable/{datatableId}/uploads/presignedurl Parametri:

tenantId – ID del tenant (string).
datatableId – ID della datatable su cui vuoi caricare (string).
apiKey – La tua API key (string).

Risposta: Un oggetto response che contiene PreSignedUploadUrl, un URL temporaneo da usare per caricare un file direttamente (di solito tramite HTTP PUT).

Esempio (con helper):

const presignedUrl = await getPresignedUploadUrl({
  apiKey,
  tenantId: 'tenant-123',
  datatableId: 'table-456'
});
console.log(presignedUrl); // es. https://s3.amazonaws.com/…?X-Amz-Signature=…

Lista dei Dataset

Endpoint: GET /tenant/{tenantId}/datasets Parametri:

tenantId – ID del tenant.
apiKey – La tua API key.

Risposta: Un array di oggetti dataset del tenant.

Esempio:

const datasets = await getDatasets({
  apiKey,
  tenantId: 'tenant-123'
});
console.log(datasets);

Recupero dettagli Tenant

Endpoint: GET /tenant/{tenantId} Parametri:

tenantId – ID del tenant.
apiKey – La tua API key.

Risposta: Oggetto con dati sul tenant come nome, data creazione e piano.

Esempio:

const tenantInfo = await getTenant({
  apiKey,
  tenantId: 'tenant-123'
});
console.log(tenantInfo);

Recupero dettagli Organization

Endpoint: GET /tenant/{tenantId}/organization Parametri:

tenantId – ID del tenant.
apiKey – La tua API key.

Risposta: Informazioni sulla organization collegata al tenant (es. nome azienda, indirizzo, contatti).

Esempio:

const org = await getOrganization({
  apiKey,
  tenantId: 'tenant-123'
});
console.log(org);

Caricamento di un file

La funzione uploadFile mostra come caricare un file usando la pre-signed URL. Il flusso generale:

Ottieni la pre-signed URL tramite la funzione getPresignedUploadUrl.
Fai una richiesta PUT a quella URL con il contenuto del file. La pre-signed URL consente il caricamento diretto sullo storage provider, senza altre credenziali.
(Facoltativo) Notifica alla tua API che il caricamento è stato completato, se richiesto dal backend.

Esempio semplificato con fetch per caricare un file:

async function uploadFile({ apiKey, tenantId, datatableId, file }) {
  // Step 1: Obtain a pre-signed URL
  const uploadUrl = await getPresignedUploadUrl({ apiKey, tenantId, datatableId });
  
  // Step 2: Upload the file via PUT
  await fetch(uploadUrl, {
    method: 'PUT',
    headers: {
      'Content-Type': file.type
    },
    body: file
  });
  
  // Step 3: Optionally notify your API of completion
  // (depends on your backend implementation)
}

info

Le pre-signed URL scadono dopo poco tempo (spesso pochi minuti). Usa la URL subito dopo averla ottenuta.
Se il caricamento fallisce (es. problemi di rete), richiedi una nuova pre-signed URL prima di riprovare.
Conserva sempre la tua apiKey in modo sicuro e non esporla lato client (es. in un front-end pubblico).

Esempio BASH

Script Bash minimale per caricare un file su ProcessMind tramite due chiamate curl, con placeholder per tutti i valori

Download Esempio BASH

#!/bin/bash
# Script Bash minimale per caricare file su ProcessMind tramite due chiamate curl con placeholder per tutti i valori

# Sostituisci i seguenti placeholder con i tuoi valori reali:
# <API_KEY>, <TENANT_ID>, <DATATABLE_ID>, <FILE_PATH>

curl -s -H "x-api-key: <API_KEY>" \
    "https://api.processmind.com/tenant/<TENANT_ID>/datatable/<DATATABLE_ID>/uploads/presignedurl" \
    | grep -oP '"PreSignedUploadUrl"\s*:\s*"\K[^"]+' \
    | xargs -I {} curl -s -X PUT --upload-file "<FILE_PATH>" "{}"

Esempio NodeJS

Carica un file CSV locale su ProcessMind tramite una URL presigned.

Step:

Recupera una URL di upload presigned tramite API.
Legge il file locale dal disco.
Carica il file alla URL presigned con HTTP PUT.

Configurazione:

Inserisci API key, tenantId, datatableId e filePath quando chiami uploadFileToProcessMind().
La base URL API è https://api.processmind.com

Download Esempio NodeJS

/**
 * Carica un file CSV locale su ProcessMind tramite URL presigned.
 *
 * Step:
 * 1. Recupera una URL di upload presigned dall'API.
 * 2. Legge il file locale da disco.
 * 3. Carica il file sulla URL presigned tramite HTTP PUT.
 *
 * Configurazione:
 * - Fornisci API key, tenantId, datatableId e filePath quando usi uploadFileToProcessMind().
 * - L'API base URL è https://api.processmind.com
 */

const fs = require("node:fs");

/**
 * Carica un file in una datatable ProcessMind tramite URL presigned.
 * @param {string} apiKey - API key per autenticazione.
 * @param {string} tenantId - ID tenant.
 * @param {string} datatableId - ID datatable.
 * @param {string} filePath - Percorso file da caricare.
 */

async function getApi({path, apiKey, apiUrl = "https://api.processmind.com"}) {
	try {
        const response = await fetch(`${apiUrl}${path}`, {
            method: "GET",
            headers: {
                "x-api-key": apiKey
            }
        });
        const body = await response.json();
        if (!response.ok) {
            console.error(`Errore dall'API: ${response.status}, ${response.statusText}: ${body.message}`);
            return;
        }
        return body;
    } catch (err) {
        console.error("Errore imprevisto:", err);
    }
}

async function getPresignedUploadUrl({apiKey, tenantId, datatableId, apiUrl = "https://api.processmind.com"}) {
	return (await getApi({apiKey, path: `/tenant/${tenantId}/datatable/${datatableId}/uploads/presignedurl`, apiUrl})).PreSignedUploadUrl;
}

async function getDatasets({apiKey, tenantId, apiUrl = "https://api.processmind.com"}) {
	return await getApi({apiKey, path: `/tenant/${tenantId}/datasets`, apiUrl});
}

async function getTenant({apiKey, tenantId, apiUrl = "https://api.processmind.com"}) {
	return await getApi({apiKey, path: `/tenant/${tenantId}`, apiUrl});
}

async function getOrganization({apiKey, tenantId, apiUrl = "https://api.processmind.com"}) {
	return await getApi({apiKey, path: `/tenant/${tenantId}/organization`, apiUrl});
}

async function uploadFile({apiKey, tenantId, datatableId, filePath, apiUrl = "https://api.processmind.com"}) {
    try {
        const uploadUrl = await getPresignedUploadUrl({apiKey, tenantId, datatableId, apiUrl});

		console.log("Upload file in corso...");
        fs.readFile(filePath, async (err, data) => {
            if (err) {
                console.error("Errore lettura file:", err);
                return;
            }
            try {
                const uploadRes = await fetch(uploadUrl, {
                    method: "PUT",
                    body: data
                });
                if (!uploadRes.ok) {
                    console.error("Caricamento fallito:", uploadRes.status, uploadRes.statusText);
                } else {
                    console.log("File caricato con successo.");
                }
            } catch (uploadErr) {
                console.error("Errore durante il caricamento:", uploadErr);
            }
        });
    } catch (err) {
        console.error("Errore imprevisto:", err);
    }
}

// Export delle funzioni per uso in altri moduli
module.exports = { 
	getPresignedUploadUrl,
	getDatasets,
	getTenant,
	getOrganization,
	uploadFile 
};

Esempio Python

Carica un file CSV locale su una API remota usando una URL presigned.

Step:

Recupera una URL di upload presigned tramite API.
Legge il file locale dal disco.
Carica il file alla URL presigned tramite HTTP PUT.

Configurazione:

Aggiorna api_key, tenant_id, datatable_id, file_path secondo necessità.

Download Esempio Python

"""
Carica un file CSV locale su una API remota tramite URL presigned.

Step:
1. Recupera la URL di upload presigned dall’API.
2. Legge il file locale dal disco.
3. Carica il file alla URL presigned tramite HTTP PUT.

Configurazione:
- Aggiorna api_key, tenant_id, datatable_id, file_path secondo le tue necessità.
"""

import requests

# === Configuration ===
api_key = ""  # API key per autenticazione
tenant_id = ""  # Identificativo tenant
datatable_id = ""  # Identificativo datatable
file_path = ""  # Percorso del file da caricare


print("Recupero URL di upload...")
api_url = "https://api.processmind.com"  # Base API URL
presign_url = f"{api_url}/tenant/{tenant_id}/datatable/{datatable_id}/uploads/presignedurl"
presign_res = requests.get(presign_url, headers={"x-api-key": api_key})
if not presign_res.ok:
	print(f"Errore durante il recupero della URL di upload: {presign_res.status_code}, {presign_res.reason}: {presign_res.text}")
	exit(1)

presign_body = presign_res.json()
upload_url = presign_body.get("PreSignedUploadUrl")
if not upload_url:
	print("URL di upload presigned non restituita.")
	exit(1)

print("Caricamento file...")
with open(file_path, "rb") as f:
	upload_res = requests.put(upload_url, data=f)
if not upload_res.ok:
	print(f"Caricamento fallito: {upload_res.status_code}, {upload_res.reason}")
else:
	print("File caricato con successo.")