Guida alla configurazione API
Con Application Programming Interface (in acronimo API, in italiano interfaccia di programmazione di un'applicazione), in informatica, si indica ogni insieme di procedure disponibili al programmatore, di solito raggruppate a formare un set di strumenti specifici per l'espletamento di un determinato compito all'interno di un certo programma. Wikipedia
Il gestionale possiede un sistema di API basilare che permette di ottenere i dati registrati al suo interno attraverso un'interfaccia comune, oltre che di creare e aggiornare le informazioni dei vari record salvati.
Metodo di accesso
L'accesso all'API viene garantito esclusivamente tramite il token personale di accesso dell'utente, individuabile nella sezione dedicata alle informazioni sull'account.
Cliccando sulla sezione evidenziata in rosso, si apre una pagina dedicata alla visualizzazione delle informazioni personali dell'utente e che permette la modifica della password e della foto profilo, oltre che la visualizzazione del token per l'API.
Gestione degli accessi
E' disponibile un sistema di gestione degli accessi basilare per l'amministratore del gestionale, che può abilitare l'accesso degli utenti attraverso il modulo Utenti e permessi.
Non è al momento disponibile un sistema di permessi per il sistema API, e pertanto chiunque possegga un token può accedere a tutte le informazioni che l'API rende disponibile.
Modalità di utilizzo
Ogni richiesta di comunicazione con l'API deve essere composta di una chiave di accesso e di un'operazione richiesta, e deve essere formattata secondo il formato JSON.
In base al tipo di risorsa che si desidera richiedere, sono disponibili quattro metodi HTTP per la comunicazione:
- GET, dedicato alle richieste di informazioni (Retrieve)
- POST, dedicato alle richieste di creazione (Create)
- PUT, dedicato alle richieste di modifica (Update)
- DELETE, dedicato alle richieste di eliminazione (Delete)
Maggiori informazioni sulle relative risorse disponibili sono presenti nelle prossime sezioni, oltre che all'interno della tabella zz_api_resources del gestionale.
Retrieve
Le operazioni di retrieve permettono di ottenere le informazioni registrate nel gestionale, e solitamente non influenzano in alcun modo lo stato del software e i dati interni.
In base alle capacità del server in cui il gestionale è installato, è possibile un rallentamento del server in caso di molteplici richieste contemporanee all'API.
Standard di funzionamento
Considerando la potenziale quantità delle informazioni restituite, il sistema API del gestionale restituisce le informazioni richieste presentando una paginazione di default di 200 record (valore modificabile in impostazioni).
Richiesta standard per la comunicazione con l'API in modalità retrieve:
curl "http://<indirizzo_osm>/api/?token=<token_tecnico>&version=v1&resource=<resource>"
Parametri
| Nome | Descrizione | Esempio | Tipo |
|---|---|---|---|
token |
Token di accesso di un utente | string | |
resource |
Risorsa richiesta | string | |
page |
Intero compreso tra 0 e il valore del campo pages restituito dalla prima richiesta | page=1 | integer |
display |
Array che indica un filtro sui campi da restituire alla richiesta | display=[id, name] | array |
filter |
Array composto che indica dei filtri da applicare sui contenuti dei risultati alla richiesta | filter[ragione_sociale]=[Mario Rossi]&filter[telefono]=[0429%] | array |
order |
Lista di campi che indicano l'ordinamento da impostare sulla richiesta | order=[descrizione|desc] | array |
upd |
Chiede di ottenere i record modificati dopo la data specificata | upd=2023-01-01 23:45:00 | date |
crd |
Chiede di ottenere i record creati dopo la data specificata | crd=2023-01-01 23:45:00 | date |
Il rispetto delle opzioni sopra indicate, come per la gestione della paginazione automatica, è riservato alla singola risorsa: in casi specifici e documentati, la risorsa potrebbe ignorare le opzioni indicate a favore di un comportamento personalizzato.
Create
La funzione Create è una funzione utilizzata per effettuare una richiesta di tipo POST ad un'API, utilizzando un linguaggio di programmazione. La richiesta POST permette di inviare dati ad un server, che poi li processerà e restituirà una risposta.
La funzione post può includere parametri come l'URL dell'API da chiamare, i dati da inviare al server e le eventuali informazioni di autenticazione o autorizzazione. La risposta ricevuta può essere gestita nel codice per eseguire ulteriori operazioni o restituire risultati all'utente.
Update
La funzione Update è una funzione che consente di aggiornare o modificare un elemento sul server. Il metodo "put" viene utilizzato per sostituire completamente le informazioni di un elemento esistente con nuovi dati forniti dal chiamante. Il chiamante deve specificare l'ID dell'elemento da modificare e fornire i nuovi dati per completare l'operazione di sostituzione.
Delete
La funzione delete è un'operazione che permette di rimuovere o eliminare i dati o le informazioni presenti in un server. Questa operazione può essere eseguita attraverso una richiesta utilizzando un metodo HTTP DELETE. Tale richiesta deve essere indirizzata all'URL corretto, specificando gli eventuali parametri necessari per identificare l'elemento da eliminare.
Risorse disponibili
Anagrafiche
Richiesta elenco dei clienti
curl "http://<indirizzo_osm>/api/?token=<token_tecnico>&version=v1&resource=clienti"
Risposta
{
"records": {
"0": {
"idanagrafica": 2,
"codice": "00000002",
"ragione_sociale": "Cliente",
"tipo": "Privato",
"piva": "05024030287",
"codice_fiscale": "05024030287",
"capitale_sociale": "",
"data_nascita": null,
"luogo_nascita": "",
"sesso": "",
"indirizzo": "Via Roma",
"indirizzo2": "",
"citta": "Este",
"cap": "35042",
"provincia": "",
"km": "0.00",
"id_nazione": 82,
"telefono": "",
"fax": "",
"cellulare": "",
"email": "",
"pec": "",
"sitoweb": "",
"note": "",
"codiceri": "",
"codicerea": "",
"riferimento_amministrazione": "",
"appoggiobancario": "",
"filiale": "",
"codiceiban": "",
"bic": "",
"diciturafissafattura": "",
"idpagamento_vendite": 0,
"idpagamento_acquisti": 0,
"id_piano_sconto_vendite": 0,
"id_piano_sconto_acquisti": 0,
"id_listino": 0,
"idiva_vendite": null,
"idiva_acquisti": null,
"id_ritenuta_acconto_vendite": 0,
"id_ritenuta_acconto_acquisti": 0,
"idsede_fatturazione": 0,
"idconto_cliente": 119,
"idbanca_vendite": null,
"idbanca_acquisti": null,
"idconto_fornitore": 0,
"id_settore": 0,
"marche": "",
"dipendenti": 0,
"macchine": 0,
"idagente": 0,
"idrelazione": 0,
"id_provenienza": null,
"agentemaster": 0,
"idzona": 0,
"foro_competenza": "",
"nome": "",
"cognome": "",
"iscrizione_tribunale": "",
"n_alboartigiani": "",
"colore": "#ffffff",
"created_at": "2023-09-19 09:27:58",
"updated_at": "2023-09-19 09:28:25",
"idtipointervento_default": null,
"id_dichiarazione_intento_default": null,
"provvigione_default": "0.000000",
"gaddress": null,
"lat": null,
"lng": null,
"deleted_at": null,
"codice_destinatario": "",
"split_payment": 0,
"enable_newsletter": 1,
"nazione": "Italia"
},
},
"total-count": 1,
"pages": 1,
"status": 200,
"message": "OK"
}
Richiesta elenco delle anagrafiche
curl "http://<indirizzo_osm>/api/?token=<token_tecnico>&version=v1&resource=anagrafiche"
Risposta
{
"records": {
"0": {
"idanagrafica": 1,
"codice": "00000001",
"ragione_sociale": "Admin spa",
"tipo": "",
"piva": "05024030289",
"codice_fiscale": "05024030289",
"capitale_sociale": "",
"data_nascita": null,
"luogo_nascita": "",
"sesso": "",
"indirizzo": "Via Rovigo, 51",
"indirizzo2": "",
"citta": "Este",
"cap": "35042",
"provincia": "",
"km": "0.00",
"id_nazione": 82,
"telefono": "",
"fax": "",
"cellulare": "",
"email": "",
"pec": "",
"sitoweb": "",
"note": "",
"codiceri": "",
"codicerea": "",
"riferimento_amministrazione": "",
"appoggiobancario": "",
"filiale": "",
"codiceiban": "",
"bic": "",
"diciturafissafattura": "",
"idpagamento_vendite": null,
"idpagamento_acquisti": null,
"id_piano_sconto_vendite": null,
"id_piano_sconto_acquisti": null,
"id_listino": 0,
"idiva_vendite": null,
"idiva_acquisti": null,
"id_ritenuta_acconto_vendite": null,
"id_ritenuta_acconto_acquisti": null,
"idsede_fatturazione": 0,
"idconto_cliente": 0,
"idbanca_vendite": null,
"idbanca_acquisti": null,
"idconto_fornitore": 0,
"id_settore": 0,
"marche": "",
"dipendenti": 0,
"macchine": 0,
"idagente": 0,
"idrelazione": 0,
"id_provenienza": null,
"agentemaster": 0,
"idzona": 0,
"foro_competenza": "",
"nome": "",
"cognome": "",
"iscrizione_tribunale": "",
"n_alboartigiani": "",
"colore": "",
"created_at": "2023-09-19 09:26:54",
"updated_at": "2023-09-19 09:27:39",
"idtipointervento_default": null,
"id_dichiarazione_intento_default": null,
"provvigione_default": "0.000000",
"gaddress": null,
"lat": null,
"lng": null,
"deleted_at": null,
"codice_destinatario": "",
"split_payment": 0,
"enable_newsletter": 1,
"nazione": "Italia"
},
"1": {
[...]
},
"2": {
[...]
},
"3": {
[...]
}
},
"total-count": 4,
"pages": 1,
"status": 200,
"message": "OK"
}
Aggiunta di una anagrafica
curl -X POST -d '{
"token": "<token_tecnico>",
"resource": "anagrafica",
"data": {
"ragione_sociale": "Mario Rossi",
"id_tipo": "1"
}
}' "http://<indirizzo_osm>/api/"
Risposta
{
"status": 200,
"message": "OK"
}
Eliminazione di una anagrafica
curl -X DELETE -d '{
"token": "<token_tecnico>",
"resource": "anagrafica",
"id": "13"
}' "http://<indirizzo_osm>/api/"
Risposta
{
"status": 200,
"message": "OK"
}
Modifica di un'anagrafica
curl -X PUT -d '{
"token": "<token_tecnico>",
"resource": "anagrafica",
"data": {
"id": 2,
"ragione_sociale": "Franco",
"indirizzo": "Via Rovigo, 51",
"citta": "Este"
}
}' "http://<indirizzo_osm>/api/"
Risposta
{
"status": 200,
"message": "OK"
}
Articoli
Richiesta elenco degli articoli a magazzino
curl "http://<indirizzo_osm>/api/?token=<token_tecnico>&version=v1&resource=articoli"
Risposta
[
{
"records": {
"0": {
"id": 2,
"codice": "001",
"descrizione": "Articolo 1",
"um": "",
"abilita_serial": 0,
"immagine": null,
"note": "",
"qta": "9.000000",
"threshold_qta": "0.000000",
"qta_multipla": "0.000000",
"ubicazione": "",
"prezzo_acquisto": "10.000000",
"coefficiente": "2.000000",
"prezzo_vendita": "20.000000",
"prezzo_vendita_ivato": "24.400000",
"minimo_vendita": "0.000000",
"minimo_vendita_ivato": "0.000000",
"idiva_vendita": 171,
"gg_garanzia": 0,
"peso_lordo": "0.000000",
"volume": "0.000000",
"componente_filename": "",
"contenuto": "",
"attivo": 1,
"created_at": "2023-09-14 09:21:21",
"updated_at": "2023-09-14 09:55:35",
"id_categoria": null,
"id_sottocategoria": null,
"servizio": 0,
"idconto_vendita": null,
"idconto_acquisto": null,
"deleted_at": null,
"barcode": "",
"id_fornitore": null,
"um_secondaria": null,
"fattore_um_secondaria": "0.0000000000",
"id_combinazione": null,
"categoria": null,
"sottocategoria": null
},
"1": {
"id": 3,
"codice": "002",
"descrizione": "Articolo di Prova",
"um": "",
"abilita_serial": 0,
"immagine": null,
"note": "",
"qta": "0.000000",
"threshold_qta": "0.000000",
"qta_multipla": "0.000000",
"ubicazione": "",
"prezzo_acquisto": "0.000000",
"coefficiente": "0.000000",
"prezzo_vendita": "0.000000",
"prezzo_vendita_ivato": "0.000000",
"minimo_vendita": "0.000000",
"minimo_vendita_ivato": "0.000000",
"idiva_vendita": 171,
"gg_garanzia": 0,
"peso_lordo": "0.000000",
"volume": "0.000000",
"componente_filename": "",
"contenuto": null,
"attivo": 1,
"created_at": "2023-09-14 09:25:52",
"updated_at": "2023-09-14 09:25:52",
"id_categoria": null,
"id_sottocategoria": null,
"servizio": 0,
"idconto_vendita": null,
"idconto_acquisto": null,
"deleted_at": null,
"barcode": "",
"id_fornitore": null,
"um_secondaria": null,
"fattore_um_secondaria": "0.0000000000",
"id_combinazione": null,
"categoria": null,
"sottocategoria": null
}
},
"total-count": 2,
"pages": 1,
"status": 200,
"message": "OK"
}
]
Creazione di un articolo
curl -X POST -d '{
"token": "<token_tecnico>",
"resource": "movimento_articolo",
"data": {
"categoria": "Componenti",
"sottocategoria": "Micro",
"codice": "Vite01",
"descrizione": "Vite da 1cm",
"prezzo_vendita": "0.05"
}
}' "http://<indirizzo_osm>/api/"
Risposta
{
"id": 6,
"status": 200,
"message": "OK"
}
Modifica di un articolo
curl -X PUT -d '{
"token": "<token_tecnico>",
"resource": "articolo",
"id": 5,
"data": {
"categoria": "Usato",
"sottocategoria": "Micro",
"descrizione": "Vite da 1cm",
"prezzo_vendita": "0.08"
}
}' "http://<indirizzo_osm>/api/"
Risposta
{
"status": 200,
"message": "OK"
}
Movimenta articolo
curl -X POST -d '{
"token": "<token_tecnico>",
"resource": "movimento_articolo",
"data": {
"id_articolo": 1,
"data": "2023-09-15 12:50:00",
"descrizione": "Movimentazione da API",
"qta": 2
}
}' "http://<indirizzo_osm>/api/"
Risposta
{
"status": 200,
"message": "OK"
}
Impianti
Richiesta elenco impianti
curl "http://<indirizzo_osm>/api/?token=<token_tecnico>&version=v1&resource=impianti"
Risposta
{
"records": {
"0": {
"id": 1,
"idanagrafica": 2,
"matricola": "01",
"nome": "Impianto di Prova",
"descrizione": ""
}
},
"total-count": 1,
"pages": 1,
"status": 200,
"message": "OK"
}
Interventi
Richiedi elenco degli articoli collegati a un intervento
curl "http://<indirizzo_osm>/api/?token=<token_tecnico>&version=v1&resource=articoli_intervento&id_intervento=6"
Risposta
{
"records": {
"0": {
"id": 18,
"id_articolo": 2,
"id_intervento": 6,
"qta": 1,
"data": "2023-09-19 12:46:34"
}
},
"total-count": 1,
"pages": 1,
"status": 200,
"message": "OK"
}
Aggiunta articolo a un intervento
curl -X POST -d '{
"token": "<token_tecnico>",
"resource": "articolo_intervento",
"data": {
"id_articolo": 2,
"id_intervento": 1,
"qta": 1,
"um": "ore"
}
}' "http://<indirizzo_osm>/api/"
Risposta
{
"status": 200,
"message": "OK"
}
Elenco degli impianti collegati a un intervento
curl "http://localhost/openstamanager/api/?token=fxh2sluhHWGoOVq9dYDOisbtBsG9iikM&version=v1&resource=impianti_intervento&id_intervento=6"
Risposta
{
"records": {
"0": {
"id_impianto": 1,
"id_intervento": 6
}
},
"total-count": 1,
"pages": 1,
"status": 200,
"message": "OK"
}
Aggiunta impianto a un intervento
curl -X POST -d '{
"token": "<token_tecnico>",
"resource": "impianti_intervento",
"data": {
"id_intervento": 6,
"impianti": 2
}
}' "http://<indirizzo_osm>/api/"
Risposta
{
"status": 200,
"message": "OK"
}
Elenco degli interventi
curl "http://<indirizzo_osm>/api/?token=<token_tecnico>&version=v1&resource=interventi"
Risposta
{
"records": {
"0": {
"id": 3,
"codice": "1",
"data_richiesta": "2023-09-19 09:32:00",
"richiesta": "<p>Test</p>",
"descrizione": "",
"km": "0.00",
"idtipointervento": 1,
"nomefile": "",
"idanagrafica": 2,
"idreferente": 0,
"idagente": 0,
"idstatointervento": 3,
"informazioniaggiuntive": "",
"prezzo_ore_unitario": "0.00",
"idsede_partenza": 0,
"idsede_destinazione": 0,
"idclientefinale": 0,
"info_sede": "",
"firma_file": "",
"firma_data": null,
"firma_nome": "",
"data_invio": null,
"data_scadenza": null,
"created_at": "2023-09-19 09:33:00",
"updated_at": "2023-09-19 09:33:37",
"codice_cig": "",
"codice_cup": "",
"id_documento_fe": "",
"num_item": "",
"deleted_at": null,
"id_preventivo": null,
"id_contratto": null,
"id_ordine": null,
"id_segment": 12,
"data": null,
"tecnici": null,
"stato": "Fatturato"
},
"1": {
"id": 6,
"codice": "2",
"data_richiesta": "2023-09-19 09:48:00",
"richiesta": "<p>Test</p>",
"descrizione": "",
"km": "0.00",
"idtipointervento": 1,
"nomefile": "",
"idanagrafica": 2,
"idreferente": 0,
"idagente": 0,
"idstatointervento": 2,
"informazioniaggiuntive": "",
"prezzo_ore_unitario": "0.00",
"idsede_partenza": 0,
"idsede_destinazione": 0,
"idclientefinale": 0,
"info_sede": "",
"firma_file": "",
"firma_data": null,
"firma_nome": "",
"data_invio": null,
"data_scadenza": null,
"created_at": "2023-09-19 09:48:31",
"updated_at": "2023-09-21 11:57:02",
"codice_cig": "",
"codice_cup": "",
"id_documento_fe": "",
"num_item": "",
"deleted_at": null,
"id_preventivo": null,
"id_contratto": null,
"id_ordine": null,
"id_segment": 12,
"data": "2023-09-20 07:15:00",
"tecnici": null,
"stato": "Da programmare"
}
},
"total-count": 1,
"pages": 1,
"status": 200,
"message": "OK"
}
Elenco dei tipi di intervento
Stampa rapportino intervento
Richiesta elenco sessioni di un intervento
Richiesta sincronizzazione interventi
Elenco stati degli interventi
Contratti
Elenco stati dei contratti
Ordini
Elenco stati degli ordini
Preventivi
Elenco stati dei preventivi
Stato dei servizi
Richiedi spazio occupato dall'installazione
Utenti
Login
Logout
Messaggi di errore
In base allo stato dell'API e alla richiesta effettuata, è possibile che vengano restituiti dei messaggi di stato che informano l'utilizzatore del risultato della richiesta.
| Codice | Significato |
|---|---|
| 200 | OK -- La richiesta è andata a buon fine. |
| 400 | Erorre interno dell'API -- La richiesta effettuata risulta invalida per l'API. |
| 401 | Non autorizzato -- Accesso non autorizzato. |
| 404 | Non trovato -- La risorsa richiesta non risulta disponibile. |
| 500 | Errore del server -- Il gestionale non è in grado di completare la richiesta. |
| 503 | Servizio non disponibile -- L'API del gestionale non è abilitata a causa della versione troppo vecchia di MySQL (>= 5.6.5). |