Linee guida Generali API TS-Digital
Header obbligatori ad ogni chiamata API
X-App-Name: idcodice dell’applicativoidentificativo (es:rilasciato TS500,da TS010,Teamsystem ecc).al momento del censimento. Non utilizzare valori diversi dall’appnameAppName assegnato in quanto verrannovi introdottisono dei controlli che bloccherannobloccano tutte le chiamate con AppName non censiti.
X-User-Agent: una stringa che indichi il prodotto, la sua versione e altre informazioni che possano essere rilevanti all'identificazionenome dell'applicativoapplicativo/software chiamante.utilizzato.
X-App-Version: versione dell’applicativo,applicativo/software utile per determinare eventuali problemi su una particolare versione, statistiche di utilizzo, ecc.utilizzato.
X-Request-ID: Identificativo univoco di unadella singola richiesta.richiesta (es.nel cjqqbbezk139w08878awoj1p0formato generatocuuid. con Esempio: se per ottenere la librerialista https://github.com/ericelliott/cuid).documenti Utiledevo chiamare Auth, Anagrafica e B2BRead ogni singola chiamata deve avere un valore diverso di X-Request-ID. NON utilizzare lo stesso valore per determinarechiamate eventuali problemi su una particolare chiamata, eventualmente associata al log dell’applicativo stesso.diverse.
X-Correlation-ID: Identificativo correlatoreunivoco didel tantiflusso in formato uuid-v4. Esempio: se per ottenere la lista documenti devo chiamare Auth, Anagrafica e B2BRead tutte le chiamate dovrebbero avere lo stesso X-Request-Correlation-ID. IlIn raggruppamentoquesto modo nei log è decisopossibile daltracciare chiamantee incorrelare quellotutte chele puòrichieste. essere definita una singola attività (es. Il provisioning di una azienda può essere formato da 3 chiamate, creazione azienda, creazione connessione, creazione servizio, sonoNON 3utilizzare X-Request-ID differenti ma correlati dallolo stesso ID in quantovalore per l’applicativoflussi l’azione può essere vista come atomica)diversi.
X-Item-ID: itemID (vedi sopra ItemID) soggetto dell’attuale azione. Nelle installazioni enterprise può coincidere con l’itemID del licenziatario, nel casoidentificativo di studichi puòeffettua esserela l’itemIDrichiesta su(UUID). cui il professionista sta lavorando. Utile Link per determinarerecuperare eventualil'identificativo problemidell'azienda: su un particolare cliente, statistiche di utilizzo, ecc.https://digital-docs.ts-paas.com/books/anagrafica/page/endpoint-di-lettura
X-User-ID: identificativo dell'utenza che disponesta dell'autorizzazione per effettuareeffettuando la chiamata API in atto.richiesta. (es:ID b7b0ce7b-86a1-4298-9da7-82522fc28a09della perChiave chiavi tecniche, mario.rossi@gmail.com per utenze personali). Insieme all’AppName verrà utilizzato per identificare puntualmente l'utente o le installazioni ERP in caso di problemi, ma anche statistiche di utilizzo, ecc.Tecnica).
X-Manager-ID: opzionale per i prodotti che non prevedono l’operatività su itemID terzi. Nel caso di studi invece è l’itemID del professionista (quindi potrebbe coincidere con l’itemID del licenziatario ad es.) che sta operando per conto dell’X-Item-ID. Utile per determinare eventuali problemi su un particolare cliente, statistiche di utilizzo, ecc.
Errori durante le chiamate
Prestare attenzione agli stati http delle risposte e agire di conseguenza (https://httpstatuses.com/)
Esempio: se ottengo un 400 Bad Request è inutile riprovare la richiesta perchè otterrò sempre lo stesso risultato. Confrontiamoci per capire le logiche di business in caso di dubbi (no confirmDownload su flussi attivi, dati obbligatori in upload, ecc)
A breve verranno introdotti limiti/controlli sul numero di chiamate effettuabili in un arco temporale (da definire). In caso di sforamento dei tali limiti è necessario gestire il codice http 429 Too many Requests.