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 fineoperation: l'operazione richiestamsg: eventuali avvisi o messaggi di erroreserver-time: ora del server (timestamp Unix)requestsPerHour: richieste effettuate nell'ultima ora / massimo consentitoresult: i dati richiesti (6) Esempio: cercare dei documenti Gli elenchi si ottengono con POST //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.