Linee guida API TS-Digital
Di seguito andiamo ad elencare le modifiche che vanno apportate per essere compatibili con le versioni future dell’hub ed in particolare della versione 2 delle api.
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ù.
HubId
L’hubId dovrà essere trattato come una stringa da 1 a 36 caratteri.
I nuovi hubId saranno ugualmente univoci, se non lo fossero subiremmo noi per primi il problema, ancora prima che voi possiate avere l’id perchè non saremmo in grado di inserirlo sul nostro db.
La nuova struttura dell’hubId ci permetterà di risparmiare spazio in RAM sul cluster di fatturazione, sia per via della dimensione ridotta sia perché tramite il nuovo formato saremo in grado di sfruttare il meccanismo di compressione degli indici di MongoDb.
Gli hubId già forniti NON verranno modificati.
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.
Lettura fatture
È disponibile un meccanismo di notifica tramite webhook che consente di essere notificati della presenza di nuove fatture e aggiornamenti di stato evitando così di interrogare TS Digital inutilmente e accedendo puntualmente alle fatture che hanno subito modifiche.
Se non viene utilizzato il meccanismo di webhook sono disponibili le api di ricerca all’endpoint /api/v2/invoices.
Il flusso consigliato per la consultazione della fatture è quello di effettuare prima una chiamata di CompanyOverview per verificare la presenza di fatture e successivamente effettuare le chiamate specifiche con il filtri di cui necessitiamo e ragionando per timestamp di ultimo aggiornamento dei documenti.
Questo procedimento consente di ridurre le chiamate a quelle essenziali, inoltre la chiamata a CompanyOverview ha un impatto notevolmente inferiore rispetto alla getAll.
Link utili alla documentazione degli endpoint
- https://b2bread-api-test.agyo.io/api/docs/index.html#resources-
companyOverviewitemOverview - https://b2bread-api-test.agyo.io/api/docs/index.html#resources-invoices-getAll
QUI Lo swagger è possibiledisponible trovareal illink json-schema dell'entità invoice.https://b2bread-api-test.agyo.io/api/swagger-ui.html
Step 1 - CompanyOverviewItemOverview
La chiamata di companyitem overview fornisce una panoramica sulla situazione delle fatture dell’azienda. Per i dettagli del funzionamento ed un corretto utilizzo consultare la documentazione a questo link.
In particolare ci informa sulla presenza di
- Fatture attive
- Fatture passive
- Fatture scartate
È possibile chiamare l’API passando più di un’azienda da controllare, in tal caso bisognerà gestirne anche l’eventuale paginazione.paginazione mediante continuationToken.
Per ogni azienda occorre specificare i seguenti parametri:
-
agyoItemIditemId : (vedi sopra ItemID) - lastTimestampActive : timestamp dal quale effettuare la ricerca, ad ogni chiamata ci aspettiamo che il chiamante si salvi il timestamp di ultima chiamata in modo da fornirlo poi alla successiva. In questo modo la ricerca sarà limitata all’ambito nel quale ancora non si è ancora ricercato nulla, ottimizzando la ricerca.
- lastTimestampPassive : come sopra.
Come risposta riceveremo per ogni azienda i 3 valori booleani relativi alla presenza di fatture attive, passive e scartate e i loro timestamp.
Ad esempio:
{
"agyoCompanyId"itemId" : "ABCDEF00G00H000I"ABCDEF",
"active" : true,
"passive" : false,
"rejected" : true,
"lastTimestampActive" : 1573748280467,
"lastTimestampPassive" : 1558706778691,
"lastTimestampRejected" : 1574382215139
}Per ogni azienda potremo quindi chiamare le api di lettura per le sole tipologie di fatture per le quali abbiamo un true. In questo caso ha senso chiamare solo per scaricare le fatture passive in quanto sappiamo per certo che sono le uniche che troveremo.
Step 2 - Lettura Fatture
Andiamo ora a vedere come interrogare gli endpoint REST delle api v2 al fine di recuperare la lista di fatture attive e passive.
Come anticipato nella call evitare di filtrare sugli stati delle fatture e lavorare invece sul delta dei documenti cambiati a partire da una certa data (aka listChangesFrom).
Nella chiamata successiva dovrò indicare come parametro lastTimestampFrom il valore di lastTimestamp della prima fattura ottenuta in risposta.
Nella query string di ricerca è stato introdotto il nuovo parametro obbligatorio ownerId. Nel caso di utenze con permessi su molte aziende le query si traducevano in un "in" molto oneroso per il database visto l'elevato numero di fatture presenti (ad oggi quasi 400 milioni). Se l'azienda ha più di un ufficio e si vogliono recuperare le fatture di tutti gli uffici è possibile aggiungere al valore di ownerId il suffisso -ALL.
Di seguito due chiamate di esempio:
per recuperare la prima pagina di fatture attive relative all'azienda con AgyoId ABCDE a partire da un dato timestamp:
per le fatture passive
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.
Cancellazione delle fatture
Tutte le fatture scartate da TS Digital (non dallo SDI) saranno eliminate fisicamente dal DB dopo 120 gg. Se si prova a visualizzare quella fattura sarà restituito errore “documento non esistente” e status code 404. Se necessario possiamo prevedere di fare un API per leggere le informazioni della conferma cancellazione (timestamp)
Rimozione dello stato Ricevuto
L’apiEra stata presa in considerazione l'ipotesi di presarimuovere visionel'operazione verràdi eliminata.confirmDonwload Perprima le fatture SDIPA passive sarà quindi possibile eseguire l’operazionedell'esecuzione di ACCETTA/RIFIUTA senzasu passarefatture dalloSDIPA passive. Per problemi di retrocompatibilità non è stato RICEVUTO.possibile procedere in tal senso, pertanto il comportamento è rimasto invariato.