Vai al contenuto

Changelog API

Questa pagina documenta tutte le modifiche significative all'Invoicetronic API.

v1.13.0 - 23 Aprile 2026

Novità

  • Nuovo filtro latest_state su GET /send: recupera in un'unica chiamata tutte le fatture il cui stato SDI corrente corrisponde al valore indicato (ad esempio ?latest_state=Scartato). Accetta il nome dello stato o il corrispondente valore numerico. Complementare al campo latest_state già esposto inline sui record Send, elimina la necessità di paginare e filtrare lato client.

v1.12.1 - 22 Aprile 2026

Fix

  • Corretto un bug per cui l'invio di un XML sintatticamente malformato a /send/xml poteva restituire un errore 500 anziché il 400 atteso. Ora il server risponde sempre 400 con un ProblemDetails che include il dettaglio dell'errore di parsing XML.

v1.12.0 - 21 Aprile 2026

Novità

  • Nuovo campo latest_state sulle risposte di /send (dettaglio e lista) e sull'oggetto send incluso nelle risposte /update. Espone lo stato SDI corrente della fattura direttamente sul record Send, evitando una seconda chiamata a /update per scoprirlo.
  • Il filtro multi-valore ids è ora supportato su GET /send: accetta fino a 100 id separati da virgola per recuperare più record in una sola chiamata. Utile per visualizzare lo stato di un set noto di fatture senza pattern N+1.

Fix

  • Il campo last_update su /send e i filtri last_update_from/last_update_to potevano mostrare valori obsoleti. Il campo è ora sempre allineato all'ultimo aggiornamento SDI ricevuto per la fattura.

Modifiche

  • Limite di rate limiting sugli endpoint di polling allargato: burst fino a 500 richieste istantanee e 180 richieste al minuto sostenute (prima: 200 e 60). L'header RateLimit-Policy riflette i nuovi valori sugli endpoint coinvolti. Dettagli nella guida al rate limiting.

v1.11.1 - 16 Aprile 2026

Fix

  • Risolto un problema per cui un documento XML contenente caratteri invisibili iniziali (come il BOM UTF-8) poteva non essere elaborato correttamente.

v1.10.0 - 14 Aprile 2026

Novità

  • Nuovo limite di rate limiting dedicato agli endpoint di polling. Le richieste GET su /receive, /update, /send, /log e /webhookhistory sono ora soggette a un limite aggiuntivo di 60 richieste al minuto a regime, con burst fino a 200 richieste istantanee. Il limite protegge l'API da pattern di polling in loop senza penalizzare la paginazione legittima. L'header RateLimit-Policy riflette il nuovo limite sugli endpoint coinvolti. Dettagli nella guida al rate limiting.

v1.9.1 - 14 Aprile 2026

Fix

  • Risolto un raro errore 500 Internal Server Error che poteva comparire su chiamate API altrimenti riuscite in caso di problemi transitori al sistema di logging interno. La risposta corretta della richiesta viene ora sempre restituita al client.

v1.9.0 - 12 Aprile 2026

Modifiche importanti

  • Rimosso il periodo di prova di 15 giorni sulle postazioni Desk: i nuovi checkout partono immediatamente come abbonamenti attivi, senza periodo di prova. Le chiavi API sandbox sono ora il percorso gratuito per valutare Desk — nessuna postazione richiesta, nessun limite di tempo.

v1.8.1 - 10 Aprile 2026

Novità

  • Viene ora inviata una notifica email quando la consegna di un webhook fallisce ripetutamente, per consentire la diagnosi e la correzione tempestiva dell'endpoint.

v1.8.0 - 10 Aprile 2026

Novità

  • Migliorata la resilienza e la diagnostica della consegna webhook. I tentativi falliti vengono ora ritentati automaticamente senza duplicare il log degli eventi. Ogni tentativo viene registrato nella cronologia webhook con il dettaglio dell'errore nel nuovo campo error.

v1.7.6 - 10 Aprile 2026

Documentazione

  • Il campo status_code nella cronologia webhook ora documenta il significato del valore 0: errore di rete, tipicamente causato da un endpoint malconfigurato o non più esistente.

v1.7.5 - 10 Aprile 2026

Fix

  • Migliorata la resilienza della consegna dei webhook: errori di rete (DNS irrisolvibile, timeout, connessione rifiutata) non causano più tentativi ripetuti dell'intero job. I fallimenti vengono ora registrati nella cronologia webhook con codice di stato 0.

v1.7.4 - 8 Aprile 2026

