Guida API Fatturazione Elettronica - Keliweb SRL

{primary} Software in Cloud per la trasmissione e la ricezione di fatture elettroniche. Applicativo web con integrazione API Rest.

Benvenuto nella guida completa sulle API Rest della Fatturazione Elettronica. Qui puoi trovare tutte le informazioni necessarie sulle nostre API, inclusi concetti e formati tecnici, metodi di autenticazione, codici di errore ed esempi.

Tutte le API utilizzano il protocollo HTTPS e restituiscono risposte in formato JSON.

Quick Start

In meno di un minuto puoi fare la tua prima chiamata API. Segui questi due passi:

1. Ottieni il token di accesso

curl --location --request POST 'https://fatture.keliweb.it/oauth/token' \
--form 'grant_type="password"' \
--form 'username="tua@email.com"' \
--form 'password="tuapassword"' \
--form 'client_id="IL-TUO-CLIENT-ID"' \
--form 'client_secret="IL-TUO-CLIENT-SECRET"'

La risposta contiene il campo access_token da usare nelle chiamate successive. Il token dura 1 ora (3600 secondi).

2. Chiama il primo metodo

curl --location --request GET 'https://fatture.keliweb.it/api/invoices' \
--header 'Authorization: Bearer IL-TUO-ACCESS-TOKEN'

{info} Le credenziali ClientID e ClientSecret vengono fornite da Keliweb all'attivazione del servizio. Puoi recuperarle dalla sezione Impostazioni API dell'applicazione.

Base URL

Tutti gli endpoint API hanno come prefisso:

https://fatture.keliweb.it/api/

Rate Limiting

Le API sono soggette a un limite di 120 richieste per minuto per utente autenticato. In caso di superamento del limite, il server risponde con HTTP 429 Too Many Requests. Si consiglia di implementare una logica di retry con backoff esponenziale.

Codici di errore HTTP

Codice	Significato	Causa tipica
`200`	OK	Richiesta completata con successo
`201`	Created	Risorsa creata con successo
`400`	Bad Request	Parametri mancanti o non validi
`401`	Unauthorized	Token assente, scaduto o non valido
`403`	Forbidden	L'utente non ha i permessi per questa operazione
`404`	Not Found	La risorsa richiesta non esiste
`422`	Unprocessable Entity	Errore di validazione (es. XML malformato)
`429`	Too Many Requests	Limite di richieste superato
`500`	Internal Server Error	Errore lato server — contattare il supporto

Stati fatture inviate al Sistema di Interscambio (SDI)

Codice/Stringa	Significato	Canale	Descrizione
`PRESA IN CARICO`		PA e privati	La fattura è stata presa in carico dai sistemi di Keliweb, ma non ancora inviata al Sistema di Interscambio (SDI).
`INVIATA`		PA e privati	La fattura è stata inviata al Sistema di Interscambio (SDI).
`NON INVIATA`		PA e privati	Si è verificato un errore nell'elaborazione della fattura.
`RC`	Ricevuta Consegna	PA e privati	La fattura è stata consegnata al destinatario.
`MC`	Mancata Consegna	PA e privati	È temporaneamente impossibile recapitare la fattura al destinatario. La fattura è emessa e presente sul portale Fatture e Corrispettivi del cliente, tuttavia non è stata consegnata attraverso il metodo scelto (PEC o Codice Destinatario). Si consiglia l'invio di una copia PDF della fattura al cliente. Solo nel caso di fatture inviate a PA, verranno fatti ulteriori tentativi di consegna nei prossimi 10 giorni.
`NS`	Notifica Scarto	PA e privati	Il file fattura non ha superato i controlli previsti dal Sistema di Interscambio (SDI). La fattura è stata rifiutata dal Sistema di Interscambio (SdI) che ha restituito un codice di errore specifico.
`DT`	Decorrenza Termini	Solo PA	La fattura è stata consegnata da parte del Sistema di Interscambio (SDI), ma il destinatario non ha inoltrato alcuna risposta nei 15 giorni successivi alla consegna.
`AT`	Attestazione Trasmissione	Solo PA	Non è stato possibile recapitare la fattura al destinatario. La consegna della fattura da parte del Sistema di Intercambio (SdI) non è andata a buon fine. Non verranno effettuati ulteriori tentativi di consegna.
`EC01`	Notifica Esito	Solo PA	La fattura è stata accettata dal destinatario.
`EC02`	Notifica Esito	Solo PA	La fattura è stata rifiutata dal destinatario.