Se programmi in PHP

Se stai sviluppando in PHP, ti consigliamo di scaricare la nostra libreria già pronta: https://github.com/clixclix2/Fattura-Elettronica-API-PHP-Client, corredata di esempi di utilizzo.

Premessa tecnica

Il nostro servizio API v.1.0 si basa su semplici chiamate HTTPS in POST al nostro endpoint.

Ogni chiamata contiene nel body una stringa in formato JSON e riceve in risposta una stringa in formato JSON

URL endpoint API:

https://fattura-elettronica-api.it/ws1.0/

1. Autenticazione

Prima di poter chiamare le API, è necessario ottenere un token di autenticazione.

Richiesta

{
    "action":   "AUTH",
    "username": "[username]",
    "password": "[password]"
}

Risposta

{
    "ack":   "OK",
    "token": "[token]"
}

Il token ottenuto ha una validità di circa 12 ore e va utilizzato in tutte le successive chiamate API. Possono essere richiesti infiniti token.

Risposta in caso di errore (formato valido per tutte le chiamate API):

{
    "ack":   "KO",
    "error": "[messaggio]"
}

2. Trasmissione di una fattura XML

Richiesta

{
    "action": "SEND",
    "token":  "[token]",
    "file":   "[la stringa xml contenente la fattura elettronica]",
    "test":   0|1 // opzionale
}

Il documento viene trasmesso al SDI in modalità sincrona e viene ritornato l'identificativo trasmissione assegnato dal SDI.

Nota: in modalità di test i documenti non vengono inoltrati al SDI, ma vengono ritornati come nuove fatture ricevute in modalità di test

Risposta

{
    "ack": "OK",
    "data": {
        "id":                 [identificativo univoco numerico fattura-elettronica-api],
        "sdi_identificativo": [identificativo trasmissione fornito dal SDI, numerico, oppure null],
        "sdi_nome_file":      "[il nome del file trasmesso]",
        "sdi_fattura":        "[il documento xml effettivamente trasmesso]",
        "sdi_stato":          "[INVI|ERRO]", -- INVI=Inviato, ERRO=Errore
        "sdi_messaggio":      "[eventuale messaggio]"
    }
}

Nota: il file XML effettivamente trasmesso differisce da quello ricevuto per l'applicazione, nella sezione FatturaElettronicaHeader, dei dati di trasmissione corretti (soggetto che effettua la trasmissione. progressivo, etc.)

Nota: se sdi_identificativo ritorna null e sdi_stato è "INVI", vuol dire che il sistema ha preso in carico la trasmissione senza riuscire a fornire subito il l'identificativo SDI, che verrà quindi ricevuto al momento della ricezione degli aggiornamenti di spedizione

3. Ricezione delle fatture e degli aggiornamenti di trasmissione

Il sistema ritornerà tutte le fatture ricevute e gli aggiornamenti sullo stato di spedizione delle fatture.
In assenza di almeno uno tra i parametri opzionali date_from, date_to, sdi_id_from, sdi_id_to, sdi_id, verranno reinviati solo aggiornamenti che non siano già stati trasmessi.

Richiesta

{
    "action":      "RECV",
    "token":       "[token]",

    "date_from":   "[data aggiornamento di partenza, formato 'yyyy-mm-dd hh:mm:ss' oppure 'yyyy-mm-dd']", // opzionale
    "date_to":     "[data aggiornamento finale, formato 'yyyy-mm-dd hh:mm:ss' oppure 'yyyy-mm-dd']", // opzionale
    "sdi_id_from": [identificativo sdi di partenza], // opzionale
    "sdi_id_to":   [identificativo sdi finale], // opzionale
    "sdi_id":      [identificativo sdi], // opzionale
    "id_from":     [id di partenza], // opzionale
    "id_to":       [id finale], // opzionale
    "id":          [id], // opzionale
    "test":        0|1 // opzionale
}

Nota: in modalità di test il sistema ritorna eventuali documenti ricevuti in modalità di test

Risposta

{
    "ack": "OK",
    "data": [
        {
            "ricezione": 1,
            "id":                     [identificativo univoco numerico fattura-elettronica-api],
            "sdi_fattura":            "[documento originale (con eventuale firma digitale del mittente) - codificato in base64]",
            "sdi_fattura_xml":        "[documento decodificato da eventuali firme digitali]",
            "sdi_identificativo":     [identificativo trasmissione del SDI, numerico],
            "sdi_data_aggiornamento": "[data ultimo aggiornamento - formato yyyy-mm-dd hh:mm:ss]",
            "sdi_messaggio":          "[eventuale messaggio dal SDI]",
            "sdi_nome_file":          "[nome del file ricevuto]"
        },
        ...
        {
            "ricezione": 0,
            "id":                     [identificativo univoco numerico fattura-elettronica-api],
            "sdi_identificativo":     [identificativo SDI della fattura trasmessa, numerico],
            "sdi_stato":              "INVI"|"ERRO"|"CONS"|"NONC"  per fatture inviate alla Pubblica Amministrazione: "ACCE"|"RIFI"|"DECO",
            "sdi_messaggio":          "[eventuale messaggio dal SDI]",
        },
        ...
    ]
}

Nota: il metodo ritorna sia le nuove fatture ricevute (righe con ricezione=1) sia gli aggiornamenti sulla trasmissione delle fatture (righe con ricezione=0)

Legenda stati: "INVI"=Inviato, "ERRO"=Errore (vedere messaggio), "CONS"=Consegnato, "NONC"=Non Consegnato (ma il mittente ha comunque ottemperato al suo obbligo),
Solo per le fatture inviate alla Pubblica Amministrazione: "ACCE"=Accettato, "RIFI"=Rifiutato, "DECO"=Decorrenza termini, ovvero accettazione implicita

4. Ricezione delle fatture e degli aggiornamenti di trasmissione via Webhook

Configurando l'apposito campo Webhook nel gestionale (URL e Token), è possibile ottenere lo stesso json in modalità push.

All'arrivo di uno o più aggiornamenti dal SDI, il sistema invocherà subito il Webhook eventualmente configurato, trasmettendo in post nel body il json con lo stesso formato dei dati sopra indicato (limitato al campo "data").

Per validare la chiamata, la richiesta conterrà un header http di questo tipo: "Authorization: Bearer [token]" dove [token] sarà il valore da te inserito nel gestionale.

Alla ricezione di una risposta http senza errori (codice risposta http 200), il sistema riterrà consegnati i relativi aggiornamenti.

In caso di ricezione di un errore, il sistema tenterà invii successivi distanziati di 3 ore, fino ad un massimo di 3 giorni di tentativi