Fix

  • Risolto un problema per cui l'invio di una fattura in formato JSON (POST /send/json e POST /send/validate/json) poteva restituire un errore 500 quando uno dei campi numerici del documento veniva passato come stringa invece che come numero. Ora la risposta è un 400 chiaro che indica il campo malformato.

v1.7.3 - 8 Aprile 2026

Fix

  • Risolto un problema per cui le richieste di test eseguite dal pannello "Try It" della API Reference potevano fallire con errore 400 a causa di valori segnaposto errati che venivano inseriti automaticamente nei campi gestiti dal server.
  • L'endpoint di aggiornamento webhook (PUT /webhook/) non rifiuta più le richieste quando il riferimento all'utente nel body non coincide con l'utente autenticato: lo allinea automaticamente, come fanno già gli altri endpoint di aggiornamento.

v1.7.2 - 7 Aprile 2026

Fix

  • Risolto un problema che, dopo la cancellazione di una postazione Desk, poteva impedire l'acquisto di una nuova postazione sulla stessa chiave API. Ora la riattivazione dalla dashboard funziona correttamente.

v1.7.1 - 7 Aprile 2026

Fix

  • Corretto un problema per cui l'acquisto di una postazione Desk aggiuntiva poteva creare un nuovo profilo cliente Stripe invece di riutilizzare quello già associato all'utente.

v1.7.0 - 7 Aprile 2026

Novità

  • Postazioni Desk: nuovo modello per gestire l'accesso a Desk Cloud tramite postazioni associate alle API key, con integrazione al sistema di pagamento ricorrente. La chiave API principale include 15 giorni di prova gratuita.
  • Supporto al doppio prezzo per postazioni Desk in base al paese (Italia/estero).
  • Nuovo campo has_active_seat nella risposta di GET /status, per verificare se la chiave API ha una postazione Desk attiva.
  • Nuovo campo is_sub_key nella risposta di GET /status, per identificare le chiavi secondarie.
  • Il campo description è ora obbligatorio per la creazione di chiavi secondarie.

Fix

  • La cancellazione di una postazione Desk avviene ora a fine periodo (status canceling con current_period_end) invece che immediatamente.

v1.6.5 - 2 Aprile 2026

Fix

  • Corretto un errore per cui l'invio di XML malformato restituiva errore 500 invece del corretto 400.

v1.6.4 - 2 Aprile 2026

Fix

  • Corretta la generazione della specifica OpenAPI che produceva un requisito di sicurezza vuoto, causando la mancata autenticazione in tutti gli SDK.

v1.6.3 - 2 Aprile 2026

Fix

  • Risolto un errore che impediva la ricezione di alcune fatture elettroniche in formato P7M.

v1.6.2 - 31 Marzo 2026

Fix

  • Corretto il controllo sul limite di dimensione file (5MB) che verificava la lunghezza della stringa Base64 anziché la dimensione effettiva del file, causando falsi rifiuti su file entro il limite.

v1.6.1 - 30 Marzo 2026

Fix

  • Migliorata la robustezza della decodifica Base64 dei payload.

v1.6.0 - 30 Marzo 2026

Novità

  • Gli eventi del log ora includono il campo user_agent, che riporta lo User-Agent della richiesta HTTP. Il campo è disponibile nelle risposte di GET /log/ e filtrabile tramite query parameter.

v1.5.1 - 27 Marzo 2026

Fix

  • Corretta identificazione di payload XML senza dichiarazione <?xml>, che venivano erroneamente convertiti in Base64.

v1.5.0 - 26 Marzo 2026

Breaking Changes

  • CORS non è più aperto a tutte le origini. Le origini consentite vanno configurate per ogni API key. Se nessuna origine è configurata, le richieste cross-origin vengono bloccate dal browser. Supporto wildcard per sottodomini (es. *.example.com).

v1.4.2 - 26 Marzo 2026

Fix

  • Corretta gestione della doppia codifica Base64 su fatture P7M ricevute da SDI.

v1.4.0 - 24 Marzo 2026

Novità

  • Supporto chiavi con restrizioni. Le API key possono ora avere chiavi figlie con permessi configurabili e, opzionalmente, accesso limitato a specifiche aziende. Le chiavi con restrizioni condividono il billing con la chiave primaria e non possono creare altre chiavi figlie.

v1.3.3 - 12 Marzo 2026

Fix

  • Corretto errore 500 su POST /send e altri endpoint con transazioni, causato dall'incompatibilità tra la strategia di retry automatico su errori transienti PostgreSQL (introdotta nella v1.3.2) e le transazioni manuali.

v1.3.2 - 12 Marzo 2026

