Polling
Il modo consigliato per sapere quando arriva un esito SDI o una fattura passiva sono i webhook. Se non puoi esporre un endpoint pubblico, ad esempio perché la tua integrazione è un software desktop, puoi interrogare periodicamente l'API: questa pagina spiega come farlo senza perdere eventi.
Due strategie
Puoi leggere le novità in due modi, anche combinati:
- con il filtro
unread, che restituisce solo gli elementi non ancora letti; - con una finestra temporale, che restituisce gli elementi aggiornati in un intervallo di tempo.
Filtro unread
Con unread=true ottieni solo gli elementi che non hai ancora letto. Leggerli li segna come letti, quindi alla chiamata successiva non ricompaiono. Cosa conta come lettura dipende dall'endpoint:
| Endpoint | Un elemento viene segnato come letto quando |
|---|---|
/update/ |
Compare in una risposta, in lista o nel dettaglio |
/receive/ |
Ne scarichi il contenuto: lista o dettaglio con include_payload=true, oppure /receive/{id}/payload |
Due conseguenze pratiche:
- Chiedi sempre la prima pagina. Gli elementi letti escono dal filtro, quindi la pagina 2 della chiamata successiva salterebbe degli elementi. Ripeti la richiesta di
page=1finché la risposta non è vuota. - Salva gli elementi appena li ricevi. Una volta restituiti sono già segnati come letti: se la tua elaborazione si interrompe a metà, non li ritroverai con
unread=true. Per recuperarli usa la finestra temporale.
Un solo lettore
Il filtro unread presuppone un solo lettore per account. Se più processi leggono in parallelo, ognuno riceve solo una parte degli elementi. In quel caso usa i webhook oppure la finestra temporale.
Finestra temporale
In alternativa, o come controllo di riconciliazione, interroga gli elementi aggiornati in un intervallo con last_update_from e last_update_to. Per non perdere nulla:
- fai sovrapporre le finestre: ad esempio, a ogni ciclo rileggi anche gli ultimi minuti del ciclo precedente;
- deduplica per
id: un elemento può comparire in più finestre, ma il suoidnon cambia.
Non usare l'id come cursore, cioè non chiedere solo gli elementi con id maggiore dell'ultimo visto: gli id sono assegnati in ordine crescente, ma non è garantito che diventino visibili in quell'ordine.
Frequenza
Lo SDI non lavora in tempo reale: fra un invio e il suo esito passano di solito minuti, a volte ore. Una lettura ogni 30-60 minuti è più che sufficiente. Gli endpoint di polling hanno un limite dedicato di 180 richieste al minuto.
Costi
Le letture sono gratuite, con una sola eccezione: il primo download del contenuto di una fattura ricevuta conta come transazione. Le letture successive della stessa fattura sono gratuite. Vedi Prezzi.
In Sandbox è tutto gratuito, ma ricorda che il simulatore lavora a cicli orari e che le fatture ricevute vengono eliminate ogni 24 ore.