ZotSell
Wizard Home | api_content

Cod. Ultima revisione Wiki Note
337 2022/04/19 - PG Syncro: 
Ordini GET: /api/api_user/api_content/orders
Task GET : 

Api Rest disponibili nel sistema

Le Api Rest sono delle chiamate https che si possono utilizzare per gestire in remoto dei  processi sui nostri sistemi o ottenere 
estrazione di dati dallo stesso. Sono molto utili per l'automazione di certe funzioni direttamente dai sistemi del cliente.

Le chiamate necessitano della conoscenza di un token (Password a 32 caratteri)  che deve essere utilizzata per una corretta autenticazione.
Il token viene generato all'attivazione del server e il Cliente è responsabile della segretezza dello stesso.

Nel caso in cui ci sia il sospetto che la segretezza di tale token possa essere compromessa è responsabilità del cliente segnalare la necessità di rinnovo 
tramite apertura di apposita issue nel sistema di Assistenze (https://help.zotsell.com) 

Sarà cura del nostro staff predisporre un nuovo token e comunicarlo al cliente.   

Le api che restituiscono informazioni a seconda del tipo possono rispondere 
- Con una stringa di testo
- Con un file JSON (Vedi  www.json.org) 
- Con un file .csv per la maggior prte dei casi 

Di seguito una lista di api interrogabili sul sistema.

Info Importante
Per scaricare via linea di comando i dati provenienti dalle api-Rest  ci sono dei programmini tipo wget o curl .
(ci dovrebbe essere il porting su qualsiasi sistema operativo)

Sul sito www.json.org, a fondo della home page, c’è una lista abbastanza nutrita di programmi che possono elaborare le json di risposta.

Elaborazione Server Completa

Individuazione delle chiavi Host :

      -->Impostazioni --> Server Settings --> Import csv (sftp/ftp)

Sia accederà a schermata di impostazione delle sincronizzazione base prevista per il vostro server in basso sarà presente una tabella "Api syncro info" che riporterà 
URL's per la chiamata di avvio sincronizzazione (Sync) e di valori di configurazione.






Avvio elaborazione

(Sync)
L’api da chiamare è la seguente (con il vostro nomehost al posto di "test" indicato nell'esempio) 

<a href="https://test-enterprise.zotsell.com/SyncServer/Sync/key/84096242922af896a010261f853b1srf">https://test-enterprise.zotsell.com/SyncServer/Syn...</a>
Dopo aver effettuato la chiamata al URL di sincronizzazione il sistema restituirà una JSON con il recepimento di del processo se correttamente avviato.

Esempio di JSON restituita dal sistema dopo in seguito a una chiamato all'URL di sincronizzazione.

{"status":0,"message":"Process start","info":""}

Se chiamato successivamente (Processo già avviato o con chiave errata) 

{"status":1,"message":"Key not provided or incorrect or sync process still running or disabled","info":""}

Per avere i dettagli di processo utilizzare l'api di seguito descritta.

Stato elaborazione

(GetStatus)
Api per ottenere dei feedback sullo stato elaborativo del server Zotsell al fine di capire se l'elaborazione si è conclusa o meno o in che fase si trova.
L’api da chiamare è la seguente (con il vostro nomehost al posto di "test" indicato nell'esempio) 

<a href="https://test-enterprise.zotsell.com/SyncServer/GetStatus/key/84096242922af896a010261f853b1srf">https://test-enterprise.zotsell.com/SyncServer/Get...</a>


La struttura della risposta è sempre quella riportata di seguito (tra parentesi quadre i parametri che potrebbero non esserci).

L’api restituisce tutto in una sola linea, dato che per i programmi che elaborano le json non ha nessuna rilevanza la formattazione

{ ["percentage”:”PERCENTUALE DEL PROCESSO”], "status”:STATO DEL PROCESSO, [step:”PARTE DEL PROCESSO IN ESECUZIONE”], "message”:"MESSAGGIO”, "info”:”INFO AGGIUNTIVE” }


Legenda Parametri: 

percentage : assume valori da 0 a 100. Generalmente a processo fermo ha valore 100. Riporta la percentuale del processo di sincronizzazione realizzato
status: può assumere i seguenti valori
0: processo fermo. In generale è associato a un valore di percentage a 100.
1: chiave fornita non corretta. Nel caso in cui venga fornita una chiave non appropriata il sistema risponde con questo status. Non viene fornito il percentage o lo step.
2: processo in esecuzione: Il processo di sincronizzazione è in esecuzione e generalmente tale valore è associato a un valore di percentage diverso da 100.
3: processo in errore: Il processo di sincronizzazione ha riscontrato un problema e non è stato ultimato. Generalmente è associato a un valore di percentage diverso da 100
step: indica lo step a cui è giunto il processo. Solo utile a livello informativo e viene riportato solo nel caso di status a 2 o 3. Può assumere i seguenti valori
1: importazione da ftp. Prima fase di sincronizzazione tracciati da ftp a server zotsell
2: importazione risorse da ftp. Sincronizzazione risorse da ftp a server zotsell
3: importazione risorse in deposito. Controllo delle risorse e registrazione nel deposito di zotsell
4: controllo tracciati. Controllo della correttezza dei tracciati e loro elaborazione
5: importazione contatti. Elaborazione contatti
6: importazione articoli. Elaborazione articoli/catalogo
7: importazione listini. Elaborazione prezzi/sconti
8: importazione reports. Elaborazione documenti personalizzati per agenti
message: messaggio di base sullo stato del processo. Può assumere i seguenti valori
"No running process”: associato generalmente con lo status 0
"Process still running”: associato generalmente con lo status 2
"Process stopped in unexpected mode”: associato generalmente con lo status 3
info: per questa api non viene valorizzato per ora.


Elaborazione Server Parziale


Per dettagli vedi questa Scheda

Esportazione Ordini

Di seguito la lista di api per interagire con i documenti di vendita (Ordini) acquisiti dal sistema.

Lista Ordini

Sintassi base chiamata:

http://#NOMEHOST#/manager/orders/key/#TOKEN#

Esempio: 


<a href="https://test-enterprise.zotsell.com/manager/orders/key/26d055e4444622c65c8dbf98eBa141AA">https://test-enterprise.zotsell.com/manager/orders...</a>


E' possibile poi accodare dei parametri per ottenere filtri formati

Parametri accettati


status

Di default adesso vengono restituiti solo gli ordini in stato trasferito. Queste le opzioni da inviare con il parametro "status"
  • 0 = Order::STATUS_CANCELED = cancellato
  • 1 = Order::STATUS_TRANSFERED (questo si sarebbe potuto omettere volendo) = trasferito in gestionale
  • 2 = Order::STATUS_BLOCKED = bloccato
  • 3 = Order::STATUS_SUSPENDED = sospeso
  • 4 = Order::STATUS_SAVED = non trasferito (creato il tracciato ma non mandato in ftp)



type

Indica il tipo di output da generare


nessuno valore
genera una json con questa struttura 

	[
	    {
	       "entity_id":"FB968325-C99F-435D-B58B-12B2327D5247",
	       "order_code":"IPAD_20170209163704_001"
	    },
	......
	    {
	       "entity_id":"FB968325-C99F- 435D-B58B-12B2327D5247",
	       "order_code":"IPAD_20170209163704_001"
	    }
	]



txt
Genera la lista testuale dei codici ordine. Es. 

	IPAD_20170320093519_001
	IPAD_20170320093646_001
	WEB_20170320094111_001
	.....



txtid
Come txt solo che genera la lista testuale degli entity_id (utile per chiamate successive)



links
Genera un html con le chiamate alle api per il dettaglio ordine e per la rigenerazione



jsonlinks
Genera una Json aggiungendo i link al dettaglio ordine (utile eventualmente per integrare con dei programmi di automazione per lo scaricamento ordine).

Es. 

	[
	  {
	    "entity_id": "FB968325-C99F-435D-B58B-12B2327D5247", <br>
	    "order_code": "IPAD_20170209163704_001",
	    "linkJson": "<a href="https://test-enterprise.zotsell.com/manager/orders/FB968325-C99F-435D-B58B-12B2327D5247/key/26d055e4444622c65c8dbf98eBa141AA?type=json">https://test-enterprise.zotsell.com/manager/orders/FB968325-C99F-435D-B58B-12B2327D5247/key/26d055e4444622c65c8dbf98eBa141AA?type=json</a>", <br>
	    "linkTrack": "<a href="https://test-enterprise.zotsell.com/manager/orders/FB968325-C99F-435D-B58B-12B2327D5247/key/26d055e4444622c65c8dbf98eBa141AA?type=track">https://test-enterprise.zotsell.com/manager/orders/FB968325-C99F-435D-B58B-12B2327D5247/key/26d055e4444622c65c8dbf98eBa141AA?type=track</a>",<br>
	    "linkRegen": "<a href="https://test-enterprise.zotsell.com/manager/orders/regen/FB968325-C99F-435D-B58B-12B2327D5247/key/26d055e4444622c65c8dbf98eBa141AA">https://test-enterprise.zotsell.com/manager/orders/regen/FB968325-C99F-435D-B58B-12B2327D5247/key/26d055e4444622c65c8dbf98eBa141AA</a>"<br>
	  }, 
	....
	]



start_date

Si basa sul contenuto del campo date_order presente nel record ordine del server  che corrisponde alla Data di creazione dell'ordine nel client .
E' la data di inizializzazione poi non veine più modificata al variare del record


Indica il valore minimo del range di estrazione.


Il valore viene considerato dalla data fornita esclusa in poi.

Valori accettabili
2017
201709
20170901
2017090101
201709010101
20170901010101
2017-09-10
2017-09-10 01:01:01


end_date

Si basa sul contenuto del campo date_order analogamente al parametro start_date

Indica il valore massimo del range di estrazione.

Valori accettabili: vedi start_date




start_date_access

Si basa sul contenuto del campo date_access presente nel record ordine del server che corrisponde alla data di creazione del record nella tabella ordini del server.

Se l'ordine viene salvato in stato sospeso, quando viene confermato questa data viene aggiornata e. valorizzata con la data di conferma.

In generale un ordine viene  generato nei client mobile con un date_order precedente alla data in cui viene trasmesso al server data salvata nel campo  date_access.

E' un parametro utile per estrarre i record trasmessi o aggiornato nel server  in un range di date specifico 

Indica il valore minore (escluso) del range di estrazione.

Valori accettabili: vedi start_date


end_date_access

Si basa sul contenuto del campo date_access analogamente al parametro start_date_access

Indica il valore maggiore (escluso) del range di estrazione.

Valori accettabili: vedi start_date



external_status


Si basa sul contenuto del campo management_status che corrisponde al valore di stato dell'ordine alimentato tramite tracciati dall'esterno (Gestionel/CRM).
Rif: ordini_opzioni_aggiuntive.csv

Valore di default : 



limit

Limitazione del numero di ordini.

Valori accettabili: solo interi


offset

Record da cui far partire la l'estrazione

Valori accettabili: solo interi


Esempi di chiamate



Errori


Codice 401: non autorizzato
Messaggio: Error: You must be authorized to view this page.



Dettaglio ordine

<a href="https://test-enterprise.zotsell.com/manager/orders/10B49514-A526-44C8-BB25-D029918B5248/key/26d055e4444622c65c8dbf98eBa141AA">https://test-enterprise.zotsell.com/manager/orders...</a>

Di default estrae la json dell'ordine. La json dell'ordine è quella registrata in database così come arriva da app.


Parametri accettati


type
indica il tipo di output da generare

nessuno valore
: restituisce la Json dell'ordine

track
: restituisce il tracciato dell'ordine



Esempi chiamate
Json ordine:  https://test-enterprise.zotsell.com/manager/orders/10B49514-A526-44C8-BB25-D029918B5248/key/26d055e4444622c65c8dbf98eBa141AA
Tracciato ordine:  https://test-enterprise.zotsell.com/manager/orders/10B49514-A526-44C8-BB25-D029918B5248/key/26d055e4444622c65c8dbf98eBa141AA?type=track

Errori
Codice  401: non autorizzato
Messaggio: Error: You must be authorized to view this page.
Codice  404: Risorsa non presente (ordine non trovato)
Messaggio: Error: Resources not present

 

Rigenerazione ordine

<a href="https://test-enterprise.zotsell.com/manager/orders/regen/10B49514-A526-44C8-BB25-D029918B5248/key/26d055e4444622c65c8dbf98eBa141AA">https://test-enterprise.zotsell.com/manager/orders...</a>
<br>
Risultati restituti
<br>
Azione riuscita: {"result":"OK","risultato":null}
<br>
Azione fallita: {"result":"KO","risultato":false}
<br>
<br>

Esportazione Task

Anche per i Task è possibile utilizzare delle API per interrogare il server e ottenere i dati acquisiti e presenti nel DB  
Trovate  la lista di api per interagire con i Task in questa  Scheda