Fix

  • Corretto errore 500 su POST /send/xml quando il Content-Type include parametri (es. charset=utf-8). Il controllo ora supporta anche text/xml ed è case-insensitive.
  • Corretto errore 500 su POST/PUT quando i campi DateTime non hanno timezone esplicita. I valori non-UTC vengono ora rifiutati con errore 400.
  • Il campo created di tutte le entity viene ora gestito interamente dal server: impostato a UTC in fase di creazione e non modificabile in fase di aggiornamento.
  • Corretto errore 500 su GET /log e GET /webhookhistory quando si ordina per success. Le proprietà calcolate non mappate al database ora restituiscono errore di validazione.

v1.3.1 - 10 Marzo 2026

Fix

  • Corretto errore 500 quando il campo payload è nullo o vuoto nell'invio fattura. Ora restituisce correttamente un errore 400.

v1.3.0 - 7 Marzo 2026

Novità

  • Aggiunto campo nome_committente alle fatture inviate e nome_prestatore alle fatture ricevute. La ragione sociale viene estratta automaticamente dall'XML ed è cercabile tramite il filtro q.

v1.2.10 - 6 Marzo 2026

Fix

  • Migliorato il rilevamento delle autofatture: ora vengono riconosciute correttamente le fatture con soggetto_emittente = CC e tipo_documento = TD01, oppure con tipo_documento TD16, TD17, TD18, TD19, TD20, TD21 o TD27.
  • Aggiunta validazione: le fatture inviate senza almeno un body restituiscono ora un errore 400.

v1.2.9 - 3 Marzo 2026

Novità

  • Aggiunto supporto per il sorting per document_date (e -document_date) negli endpoint /send/ e /receive/, per ordinare le fatture in base alla data documento.

Documentazione

  • Chiarito nella documentazione dell'endpoint /update/ che l'interrogazione è gratuita e non viene conteggiata come operazione.

v1.2.8 - 2 Marzo 2026

Novità

  • Aggiunto header Retry-After sulle risposte 429 Too Many Requests, che indica al client quanti secondi attendere prima di riprovare.
  • Aggiunti header RateLimit-Limit e RateLimit-Policy su tutte le risposte API, che descrivono le finestre di rate limiting attive (al secondo, al minuto, al giorno).

v1.2.7 - 2 Marzo 2026

Novità

  • Aggiunto endpoint GET /health/ per il controllo dello stato dell'API e dei database. Non richiede autenticazione. Rate limited a 12 richieste al minuto. Restituisce 200 se tutti i servizi sono operativi, 503 se uno o più dipendenze non sono raggiungibili.

v1.2.6 - 27 Febbraio 2026

Novità

  • Aggiunta validazione del formato filename SDI per le fatture in invio. Il file_name, se fornito, deve rispettare la convenzione SDI: codice paese + id fiscale + _ + progressivo + .xml o .xml.p7m (es. IT01234567890_00001.xml).

v1.2.5 - 26 Febbraio 2026

Correzioni

  • Il parametro type dell'endpoint /export/ ora accetta valori case-insensitive (es. send, Send, SEND) e restituisce un errore chiaro per valori non validi.

v1.2.4 - 26 Febbraio 2026

Novità

  • Aggiunto parametro q per la ricerca full-text su nome, partita IVA e codice fiscale nell'endpoint di lista /company/.

v1.2.3 - 26 Febbraio 2026

Novità

  • Aggiunto parametro q per la ricerca full-text su committente, prestatore, identifier e nome file negli endpoint di lista /send/ e /receive/.

v1.2.2 - 25 Febbraio 2026

Correzioni

  • Il parametro sort degli endpoint di lista ora è case-insensitive (es. sort=name e sort=Name funzionano entrambi).

v1.2.1 - 25 Febbraio 2026

Novità

  • Aggiunto endpoint GET /company/{vat} per il recupero di un'azienda tramite partita IVA.

Correzioni

  • Aggiunto ordinamento predefinito per id alle query con paginazione per evitare risultati imprevedibili.

v1.1.6 - 24 Febbraio 2026

Correzioni

  • Le eccezioni transient di database (timeout di connessione, ecc.) ora restituiscono 503 Service Unavailable con ProblemDetails.

v1.1.5 - 23 Febbraio 2026

Novità

  • Aggiunti endpoint GET /send/{id}/payload e GET /receive/{id}/payload per ottenere solo il payload senza i metadati della fattura. L'endpoint receive marca la fattura come letta e conta l'operazione.

Correzioni

  • Le risposte GET di receive e update restituivano is_read=false anche quando la lettura li marcava come letti. Ora is_read è correttamente true nella risposta immediata.

v1.1.4 - 19 Febbraio 2026

