Documentazione

apidesk API v3 - Documentazione tecnica

apidesk è un Hub di servizi, tra i quali la spedizione e la ricezione delle fatture elettroniche a/da privati e pubblica amministrazione.

Autenticazione e Login

Ogni account abilitato all'utilizzo delle API dispone di una Bridge key e di una password.

Tutte le chiamate devono includere un Basic authentication header generato da tali credenziali, ad esempio con:

Bridge Key: test_12345678901234567890
Password: 123456

L'header da inviare sarà:

Authorization: Basic dGVzdF8xMjM0NTY3ODkwMTIzNDU2Nzg5MDoxMjM0NTY=

Tutte gli endpoint rispondono con un opportuno stato HTTP ed un JSON nella forma:

{
    "result": mixed,               // risultato della richiesta
    "code": int                     // codice del risultato
}

In caso di successo lo status HTTP sarà 200e il valore della sezione code sarà 0

Corrispettivi elettronici

Tutte le richieste ai metodi dei corrispettivi dovranno essere inviate come multipart/form-data seguendo i metodi http indicati e i relativi dati da fornire.

Recupero configurazione

Recupera la configurazione corrente per il servizio Corrispettivi. Non è necessario passare nessun dato.

GET https://www.uniwix.com/api/Corrispettivo/Configurazione

Risposta di successo:

{
  "result": {
    "fisconline_tipoutenza": "1",
    "fisconline_user": "username_fisconline",
    "fisconline_pass": "password_fisconline",
    "fisconline_pincode": "pincode_fisconline",
    "fisconline_utenza1": "01234567890",
    "updated_at": "2023-10-22 10:30:00"
  },
  "code": 1
}

Crea configurazione

POST    https://www.uniwix.com/api/Corrispettivo/Configurazione

Crea la configurazione per il servizio Corrispettivi.

Parametri:

Parametro Tipo Obbligatorio Descrizione
fisconline_tipoutenza string Si Tipo di utenza Fisconline (0=Incaricato, 1=Me Stesso). Default: 1.
fisconline_user string Si Username dell'utente Fisconline.
fisconline_pass string Si Password dell'utente Fisconline.
fisconline_pincode string Si Pincode dell'utente Fisconline.
fisconline_utenza1 string Si Partita IVA del soggetto emittente.
fisconline_email string Si Email del soggetto emittente.
fisconline_azienda string Si Azienda del soggetto emittente.

ATTENZIONE: email ed azienda dopo la creazione non possono essere più modificate.

Esempio di richiesta:

  "fisconline_tipoutenza": "1"
  "fisconline_user": "mio_user"
  "fisconline_pass": "mia_password"
  "fisconline_pincode": "1234567890"
  "fisconline_utenza1": "01234567890"
  "fisconline_email": "azienda@azienda.it"
  "fisconline_azienda": "Azienda S.R.L."

Risposta: Restituisce la configurazione aggiornata, come per GET Configurazione.

Modifica configurazione

PATCH   https://www.uniwix.com/api/Corrispettivo/Configurazione

Aggiorna la configurazione per il servizio Corrispettivi.

Parametri:

Parametro Tipo Obbligatorio Descrizione
fisconline_tipoutenza string Si Tipo di utenza Fisconline (0=Incaricato, 1=Me Stesso). Default: 1.
fisconline_user string Si Username dell'utente Fisconline.
fisconline_pass string Si Password dell'utente Fisconline.
fisconline_pincode string Si Pincode dell'utente Fisconline.
fisconline_utenza1 string Si Partita IVA del soggetto emittente.

Esempio di richiesta:

  "fisconline_tipoutenza": "1"
  "fisconline_user": "mio_user"
  "fisconline_pass": "mia_password"
  "fisconline_pincode": "1234567890"
  "fisconline_utenza1": "01234567890"

Risposta: Restituisce la configurazione aggiornata, come per GET Configurazione.

Chiamate Corrispettivi

