Le API di TotalGest (v2)

Documentazione API: https://vostro-nome.totalgest.cloud/docs/api/

Le API di TotalGest permettono ad altri programmi di leggere e scrivere dati in TotalGest in modo automatico.

Con le API potete ad esempio collegare il vostro shop online, sincronizzare contatti e articoli con un altro gestionale, creare fatture da un'applicazione esterna o scaricare i PDF dei documenti. Questa pagina è un'introduzione: i dettagli di ogni chiamata si trovano nella documentazione tecnica online.

Le informazioni in questa pagina fanno riferimento alla versione 4.3.0 con le API v2, disponibili dalla versione 4.2.0. La documentazione è pensata per sviluppatori e programmatori.

(1) La documentazione online

La documentazione completa è disponibile all'indirizzo https://vostro-nome.totalgest.cloud/docs/api/ (sostituite vostro-nome con il nome della vostra installazione). Potete consultare l'esempio sulla demo: demo.totalgest.cloud/docs/api. È raggiungibile anche dal menu utente in alto a destra, voce Documentazione API.

(1) Elenco delle risorse disponibili (contatti, articoli, offerte, fatture, ...), con la ricerca
(2) Download della specifica OpenAPI, da importare ad esempio in Postman o in un generatore di codice
(3) Metodo ed indirizzo della chiamata
(4) Parametri da inviare; a destra trovate esempi di richiesta e di risposta

(2) Indirizzo di base

Tutte le chiamate partono dall'indirizzo della vostra installazione seguito da /ws:

https://vostro-nome.totalgest.cloud/ws

(3) Autenticazione e token

Ogni chiamata deve essere autenticata con un utente di TotalGest e un suo token. Utente e token si possono inviare in due modi:

Basic Auth: nome utente e token nell'intestazione HTTP (al posto della password si usa il token).
Parametri nell'indirizzo: username e token aggiunti all'indirizzo della chiamata.

In entrambi i casi si usano sempre nome utente e token. L'uso della password dell'utente al posto del token è deprecato: anche se potrebbe ancora funzionare, non usatelo nelle nuove integrazioni.

I token si gestiscono in Impostazioni > Impostazioni sistema > Token:

(1) Crea un nuovo token
(2) Il token da usare nelle chiamate
(3) L'utente a cui è collegato il token e se il token è abilitato
(4) Eventuale limitazione dell'host o indirizzo IP da cui il token può essere usato

Un token dà accesso ai dati come l'utente a cui è collegato: trattatelo come una password, non pubblicatelo e non inviatelo per email. Per le integrazioni è consigliabile usare un utente dedicato, inserito in un gruppo con i soli permessi necessari. Se un token non serve più, disabilitatelo o eliminatelo.

Per verificare che utente e token funzionino potete usare GET /ping, che controlla il login e che il server sia raggiungibile.

(4) Le risorse disponibili

Risorsa	Contenuto	Operazioni principali
customer	Contatti (clienti, fornitori, produttori)	elenco, crea, leggi, modifica, elimina
product	Articoli	elenco, crea, leggi, modifica, elimina, articoli eliminati, stock
service	Servizi	elenco, crea, leggi, modifica, elimina
abo	Abbonamenti	elenco, crea, leggi, modifica, elimina
estimate	Offerte	elenco, crea, leggi, modifica, elimina, clona, PDF
order	Ordini	elenco, crea, leggi, modifica, elimina, PDF
deliverynote	Bollettini di consegna	elenco, crea, leggi, modifica, elimina, PDF
invoice	Fatture	elenco, crea, leggi, modifica, elimina, PDF
creditnote	Note di credito	elenco, leggi, PDF
cdeliverynote	Bollettini d'entrata fornitore	elenco, crea, leggi
techint	Rapporti di lavoro	elenco, crea, leggi, modifica, elimina, PDF
fidelitycard	Carte fedeltà	registrazione, associazione e ricerca di carte e clienti
shop	Shop online	sincronizzazione prodotti e ordini
user	Utenti	leggi
login	Login	ping (verifica login e server)

(5) La risposta

Tutte le risposte sono in formato JSON e hanno la stessa struttura:

error: true se la chiamata non è andata a buon fine
operation: l'operazione richiesta
msg: eventuali avvisi o messaggi di errore
server-time: ora del server (timestamp Unix)
requestsPerHour: richieste effettuate nell'ultima ora / massimo consentito
result: i dati richiesti

(6) Esempio: cercare dei documenti

Gli elenchi si ottengono con POST /<risorsa>/list. Nel corpo della richiesta si invia un array che combina filtri (field, operator, value) e opzioni (limit, offset, ordering, relations). Ad esempio, le prime 10 fatture create dopo il 31 gennaio 2024:

curl -X POST "https://vostro-nome.totalgest.cloud/ws/invoice/list?username=UTENTE&token=TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"field": "createdAt", "operator": ">", "value": "2024-01-31 10:00:00"}, {"limit": 10}]'

Gli operatori disponibili sono descritti nella documentazione online (ad esempio =, !=, >, LIKE%, IN, BETWEEN, IS NULL).

Per collegare un sito WordPress / WooCommerce vedi anche il libro Woocommerce su WordPress. Per assistenza sull'integrazione potete aprire un ticket.