Novità

  • La sezione API Reference ora include gli schemi delle entity (Company, Send, Receive, Update, WebHook, Event, Status) con le relative descrizioni.

v1.1.3 - 17 Febbraio 2026

Correzioni

  • Spazi nell'id_codice o codice_fiscale del XML (es. 04467630614) causavano errore 400 nella ricezione fatture. I valori vengono ora trimmati automaticamente.

v1.1.2 - 17 Febbraio 2026

Correzioni

  • Le validazioni vengono ora conteggiate correttamente nel contatore operazioni, anche quando si invia con ?validate=true.

v1.1.1 - 16 Febbraio 2026

Correzioni

  • XML malformato ora restituisce 400 Bad Request invece di 500 Internal Server Error su tutti gli endpoint di invio e validazione.
  • Il messaggio di errore per partita IVA non trovata ora include la partita IVA estratta dall'XML.
  • Il filtro prestatore sulle query /update/ veniva ignorato. Ora filtra correttamente tramite la fattura inviata collegata.

v1.1.0 - 13 Febbraio 2026

Novità

  • Aggiunto endpoint GET /export/ per esportare fatture inviate e ricevute come archivio ZIP di file XML FatturaPA. Supporta filtri per azienda, periodo (mese/trimestre) e range di date documento. Le fatture inviate vengono incluse solo se in stato definitivo.

Correzioni

  • Le fatture ricevute (Receive) vengono ora conteggiate come operazione solo se non ancora lette.

v1.0.27 - 6 Febbraio 2026

Correzioni

  • Il campo date_sent dei documenti inviati (Send) viene ora aggiornato correttamente.

Documentazione

  • Aggiunta tabella valori enum State nella documentazione Update con descrizioni dettagliate.
  • Aggiunta nota sull'importanza di monitorare lo stato dei documenti inviati.

v1.0.26 - 5 Febbraio 2026

Novità

  • L'endpoint DELETE /company/{id} ora richiede il parametro ?force=true se esistono fatture collegate alla company. Senza il parametro, ritorna 409 Conflict con i dettagli delle fatture esistenti.

v1.0.25 - 3 Febbraio 2026

Correzioni

  • Il campo is_read nelle fatture ricevute (receive) viene ora impostato solo quando include_payload=true, sia per GET singolo che per lista.

Documentazione

  • Aggiornate le descrizioni degli endpoint receive per documentare il nuovo comportamento di is_read.
  • Corretti typo nelle descrizioni dei modelli.

v1.0.24 - 2 Febbraio 2026

Correzioni

  • Migliorato il log degli eventi.

v1.0.23 - 2 Febbraio 2026

Correzioni

  • Corretta la decodifica base64 nell'autenticazione Basic Auth che poteva causare il fallimento del login quando le credenziali venivano codificate senza il separatore colon (es. Base64(api_key) invece di Base64(api_key:)).

v1.0.22 - 18 Gennaio 2026

Miglioramenti

Documentazione API migliorata

Aggiunte descrizioni complete a tutti gli endpoint API con informazioni dettagliate su: - Descrizione di ogni entità (send, receive, update, company, log, webhook, status) - Periodi di retention dei dati - Filtri disponibili per le ricerche - Link alla Dashboard per la gestione delle risorse - Link alla documentazione Sandbox e Webhooks

v1.0.21 - 5 Gennaio 2026

Novità

Supporto per la lingua tedesca

Aggiunto il supporto completo per la lingua tedesca (de) nell'header Accept-Language. Tutti i messaggi di errore e validazione sono ora disponibili in tre lingue: - Accept-Language: it - Messaggi in italiano (predefinito) - Accept-Language: en - Messaggi in inglese - Accept-Language: de - Messaggi in tedesco

Le varianti regionali sono supportate e mappate automaticamente alla lingua base (es. de-DE, de-AT, de-CH → de). Per maggiori dettagli, consulta la documentazione sulla localizzazione.

v1.0.20 - 4 Gennaio 2026

Modifiche Breaking

Header di localizzazione - Migrazione a Accept-Language

L'header di localizzazione è stato migrato dall'header custom Invoicetronic-Language all'header HTTP standard Accept-Language (RFC 7231). Per maggiori dettagli, consulta la documentazione sulla localizzazione.

Azione richiesta: I client devono aggiornare le loro integrazioni per usare l'header Accept-Language invece di Invoicetronic-Language: - Prima: Invoicetronic-Language: it - Ora: Accept-Language: it

L'header custom Invoicetronic-Language non è più supportato. La lingua predefinita è ora italiano (in precedenza era inglese).

Novità

