Skip to main content

Linee guida Generali API TS-Digital

Header obbligatori ad ogni chiamata API

 

Ad ogni chiamata è obbligatorio inserire i parametri riportati e popolarli nel seguente modo:

Authorization: contieneBearer Token. Come si genera il tokentoken? rilasciatoVedi dallenella APIsezione di auth (https://digital-docs.ts-paas.com/books/autenticazione-e-autorizzazione)"Info"

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). LinkCome persi recuperarerecupera l'identificativoUUID? dell'azienda.Vedi nella sezione "Info"

X-User-ID:  identificativo dell'utenza che sta effettuando la richiesta. (ID della Chiave Tecnica).

X-Manager-ID: opzionaleparametro opzionale. Da popolare con UUID dello studio che opera per aziende gestite.

Info:

Come si generano le chiavi tecniche? Clicca qui.

Per generare il token invece, i prodottipassaggi chesono noni prevedonoseguenti:

    Generare il nonce, inserendo nel body della chiamata l’operativitàID sudella itemIDchiave terzi.tecnica. NelGenerare casoil ditoken, studiinserendo invecenel body della chiamata l’ID della chiave tecnica e il digest.

    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"
}'

    Chiamata per recuperare l'UUID:

    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 ''

    Il parametro da prendere in considerazione nella response è l’itemID"id". delEsempio:

    professionista
    {
    (quindi"items": potrebbe[
        coincidere{
            con"item": l’itemID{
                del"base": licenziatario{
                    ad"id": es.)"bf01b67b-86c6-4695-b8c3-2135aa0b8d6c",
                    che"identifier": sta{
                        operando"taxId": per"00987564119",
                        conto"taxRegion": dell’X-Item-ID."IT",
                        Utile"vatNumber": per"00987564119",
                        determinare"govCode": eventualinull
                      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.

     

     

    Back to top