Qui di seguito trovate le tre chiamate per i corrispettivi elettronici:

Invio corrispettivo

Invia un nuovo corrispettivo elettronico al sistema dell'Agenzia delle Entrate. 

POST    https://www.uniwix.com/api/Corrispettivo/invio

Parametri:

Parametro Tipo Obbligatorio Descrizione
tipo_pagamento string No Tipo di pagamento. Valori: contante, elettronico, mixed. Default: contante.
articoli array Sì Elenco degli articoli del corrispettivo.
sconto_abbuono number No Importo totale dello sconto o abbuono applicato al documento.

Parametri per ogni articolo (array articoli):

Parametro Tipo Obbligatorio Descrizione
quantita number No Quantità del prodotto. Default: 1.
descrizione string No Descrizione del prodotto. Default: Articolo.
prezzo_lordo number No Prezzo unitario del prodotto (IVA inclusa).
aliquota_iva number No Aliquota IVA in percentuale. Default: 22.
sconto_lordo number No Sconto applicato per singola unità.
sku number No Codice dell'articolo.

Se il prezzo è 0, verrà dichiarato automaticamente come complemetary (free)

Parametri per pagamento mixed (almeno uno deve essere inviato):

Parametro Tipo Obbligatorio Descrizione
contanti number No Importo pagato in contanti. Default: 0.
elettronico number No Importo pagato elettronicamente. Default: 0.
ticket_restaurant number No Importo pagato con il ticket restaurant (Il valore non si intende per il valore singolo, ma per l'importo complessivo). Default: 0.
ticket_restaurant_qta number No Numero di buoni pasto utilizzati. Default: 0.

Esempio di richiesta: 

tipo_pagamento: mixed
mixed['ticket_restaurant_qta']: 4
mixed['ticket_restaurant']: 20
mixed['elettronico']: 25
articoli[0][quantita]: 2
articoli[0][descrizione]: Prodotto A
articoli[0][prezzo_lordo]: 10.00
articoli[0][aliquota_iva]: 22
articoli[0][sconto_lordo]: 0
articoli[1][quantita]: 1
articoli[1][descrizione]: Prodotto B
articoli[1][prezzo_lordo]: 25.00
articoli[1][aliquota_iva]: 22
articoli[1][sconto_lordo]: 0
sconto_abbuono: 0

Risposta di successo:

{
  "result": {
    "codice": "Ok",
    "descrizione": "Documento inviato con successo.",
    "esito": 0,
    "messaggio": {
      "esito": true,
      "progressivo": "69403b5e81a1abbf2e085e73",
      "errori": []
    },
    "code": 1
  }
}

Annulla corrispettivo

Annulla un corrispettivo elettronico precedentemente inviato. 

POST    https://www.uniwix.com/api/Corrispettivo/annullo

Parametri:

Parametro Tipo Obbligatorio Descrizione
progressivoSdi string Sì Progressivo del documento commerciale da annullare.

Esempio di richiesta:

  "progressivoSdi": "12345"

Risposta di successo: 

{
    "result": {
        "data": {
            "fiscal_id": "01635330887",
            "items": [
                {
                    "quantity": 2,
                    "description": "Articolo",
                    "unit_price": 0.02459016,
                    "vat_rate_code": "22",
                    "complimentary": false,
                    "discount": 0,
                    "sku": "",
                    "gross_discount": 0,
                    "gross_price": 0.03,
                    "id": "150253",
                    "return": 0,
                    "taxable_amount": 0.04918033,
                    "net_taxable_amount": 0.04918033,
                    "vat_amount": 0.01081967,
                    "unit_discount": 0,
                    "total_amount": 0.06
                }
            ],
            "cash_payment_amount": 0.06,
            "id": "6942bb57b3948e43dc0af0a3",
            "invoice_issuing": false,
            "services_uncollected_amount": 0,
            "goods_uncollected_amount": 0,
            "electronic_payment_amount": 0,
            "ticket_restaurant_payment_amount": 0,
            "ticket_restaurant_quantity": 0,
            "discount": 0,
            "linked_receipt": null,
            "lottery_code": null,
            "created_at": "2025-12-17T14:16:55.000Z",
            "error_message": null,
            "error_code": null,
            "total_amount": 0.06,
            "document_number": "",
            "document_date": null,
            "transaction_id": null,
            "create_timestamp": 1765981014,
            "parent_receipt_id": "69403b46d7c965052f0e1c63",
            "status": "new",
            "total_discount": 0,
            "total_gross_discount": 0,
            "total_taxable_amount": 0,
            "total_uncollected_amount": 0,
            "total_vat_amount": 0,
            "deductible_amount": 0,
            "type": "void",
            "tags": null
        },
        "message": "voided receipt:69403b46d7c965052f0e1c63",
        "success": true,
        "error": null
    },
    "code": 0
}

Lista corrispettivo

Recupera la lista dei corrispettivi elettronici dal cassetto fiscale o dal gestionale. 

POST    https://www.uniwix.com/api/Corrispettivo/lista

Parametri:

Parametro Tipo Obbligatorio Descrizione
dataDal string No Data di inizio ricerca (formato: YYYY-MM-DD). Default: giorno corrente.
dataAl string No Data di fine ricerca (formato: YYYY-MM-DD). Default: giorno corrente.

Esempio di richiesta:

  "dataDal": "2023-10-01",
  "dataAl": "2023-10-31",

Risposta di successo: 

{
    "result": [
        {
            "fiscal_id": "0123456789",
            "items": [
                {
                    "quantity": "2",
                    "description": "Articolo",
                    "unit_price": "0.03",
                    "vat_rate_code": "22",
                    "complimentary": false,
                    "discount": 0,
                    "sku": ""
                }
            ],
            "cash_payment_amount": 0.06,
            "id": "69403b5e81a1abbf2e085e73",
            "invoice_issuing": false,
            "services_uncollected_amount": 0,
            "goods_uncollected_amount": 0,
            "electronic_payment_amount": 0,
            "ticket_restaurant_payment_amount": 0,
            "ticket_restaurant_quantity": 0,
            "discount": 0,
            "linked_receipt": null,
            "lottery_code": null,
            "created_at": "2025-12-15T16:46:21.000Z",
            "error_message": null,
            "error_code": null,
            "total_amount": 0.06,
            "document_number": "",
            "document_date": null,
            "transaction_id": null,
            "create_timestamp": 1765817181,
            "status": "new",
            "total_discount": 0,
            "total_gross_discount": 0,
            "total_taxable_amount": 0,
            "total_uncollected_amount": 0,
            "total_vat_amount": 0,
            "deductible_amount": 0,
            "type": "sale",
            "tags": null
        },
        {
            "fiscal_id": "01635330887",
            "items": [
                {
                    "quantity": 2,
                    "description": "Articolo",
                    "unit_price": 0.02459016,
                    "vat_rate_code": "22",
                    "complimentary": false,
                    "discount": 0,
                    "sku": "",
                    "gross_discount": 0,
                    "gross_price": 0.03,
                    "id": "150253",
                    "return": 0,
                    "taxable_amount": 0.04918033,
                    "net_taxable_amount": 0.04918033,
                    "vat_amount": 0.01081967,
                    "unit_discount": 0,
                    "total_amount": 0.06
                }
            ],
            "cash_payment_amount": 0.06,
            "id": "6942bb57b3948e43dc0af0a3", //Il nuovo id univoco dell'annullo viene inserito qui
            "invoice_issuing": false,
            "services_uncollected_amount": 0,
            "goods_uncollected_amount": 0,
            "electronic_payment_amount": 0,
            "ticket_restaurant_payment_amount": 0,
            "ticket_restaurant_quantity": 0,
            "discount": 0,
            "linked_receipt": null,
            "lottery_code": null,
            "created_at": "2025-12-17T14:16:55.000Z",
            "error_message": null,
            "error_code": null,
            "total_amount": 0.06,
            "document_number": "",
            "document_date": null,
            "transaction_id": null,
            "create_timestamp": 1765981014,
            "parent_receipt_id": "69403b46d7c965052f0e1c63", //In caso di annullo, il precedente id univoco del documento viene inserito qui
            "status": "new",
            "total_discount": 0,
            "total_gross_discount": 0,
            "total_taxable_amount": 0,
            "total_uncollected_amount": 0,
            "total_vat_amount": 0,
            "deductible_amount": 0,
            "type": "void",
            "tags": null
        },
        ........
    ],
    "code": 0
}

Note Importanti

  • Autenticazione: Tutte le chiamate ai corrispettivi utilizzano le credenziali configurate tramite Configurazione_POST.
  • Formato Date: Le date nei parametri devono essere nel formato YYYY-MM-DD. La data del documento (dataDoc) viene generata automaticamente in formato yyyy-MM-ddTHH:mm:ss.
  • Limiti di Ricerca: Per la chiamata Corrispettivo_lista, l'intervallo tra dataDal e dataAl non può superare i 31 giorni.
  • Codici di Esito: Nelle risposte, esito: 0 indica sempre un'operazione andata a buon fine. Qualsiasi altro valore indica un errore.

Fatture elettroniche

Invio fattura XML

L'endpoint da chiamare per inviare una fattura XML all'SdI è:

POST    https://www.uniwix.com/api/Uniwix/Invoices/Upload

Il nome del file XML da inviare deve avere il formato:

IT PIVA _ PROGRESSIVO .xml

dove:

  • PIVA è la partita iva del prestatore, di 11 cifre
  • PROGRESSIVO è un codice alfanumerico progressivo, univoco per ogni invio. Deve essere di almeno 1 carattere.

Il nome del file privo della sua estensione è un identificativo della fattura, di seguito indicato col nome di FID, utile per ottenere la cronologia degli stati di una fattura, o scaricarne l'esito.

Ad esempio:

IT12345678901_A0001.xml  =>  FID: IT12345678901_A0001

Il file XML va inviato come parametro fattura. Il body del POST deve avere la codifica multipart/form-data.

In caso di successo le API rispondono con uno stato HTTP 200 e un JSON nella forma:

{
    "result": {
        "id": 482313,
        "tipo": 3,
        "fid": "IT12345678901_A0001",
        "data": "2019-05-12",
        "msg": "Uploading in FTP...",
        "anagrafica": "Acme spa",
        "doc_number": "A1003/19",
        "totale": "20.74",
        "stato": null,
        "stato_sdi": null
    },
    "code": 0
}

La sezione result riporta lo stato corrente della fattura appena caricata. Per maggiori dettagli vedere il paragrafo Stati delle fatture. In caso di fallimento verrà resituito un codice di errore, come indicato nella sezione Codici di errore.

Invio fattura da tracciato (versione semplificata)

L'endpoint da chiamare per inviare una fattura mediante tracciato è:

POST    https://www.uniwix.com/api/Uniwix/Invoices/UploadData

Il tracciato ha la seguente struttura

{
    "data": "2024-10-19",                       // Data della fattura
    "num_documento": "000001/TEST",             // Numero del documento
    "anagrafica": {                             // Sezione anagrafica
        "descrizione": "Acme srl",              // Nome del destinatario
        "piva": "12345678902",                  
        "indirizzo": "Via Roma, 100",           
        "citta": "Roma",
        "provincia": "RM",
        "cap": "00100",
        "stato": "IT",
        "cod_ufficio": "ABCDEFG"                // Cod. destinatario
    },
    "articoli": [
        {
            "nome": "Prodotto di prova",        // Nome della merce/servizio indicato in fattura
            "qta": "1",                         // Quantità indicata
            "prezzo": "10.50",                  // Prezzo imponibile
            "iva": "10"                         // Percentuale iva
        }
    ],
    "cod_pagamento": "MP05"                     // Codice del metodo di pagamento associato
}

e va passato come RAW POST. La risposta dell'endpoint è uguale a quella descritta per l'upload XML.

Stati fatture attive

Per richiedere gli stati delle fatture attive, la chiamata HTTP da fare è:

GET https://www.uniwix.com/api/Uniwix/Invoices/Attive

La risposta è il JSON nella forma standard già documentata. La sezione result è questa volta un array di tutti gli stati delle fatture. L'array degli stati è ordinato per data documento e data ricezione/spedizione, in ordine descrescente. La richiesta consente di specificare una serie di filtri e la paginazione.

Filtri e paginazione

I filtri disponibili sono:

  • dal: (date) in formato ISO, se specificato mostra gli stati con data successiva al valore passato.
  • al: (date) come dal, mostra gli stati con data fino al valore passato.
  • last: (int) mostra gli stati con id maggiore del valore passato.
  • row: (int) mostra lo stato con id uguale al valore passato.

La paginazione si abilita valorizzando il parametro page. I parametri sono:

  • page: (int) il numero di pagina da richiedere. 0 è la prima pagina, con i risultati più recenti.
  • pagesize: (int) la dimensione di ogni pagina, nell'intervallo [10,1000], default 25.

Nel caso in cui venga richiesta la paginazione dei risultati (fortemente consigliato) il JSON di risposta avrà questa forma:

{
    "result": {
        "records": 7390,
        "pagesize": 25,
        "pages": 296,
        "page": 0,
        "data": [
...

Dove:

  • records: (int) numero totale di stati.
  • pagesize: (int) numero di record per pagina
  • pages: (int) numero di pagine
  • page: (int) pagina corrente
  • data: (array) array degli stati

Stati fatture passive

L'endpoint è:

GET https://www.uniwix.com/api/Uniwix/Invoices/Passive

Filtri, paginazione e stati di ritorno sono uguali a quelli indicati nella sezione Stati fatture attive

Stati singola fattura

E' possibile richiedere la lista completa degli stati di una specifica fattura, identificata dal FID, con la chiamata:

GET https://www.uniwix.com/api/Uniwix/Invoices/FID

In alternativa, si può richiedere un singolo stato, indicandone l'ID:

GET https://www.uniwix.com/api/Uniwix/Invoices/ID

Download fattura

GET https://www.uniwix.com/api/Uniwix/Invoices/FID_O_ID/Download

Questo endpoint consente il download del file identificato dal FID o in alternativa dall'id di uno stato specifico indicato nell'url. Passando il valore di un FID, il sistema avvia il download del documento di fattura collegato. Passando invece il valore di un id, il sistema avvia il download del file relativo allo specifico stato. Ad esempio, per una fattura attiva della quale esiste anche uno stato SdI, è possibile scaricare il documento XML originario passando semplicemente il FID, mentre per scaricare il file XML inviato dall'SdI, è possibile indicare il valore dell'id dello stato corrispondente.

Stati delle fatture

Ogni fattura è caratterizzata da una lista contenente almeno uno stato. La struttura di uno stato è la seguente:

  • id: (int) è un identificativo interno del singolo stato della fattura
  • tipo: (int) indica il tipo di fattura e può valere:
    • 1: Fattura ATTIVA alla PA
    • 3: Fattura ATTIVA a privato
    • 4: Fattura PASSIVA
  • fid: (string) il FID associato alla fattura
  • data: (date) la data della fattura, come riportato nell'XML
  • data_ricezione: (date) la data di ricezione della fattura passiva. In caso di fattura attiva, questo campo riporta la data di spedizione
  • anagrafica: (string) il nome del cliente/fornitore indicato in fattura
  • doc_number: (string) il numero documento, come riportato nell'XML
  • totale: (float) l'importo totale della fattura
  • stato: (int) lo stato in cui si trova la fattura
    • null: fattura presa in carico dal sistema, in attesa di essere inviata all'SdI
    • 1: fattura inviata all'SdI
    • 5: notifica ricevuta dall'SdI. I dettagli sul tipo di notifica ricevuta sono riportati sul campo stato_sdi
    • 9: fattura passiva ricevuta
  • stato_sdi: (string) riporta il codice di notifica SdI, come da specifiche dell'Agenzia delle Entrate:
    • RC: Ricevuta di consegna
    • NS: Notifica di scarto
    • MC: Notifica di mancata consegna
    • NE: Notifica esito cedente / prestatore
    • MT: File dei metadati
    • EC: Notifica di esito cessionario / committente
    • SE: Notifica di scarto esito cessionario / committente
    • DT: Notifica decorrenza termini
    • AT: Attestazione di avvenuta trasmissione della fattura con impossibilità di recapito
  • msg: (string) riporta lo stato corrente in formato testuale

Codici di errore

In caso di fallimento verrà resituito uno stato HTTP differente da 200 e un JSON nella forma

{
    "result": mixed,               // descrizione dell'errore
    "code": int                     // codice errore
}

L'elenco dei possibili codici di errore è:

  • -1: File XML vuoto o non specificato (stato HTTP 400)
  • -2: Errore nell'invio del file XML (stato HTTP 400)
  • -3: Formato file non supportato (stato HTTP 400)
  • -4: Credito insufficiente (stato HTTP 402)
  • -5: Errore nel caricamento del file XML (stato HTTP 500)
  • -6: Identificativo fattura non trovato (stato HTTP 404)
  • -7: Stato fattura non trovato (stato HTTP 404)
  • -8: L'url indicato non contiene la macro obbligatoria #URL# (stato HTTP 400)
  • -9: Metodo non valido (stato HTTP 405)
  • -10: File non disponibile per questo stato (stato HTTP 404)
  • -11: ["message":"Errore di validazione", "errors":[errori]] (stato HTTP 400)
  • -12: File già presente nella coda (stato HTTP 409)
  • -13: Delega mancante (stato HTTP 403)
  • -15: File già caricato (stato HTTP 409)
  • -16: Allegato non trovato (stato HTTP 404)
  • -17: File non trovato (stato HTTP 404)
  • -18: P.iva prestatore non valida (stato HTTP 406)
  • -19: Configurazione richiesta mancante (stato HTTP 500)
  • -20: Fattura duplicata (stato HTTP 409)

Recupero dati azienda da P.IVA

Per richiedere i dati di un'azienda va usato il seguente endpoint, indicando la PIVA da cercare:

GET    https://www.uniwix.com/api/Uniwix/companyDetails/PIVA

In caso di successo lo status HTTP sarà 200 e verrà restituito un JSON nella forma:

{
    "result": {
        "denominazione": "Acme Spa",
        "piva": "12345678901",
        "cf": "12345678901",
        "codice_destinatario": "ABCDEFG",
        "indirizzo": "VIA ROMA 100",
        "cap": "00143",
        "comune": "ROMA",
        "frazione": null,
        "provincia": "RM",
        "stato_attivita": "ATTIVA"
    },
    "code": 0
}

In caso di errore lo status HTTP sarà 400, il valore della sezione code sarà -1 e la sezione result conterrà il messaggio di errore, ad es.:

{
    "result": "cf/piva not valid",
    "code": -1
}

Statistiche di utilizzo

Per richiedere le statistiche di utilizzo del servizio va usato il seguente endpoint:

GET    https://www.uniwix.com/api/Uniwix/companyDetails/stats

La chiamata restituisce un JSON nella forma:

{
    "result": {
        "requests": "17",
        "successes": "10",
        "errors": "7",
        "last_request": "2021-07-11 08:58:57"
    },
    "code": 0
}

Dove requests indica il totale delle richieste fatte, successes quelle completate con successo (corrispondenti al numero di crediti consumati), errors quelle completate con errore (non comportano il consumo di crediti) e last_request il timestamp dell'ultima richiesta inviata.