Linee guida Generali API TS-Digital
ItemID
Riferimenti a risorse avvengono tramite ItemID
L'itemID è il riferimento univoco ad una risorsa anagrafica TsDigital, in particolare può riferisia a :
- Studi
- Aziende
- Uffici
- Condomini
A tendere ogni endpoint di TS-Digital che avrà come input un dato che fa riferimento ad una di queste entità dovrà utilizzare il rispettivo ItemId.
Ad oggi ogni azienda ha già un ItemId che, nel caso di aziende (classifier=COMPANY) e studi (classifier=STUDIO) italiane (taxRegion=IT), coincide con il codice fiscale. Condomini e aziende/studi esteri utilizzano già il nuovo formato.
Per recuperare questo id è possibile chiamare l’anagrafica TS-Digital al seguente endpoint:
https://registry-read-test.agyo.io/swagger-ui.html#/API/findItemsUsingGET
Impostando
- identifier.taxId o identifier.vatNumber
- identifier.taxRegion
- packageType: BASE
È possibile cercare per CF o PIVA
Esempio ricerca per partiva iva:
Esempio ricerca per codice fiscale:
Una volta recuperato l’id per una determinata azienda sarà possibile salvarlo localmente solo in caso sia un UUIDv4 perchè non verrà più modificato a differenza dell’attuale codice fiscale che può subire variazioni dovuti ad eventi di rettifica.
Inizialmente la situazione sarà mista per questioni di migrazione.
In caso l’identificativo sia uguale al CF il comportamento consigliato è quello di avere una cache di alcune ore (consigliate 24/48) per evitare carico inutile verso le API di anagrafica, ma di continuare a chiederlo ogni volta che scade la cache.
Se l’identificativo risulta invece essere un UUIDv4 (o comunque lunghezza > 20 quindi oltre il formato CF italiano (16) + i caratteri “-XXX” dell’ufficio (4)) è possibile salvarlo consapevoli del fatto che non cambierà più.
Header obbligatori ad ogni chiamata API
X-App-Name: id dell’applicativo (es: TS500, TS010, ecc). Non utilizzare valori diversi dall’appname assegnato in quanto verranno introdotti controlli che bloccheranno tutte le chiamate con AppName non censiti
X-App-Version: versione dell’applicativo, utile per determinare eventuali problemi su una particolare versione, statistiche di utilizzo, ecc
X-Request-ID: Identificativo univoco di una singola richiesta. (es. cjqqbbezk139w08878awoj1p0 generato con la libreria https://github.com/ericelliott/cuid). Utile per determinare eventuali problemi su una particolare chiamata, eventualmente associata al log dell’applicativo stesso.
X-Correlation-ID: Identificativo correlatore di tanti X-Request-ID. Il raggruppamento è deciso dal chiamante in quello che può essere definita una singola attività (es. Il provisioning di una azienda può essere formato da 3 chiamate, creazione azienda, creazione connessione, creazione servizio, sono 3 X-Request-ID differenti ma correlati dallo stesso ID in quanto per l’applicativo l’azione può essere vista come atomica)
X-Item-ID: itemID (vedi sopra ItemID) soggetto dell’attuale azione. Nelle installazioni enterprise può coincidere con l’itemID del licenziatario, nel caso di studi può essere l’itemID su cui il professionista sta lavorando. Utile per determinare eventuali problemi su un particolare cliente, statistiche di utilizzo, ecc.
X-User-ID: identificativo della chiave tecnica dell’applicativo utilizzata per ottenere il token dalle API di auth (es: b7b0ce7b-86a1-4298-9da7-82522fc28a09, ecc). Insieme all’AppName verrà utilizzato per identificare puntualmente la o le installazioni in caso di problemi, ma anche statistiche di utilizzo, ecc..
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.
Differenze con le attuali V1
Le API v2 di lettura differiscono dalle v1 relativamente alla paginazione. Nella nuova versione infatti non è più presente il conteggio degli elementi totali e del numero di pagine ma un booleano che indica se è presente una pagina successiva.
V1 (deprecate)
"page": {
"size": 20,
"totalElements": 111,
"totalPages": 6,
"number": 0
}V2
"page": {
"size": 20,
"hasNext": true,
"continuationToken": "abc...xyz"
}Per ottenere la pagina successiva è sufficiente richiamare la url fornita nella risposta nell'oggetto _links:
"_links": {
"first": {
"href": "https://b2bread-api-test.agyo.io/api/v2/invoices?ownerId=ABCDEFGHI&size=20&sort=lastTimestamp,desc"
},
"self": {
"href": "https://b2bread-api-test.agyo.io/api/v2/invoices?ownerId=ABCDEFGHI&size=20&sort=lastTimestamp,desc"
},
"next": {
"href": "https://b2bread-api-test.agyo.io/api/v2/invoices?ownerId=ABCDEFGHI&continuationToken=5WvMRcmA_8WJtFSiemEregGggF3etSD4QqPv1aSDXnwfjLKGZKOwq13sye5fl9NQ8799jMkJveAlTaOmC9H4Pn3Wtt2cA5iTyce_5YgEik8cNNEvvUwfz43t22M3tjjc&size=20&sort=lastTimestamp,desc"
}
}Come è possibile osservare esaminando questi link, nella chiamata viene aggiunto il parametro relativo al continuationToken. Questo parametro consentirà al servizio di lettura di riprendere la lettura nel punto in cui si è arrivati nella lettura precedente
Un’ulteriore differenza consiste nell’obbligatorietà del campo OwnerId
Questo campo identifica il proprietario della fattura. Confrontandolo con le V1 rappresenta il sender per la ricerca delle fatture attive e il recipient per la ricerca delle passive.
Questo campo è quindi un riferimento all’azienda con la qule si sta operando. Ed è anch’esso un AgyoItemId.