Linee guida Generali API TS-Digital
Header obbligatori ad ogni chiamata API
X-App-Name: codice identificativo rilasciato da Teamsystem al momento del censimento. Non utilizzare valori diversi dall’AppName assegnato in quanto vi sono dei controlli che bloccano tutte le chiamate con AppName non censiti.
X-User-Agent: nome dell'applicativo/software utilizzato.
X-App-Version: versione dell’applicativo/software utilizzato.
X-Request-ID: Identificativo univoco della singola richiesta nel formato cuuid. Esempio: se per ottenere la lista documenti devo chiamare Auth, Anagrafica e B2BRead ogni singola chiamata deve avere un valore diverso di X-Request-ID. NON utilizzare lo stesso valore per chiamate diverse.
X-Correlation-ID: Identificativo univoco del flusso 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-Correlation-ID. In questo modo nei log è possibile tracciare e correlare tutte le richieste. NON utilizzare lo stesso valore per flussi diversi.
X-Item-ID: identificativo di chi effettua la richiesta (UUID). Link per recuperare l'identificativo dell'azienda: https://digital-docs.ts-paas.com/books/anagrafica/page/endpoint-di-letturaazienda.
X-User-ID: identificativo dell'utenza che sta effettuando la richiesta. (ID della Chiave 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.