Linee guida Generali API TS Digital
Header
Ad ogni chiamata è obbligatorio inserire i parametri riportati e popolarli nel seguente modo:
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). Come si recupera l'UUID? Vedi nella sezione "Info"
X-User-ID: identificativo dell'utenza che sta effettuando la richiesta. (ID della Chiave Tecnica).
X-Manager-ID: parametro opzionale. Da popolare con UUID dello studio che opera per aziende gestite.
Chiavi Tecniche
Le credenziali (id e secret) da utilizzare nell’autenticazione possono essere generate dalla sezione applicativi del portale.
Per saperne di più, clicca qui.
Token
Per generare il token invece, i passaggi sono i seguenti:
1. Generare il nonce, inserendo nel body della chiamata l’ID della chiave tecnica.
2. Generare il token, inserendo nel body della chiamata l'ID della chiave tecnica.
Calcolare il digest tramite la seguente formula: sha256(sha256(ID + secret) + nonce)
Chiamata per generare il nonce:
curl --location --request POST 'https://b2b-auth-service-test.agyo.io/api/v3/nonces' \
--header 'accept: application/json' \
--header 'User-Agent: Postman' \
--header 'X-App-Name: TSxyz' \
--header 'X-App-Version: 1.0' \
--header 'X-Request-ID: 1' \
--header 'X-Correlation-ID: 1' \
--header 'Content-Type: application/json' \
--data-raw '{
"id":"string"
}'Chiamata per genere il token:
curl --location --request POST 'https://b2b-auth-service-test.agyo.io/api/v3/tokens' \
--header 'accept: application/json' \
--header 'User-Agent: Postman' \
--header 'X-App-Name: TSxyz' \
--header 'X-App-Version: 1.0' \
--header 'X-Request-ID: 1' \
--header 'X-Correlation-ID: 1' \
--header 'Content-Type: application/json' \
--data-raw '{
"id":"string",
"digest":"string"
}'UUID
Per recuperare l'UUID invece bisogna effettuare la chiamata sottostante ed inserire il CF/P.iva dell'azienda nel parametro "vatNumber".
curl --location --request GET 'https://registry-read-test.agyo.io/api/v3/items?identifier.vatNumber=48548641546&packageType=BASE&pagination.itemsPerPage=10&pagination.pageNumber=0&identifier.taxRegion=IT' \
--header 'accept: application/json;charset=utf-8' \
--header 'User-Agent: Postman' \
--header 'X-App-Name: TSxyz' \
--header 'X-App-Version: 1.0' \
--header 'X-Request-ID: 1' \
--header 'X-Correlation-ID: 1' \
--header 'Authorization: Bearer ' \
--data-raw ''Nella response poi, il parametro da prendere in considerazione è "id".
Esempio: 
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.