Uniwix API v3 - Documentazione tecnica ====== Uniwix è 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à ``200``e 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: ```json { "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: ```json { "result": { "data": { "fiscal_id": "07686800967", "items": [ { "quantity": 1, "description": "Articolo", "unit_price": "0.05", "vat_rate_code": "22", "complimentary": false, "discount": 0, "sku": "" } ], "cash_payment_amount": 0.05, "id": "6955131543dab3e45c020072", "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-31T12:12:05.000Z", "error_message": null, "error_code": null, "total_amount": 0.05, "document_number": "", "document_date": null, "transaction_id": null, "create_timestamp": 1767183124, "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 }, "success": true, "message": "6955131543dab3e45c020072", "error": null }, "code": 0 } ``` ### 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: ```json { "result": { "data": { "fiscal_id": "0123456789", "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: ```json { "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": "0123456789", "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.