Supporto multi-lingua completo

Tutti i messaggi di errore di validazione sono ora disponibili in italiano e inglese. L'API risponde nella lingua specificata nell'header Accept-Language: - Accept-Language: it - Messaggi in italiano - Accept-Language: en - Messaggi in inglese

Se l'header è assente o contiene una lingua non supportata, l'API risponderà in italiano. Lingue attualmente supportate: italiano (it), inglese (en).

v1.0.19 - 2 Gennaio 2026

Correzioni

Log errori - Campo error più leggibile

Migliorato il campo error nei log per mostrare solo il messaggio di errore effettivo invece dell'intera risposta JSON. Il campo ora contiene il messaggio reale (es. "vat is required") invece del wrapper JSON completo, rendendo i log più leggibili. In caso di errori ProblemDetails, viene estratto il campo detail, altrimenti viene usato il campo title o, per risposte non-ProblemDetails, la risposta grezza (troncata a 500 caratteri).

v1.0.18 - 1 Gennaio 2026

Correzioni

Validazione campi obbligatori

Corretta la validazione dei campi obbligatori per restituire 400 Bad Request invece di 500 Internal Server Error quando i campi vat, fiscal_code, name (Company) o payload (Send/Receive) sono null. Questi campi erano già contrassegnati come obbligatori nel contratto API e nella specifica OpenAPI, ma la validazione non era correttamente applicata a runtime.

v1.0.16 - 9 Dicembre 2025

Modifiche

Invio fatture - Auto-compilazione DatiTrasmissione

Quando si invia una fattura senza specificare il campo file_name, il sistema ora aggiorna automaticamente i campi DatiTrasmissione nel XML se sono vuoti: - IdTrasmittente.IdPaese viene impostato a "IT" - IdTrasmittente.IdCodice viene impostato a "01180680397" (P.IVA Invoicetronic) - ProgressivoInvio viene impostato al contatore Base36 auto-generato

In precedenza, veniva generato solo il nome del file ma il contenuto XML rimaneva invariato. Questa modifica garantisce coerenza tra il nome del file e la struttura XML. I valori esistenti non vuoti vengono sempre preservati e mai sovrascritti.

v1.0.15 - 6 Dicembre 2025

Novità

Header Invoicetronic-Version

Aggiunto l'header Invoicetronic-Version a tutte le risposte API. I client possono ora verificare la versione dell'API e rilevare aggiornamenti leggendo questo header da qualsiasi risposta. Il numero di versione corrisponde alla versione di release dell'API (es. "1.0.15").

v1.0.14 - 6 Dicembre 2025

Correzioni

Webhook - Codifica payload

Corretta la codifica del payload webhook da UTF-16 a UTF-8 per la corretta verifica della firma HMAC. Il payload HTTP del webhook veniva inviato con Encoding.Unicode (UTF-16LE) mentre la firma HMAC veniva calcolata usando la codifica ASCII, rendendo difficile per i client verificare la firma. Ora sia il payload che il calcolo HMAC utilizzano la codifica UTF-8, che è lo standard per i payload JSON e garantisce una verifica coerente della firma.

v1.0.13 - 5 Dicembre 2025

Correzioni

Webhook - Supporto evento wildcard

Corretto il supporto per l'evento wildcard (*) nei webhook. I webhook configurati con l'evento * venivano accettati durante la creazione ma non venivano mai attivati. Ora i webhook con * nella lista degli eventi vengono correttamente attivati per tutti gli eventi.

v1.0.12 - 4 Dicembre 2025

Novità

Webhook - Campo resource_id

Aggiunto il campo resource_id alle notifiche webhook. I payload webhook ora includono l'ID della risorsa creata o modificata dalla richiesta.

Per esempio, per gli eventi update.add, il campo resource_id contiene l'ID dell'entità Update appena creata. Questo permette ai ricevitori webhook di recuperare direttamente i dettagli della risorsa senza dover fare matching basato su timestamp o altre euristiche.

v1.0.9 - 4 Dicembre 2025

Correzioni

Notifiche webhook per receive.add e update.add

Corretta un'anomalia che impediva l'invio corretto delle notifiche webhook per gli eventi receive.add e update.add. I webhook vengono ora attivati correttamente per il proprietario della risorsa.

v1.0.7 - 3 Dicembre 2025

Correzioni

Notifiche webhook con company_id null

Corretto un problema che impediva l'invio delle notifiche webhook quando la risposta API conteneva un valore company_id null. Ora i webhook vengono correttamente inviati anche in questi casi.

v1.0.0 - 14 Luglio 2025

Novità

Prima release ufficiale di Invoicetronic API.