Lettura fatture
Endpoints
LinkRiferimenti: Endpoints
Le chiamate per la lettura delle fatture si dividono in due step.
Api
Questo v2non vuol dire però che sono complementari, ovvero, le chiamate di lettura fatture (step 2) possono essere effettuate anche senza lo step 1.
Perché è importante però utilizzare lo step 1?
Lo step 1, ovvero la chiamata di ItemOverview, è importante perché ci consente di verificare rapidamente se ci sono delle nuove fatture.
Questo permette di non sovraccaricare i nostri server perché se chiamando l’ItemOverview (step 1) ci restituisce che non ci sono delle nuove fatture è inutile procedere con lo step 2.
Dopo aver effettuato la chiamata di company Overview ( se non lo avete fatto, leggetelink qui).
Possiamopossiamo procedere a chiamare le api di lettura per ogni item che ha fatture.
Endpoint:
Andiamoi ora a vedere come interrogare gli endpoint REST delle api v2 al fine di recuperare la lista di fatture attive e passive.
Evitare di filtrare sugli stati delle fatture e lavorare invece sul delta dei documenti cambiati a partireparametri da unaimpostare certasono:
Nella chiamata dovrò indicare come parametro lastTimestampFrom il valore di lastTimestamp della fattura più recente ottenuta in risposta alla precedente chiamata a v2/invoices.
Se la chiamata è effettuata per la prima utilizzare un valore valido a piacere, ad esempio 1577836800000 (1 Gennaio 2020, 00:00:00 UTC).
Attenzione NON vanno utilizzati i valori di lastTimestampActive / lastTimestampPassive della company overview, ma, ad essclusione della prima volta, per tutte le chiamate dovrà essere il valore di lastTimestamp della fattura più recente ricevuta in risposta.
Nella query string di ricerca è stato introdotto il parametro obbligatorio ownerId.UUID/CF/P.iva) 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.
Come impostare la chiamata:
Eseguo la prima chiamata con data a piacere, ad esempio 24/01/2022
Dalla response ottengo tutte le fatture che hanno subito aggiornamenti successivi alla data impostata.
Le fatture vengono restituite dalla più recente alla meno recente.
Il giorno seguente ho bisogno di sapere se ci sono altri aggiornamenti sulle fatture?
Quello che bisogna fare è fare è impostare nella chiamata il timestamp dell’ultima fattura ottenuta dalla response precedente.
Esempio:
24/01/2022 ore 11:00 à timestamp: 1643022047000
Response:
“…
"currentStatusName": "INVIATO",
"lastTimestamp": 1643047247000,
"active": true,
…"
25/01/2022 ore 11:00 timestamp: 1643047247000
In questo modo dalla response otterremo solo le fatture che hanno subito un aggiornamento e non nuovamente tutta la lista delle fatture.
Il comportamento ideale da seguire quindi è sincronizzare le fatture tramite questa chiamata e poi impostare delle query da parte vostra per ottenere specifici risultati.
E’ possibile trovare la stessa fattura in diverse chiamate?
Sì è possibile perché il lastTimestamp di una fattura viene cambiato ad ogni aggiornamento quindi una fattura potresti averla in risposta anche ad ogni chiamata se (per esempio) venisse aggiornata ogni giorno.
DiContinuation seguitoToken
Il “continuationToken” ci permette di vedere, qualora siano presenti, le altre fatture ottenute dalla response.
Il “size” della chiamata è impostato di default a 20 in modo da ottenere dalla response non più di 20 record (fatture).
Nel caso in cui siano presenti più di 20 fatture, in fondo alla response, troveremo due chiamatetag diche esempio:ne danno conferma e sono “hasNext” popolato con “true” e “continuationToken” popolato con una stringa.
Fatture Attive
Esempio:
"page": {
"size": 20,
"hasNext": true,
"continuationToken": "6g5TtcULxhoHlBd9DlTOmnTlqtnDa5Hz8zlimF7R1ahgTkS2fOYE1z3HM162btsWr8iV0xi2Pbd02nHD7XlwFX3Wtt2cA5iTxLJ07-zpwUXV1WJ9HAd9ko3t22M3tjjc"
}
Quindi dell'aziendaper Azienda/Studio ABCDEF
Fatture Passive