Elenco documenti

In questa pagina

> risorse > documenti > api > chiamate api > Chiamate API

Chiamate API

Come effettuare chiamate API su ProcessMind

Questa guida offre esempi e best practice per usare le API di ProcessMind. Che tu voglia recuperare data, inviare informazioni o automatizzare workflow, sapere come interagire con la nostra API è fondamentale. Per la documentazione completa delle API, inclusi endpoint disponibili, metodi di autenticazione, esempi di richieste, formati di risposta e guide dettagliate all’integrazione, visita la nostra Documentazione API su GitHub.

Variabili di autenticazione

apiKey Tutte le richieste API richiedono la API key nell’header per autenticazione. Trovi la tua API key nelle impostazioni account di ProcessMind.
tenantId Alcuni endpoint richiedono il Tenant ID per definire il contesto della richiesta. Questo ID, unico per la tua azienda, si trova sempre nelle impostazioni dell’account.
datatableId Per lavorare con i dataset serve il Datatable ID per identificare la datatable d’interesse. Questo ID è disponibile nel menu impostazioni del dataset [Get Data Table ID] su ProcessMind.

Upload diretti di file

ProcessMind permette di caricare file direttamente sulle datatable tramite presigned URL. Questo metodo consente un upload sicuro senza esporre la tua API key o altri dati sensibili. Ricorda che le presigned URL sono a tempo limitato e devono essere usate subito dopo essere state ottenute. Per avere l’URL di upload diretto, esegui una richiesta GET all’endpoint. Questa URL si trova nel menu impostazioni dataset [Get upload URL] in ProcessMind. Qui puoi impostare una scadenza massima di 1 ora, 1 settimana o 1 mese.

Panoramica degli endpoint API

Method	Endpoint	Descrizione
GET	`/tenant/{tenantId}/datatable/{datatableId}/uploads/presignedurl`	Restituisce un URL temporaneo pre‑firmato per caricare un file in una datatable.
GET	`/tenant/{tenantId}/datasets`	Restituisce la lista dei dataset del tenant specificato.
GET	`/tenant/{tenantId}`	Restituisce i dettagli del tenant richiesto.
GET	`/tenant/{tenantId}/organization`	Restituisce informazioni sull’organizzazione collegata al tenant.

URL base API

Tutte le richieste API devono essere fatte all’URL base: https://api.processmind.com

Come ottenere una pre-signed Upload URL

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

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

Restituisce:
Un oggetto risposta che contiene PreSignedUploadUrl, un URL temporaneo da usare per caricare un file direttamente (solitamente tramite HTTP PUT).

Esempio (usando l’helper):

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

Come visualizzare la lista dei dataset

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

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

Restituisce:
Un array di oggetti dataset collegati al tenant.

Esempio:

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

Come recuperare dettagli del Tenant

Endpoint: GET /tenant/{tenantId}
Parametri:

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

Restituisce:
Un oggetto con dati principali del tenant (es nome, data creazione, piano).

Esempio:

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

Come ottenere dettagli della Organization

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

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

Restituisce:
Informazioni sull’organizzazione associata al tenant (es: ragione sociale, indirizzo, contatti).

Esempio:

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

Come caricare un file

La funzione uploadFile mostra come caricare un file con una pre-signed URL. Il flusso è:

Ottieni la pre-signed URL con getPresignedUploadUrl.
Effettua una richiesta PUT all’URL con il contenuto del file. La pre-signed URL autorizza l’upload direttamente sullo storage provider, senza credenziali aggiuntive.
(Facoltativo) Notifica la tua API al termine dell’upload, se richiesto dal backend.

Esempio semplificato con fetch:

async function uploadFile({ apiKey, tenantId, datatableId, file }) {
	// Step 1: Ottieni la pre-signed URL
	const uploadUrl = await getPresignedUploadUrl({ apiKey, tenantId, datatableId });
	
	// Step 2: Carica il file via PUT
	await fetch(uploadUrl, {
		method: "PUT",
		headers: {
			"Content-Type": file.type
		},
		body: file
	});
	
	// Step 3: Facoltativo: notifica la tua API
	// (dipende dal backend)
}

info

Le pre-signed URL scadono dopo un certo tempo (spesso pochi minuti). Usa l’URL subito dopo averla ottenuta.
Se un upload fallisce (es. interruzione rete), richiedi una nuova pre-signed URL prima di riprovare.
Conserva sempre sicura la tua apiKey e non esporla mai lato client (es. in front‑end pubblico).

Esempio Bash: Upload di un file

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

Scarica 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 Node.js: Upload di un file CSV locale

Carica un file CSV locale su ProcessMind tramite presigned URL.

Procedure:

Richiedi una presigned upload URL dalla API.
Leggi il file locale dal disco.
Carica il file sulla presigned URL usando HTTP PUT.

Configurazione:

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

Scarica esempio NodeJS

/**
 * Carica un file CSV locale su ProcessMind tramite un URL presigned.
 *
 * Passaggi:
 * 1. Richiedi l'URL presigned di upload dall'API.
 * 2. Leggi il file locale dal disco.
 * 3. Carica il file sull'URL tramite HTTP PUT.
 *
 * Configurazione:
 * - Inserisci la tua API key, tenantId, datatableId e filePath quando chiami uploadFileToProcessMind().
 * - L'API base URL è https://api.processmind.com
 */

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

/**
 * Carica un file nella datatable di ProcessMind tramite un URL presigned.
 * @param {string} apiKey - La tua API key per l'autenticazione.
 * @param {string} tenantId - L'identificatore del tuo tenant.
 * @param {string} datatableId - L'identificatore della tua datatable.
 * @param {string} filePath - Percorso del 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 durante il caricamento 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("Caricamento file in corso...");
        fs.readFile(filePath, async (err, data) => {
            if (err) {
                console.error("Errore nella lettura del file:", err);
                return;
            }
            try {
                const uploadRes = await fetch(uploadUrl, {
                    method: "PUT",
                    body: data
                });
                if (!uploadRes.ok) {
                    console.error("Upload non riuscito:", uploadRes.status, uploadRes.statusText);
                } else {
                    console.log("File caricato correttamente.");
                }
            } catch (uploadErr) {
                console.error("Errore durante il caricamento del file:", uploadErr);
            }
        });
    } catch (err) {
        console.error("Errore imprevisto:", err);
    }
}

// Esporta la funzione per l'utilizzo in altri moduli
module.exports = { 
	getPresignedUploadUrl,
	getDatasets,
	getTenant,
	getOrganization,
	uploadFile 
};

Esempio Python: Upload di un file CSV locale

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

Procedure:

Richiedi una presigned upload URL alla API.
Leggi il file dal disco.
Carica il file sulla presigned URL tramite HTTP PUT.

Configurazione:

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

Scarica esempio Python

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

Passaggi:
1. Richiedi un URL di upload presigned dall'API.
2. Leggi il file locale dal disco.
3. Carica il file sull'URL tramite HTTP PUT.

Configurazione:
- Modifica api_key, tenant_id, datatable_id, file_path secondo necessità.
"""

import requests

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


print("Recupero URL upload...")
api_url = "https://api.processmind.com"  # URL API di base
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 recupero URL 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("Nessun URL di upload presigned restituito.")
	exit(1)

print("Caricamento file in corso...")
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.")

info

Per la documentazione API completa, inclusi endpoint, autenticazione, esempi, formati risposta e guide di integrazione passo passo, visita la nostra API Documentation su GitHub. Se hai dubbi o ti serve supporto con l’API, contatta il nostro supporto o partecipa ai forum della community developer.