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:
```json
{
"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
```json
{
"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.
---
### Invio fattura da tracciato (versione completa) ###
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
```json
{
"tipo_documento": "TD01",
"data": "2026-06-05",
"num_documento": "45/A",
"oggetto": "Fornitura materiale informatico",
"anagrafica": {
"cap": "35129",
"citta": "Padova",
"stato": "IT",
"indirizzo": "Via Venezia 10",
"provincia": "PD",
"cod_ufficio": "ABC1234",
"email_pec": "cliente@pec.it",
"nome": "Mario",
"cognome": "Rossi",
"CF": "RSSMRA80A01G224X",
"descrizione": "Rossi Mario",
"piva": "01234567890"
},
"articoli": [
{
"nome": "Notebook Lenovo ThinkPad",
"codice": "NB001",
"qta": 2,
"prezzo": 850.0,
"sconto_mc": "",
"iva": 22,
"dal": "",
"al": "",
"sconto": 10
},
{
"nome": "Servizio assistenza tecnica",
"codice": "SRV001",
"qta": 1,
"prezzo": 120.0,
"sconto_mc": "",
"iva": 22,
"dal": "2026-06-01",
"al": "2026-06-30"
},
{
"nome": "Articolo non imponibile",
"codice": "NIMP001",
"qta": 1,
"prezzo": 100.0,
"sconto_mc": "",
"iva": 0,
"natura": "N2.2",
"dal": "",
"al": ""
}
],
"rate": [
{
"data": "2026-07-05",
"importo": "1000.00",
"tipo": "MP05"
},
{
"data": "2026-08-05",
"importo": "940.00",
"tipo": "MP05"
}
],
"iban": "IT60X0542811101000000123456",
"incasso": {
"importo": 2.0,
"iva": 22,
"natura": ""
},
"trasporto": {
"causale": "Vendita",
"peso_lordo": "12.5",
"peso_netto": "11.8",
"colli": "2",
"inizio_trasporto": "2026-06-05",
"vettore": "BRT Spa",
"piva": "04507990150",
"iva": 22,
"natura": ""
},
"bollo": {
"importo": "2.00",
"applicato": "SI",
"carico": ""
},
"sconto": "50.00",
"sconto_perc": "5",
"arrotondamento": "0.01",
"ritenuta": {
"tipo": "RT01",
"importo": "200.00"
},
"esigibilita_iva": "I",
"ordini": [
{
"RiferimentoNumeroLinea": "1,2",
"IdDocumento": "ORD-2026-001",
"Data": "2026-05-15",
"CodiceCommessaConvenzione": "COMM001",
"CodiceCUP": "CUP123456789",
"CodiceCIG": "CIG987654321"
}
],
"contratti": [
{
"RiferimentoNumeroLinea": "",
"IdDocumento": "CTR-2026-001",
"Data": "2026-01-01",
"CodiceCommessaConvenzione": "",
"CodiceCUP": "",
"CodiceCIG": ""
}
],
"convenzioni": [
{
"RiferimentoNumeroLinea": "",
"IdDocumento": "CONV-01",
"Data": "2026-01-10",
"CodiceCommessaConvenzione": "",
"CodiceCUP": "",
"CodiceCIG": ""
}
],
"ricezioni": [
{
"RiferimentoNumeroLinea": "",
"IdDocumento": "RCV-2026-001",
"Data": "2026-05-30",
"CodiceCommessaConvenzione": "",
"CodiceCUP": "",
"CodiceCIG": ""
}
],
"fatture": [
{
"RiferimentoNumeroLinea": "",
"IdDocumento": "FT-2026-010",
"Data": "2026-04-15",
"CodiceCommessaConvenzione": "",
"CodiceCUP": "",
"CodiceCIG": ""
}
]
}
```
e va passato come RAW POST. La risposta dell'endpoint è uguale a quella descritta per l'upload XML.
---
#### Struttura Generale
| Campo | Tipo | Descrizione |
| --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tipo_documento | string | Codice del tipo documento secondo le specifiche SDI. Ad esempio `TD01` per una fattura immediata, `TD24` per una fattura differita o altri codici previsti dall'Agenzia delle Entrate. |
| data | date | Data di emissione del documento nel formato `YYYY-MM-DD`. |
| num_documento | string | Numero progressivo della fattura. Può contenere caratteri alfabetici, numerici e separatori. |
| oggetto | string | Descrizione sintetica del documento o della fornitura effettuata. |
| anagrafica | object | Informazioni fiscali e anagrafiche del destinatario della fattura. |
| articoli | array | Elenco delle righe che compongono il documento. Ogni elemento rappresenta un bene o servizio fatturato. |
| rate | array | Elenco delle scadenze di pagamento associate alla fattura. |
| iban | string | Coordinate bancarie sulle quali dovrà essere effettuato il pagamento. |
| incasso | object | Dati relativi a spese di incasso |
| trasporto | object | Informazioni relative alla spedizione o al trasporto della merce. |
| bollo | object | Configurazione dell'imposta di bollo virtuale prevista dalla normativa fiscale. |
| sconto | decimal | Importo complessivo di sconto applicato all'intero documento. |
| sconto_perc | decimal | Percentuale di sconto globale applicata sul totale imponibile. |
| arrotondamento | decimal | Arrotondamento sul totale documento. |
| ritenuta | object | Informazioni relative alla ritenuta d'acconto o ad altri contributi trattenuti. |
| esigibilita_iva | string | Modalità di esigibilità dell'IVA secondo la normativa fiscale vigente. |
| ordini | array | Riferimenti ad eventuali ordini di acquisto associati alla fattura. |
| contratti | array | Riferimenti a contratti collegati alla fornitura. |
| convenzioni | array | Riferimenti a convenzioni o accordi quadro. |
| ricezioni | array | Riferimenti a documenti di ricezione o verbali di consegna. |
| fatture | array | Collegamenti ad altre fatture correlate al documento corrente. |
---
#### Anagrafica Cliente
Contiene tutte le informazioni necessarie all'identificazione fiscale del destinatario della fattura.
##### Struttura
```json
{
"cap": "35129",
"citta": "Padova",
"stato": "IT",
"indirizzo": "Via Venezia 10",
"provincia": "PD",
"cod_ufficio": "ABC1234",
"email_pec": "cliente@pec.it",
"nome": "Mario",
"cognome": "Rossi",
"CF": "RSSMRA80A01G224X",
"descrizione": "Rossi Mario",
"piva": "01234567890"
}
```
| Campo | Tipo | Descrizione |
| ----------- | ------ | ------------------------------------------------------------------------------- |
| cap | string | Codice di avviamento postale della sede fiscale o operativa del cliente. |
| citta | string | Comune di residenza o sede legale del destinatario. |
| stato | string | Codice ISO dello Stato di appartenenza (es. `IT`, `FR`, `DE`). |
| indirizzo | string | Via, piazza o altro indirizzo completo comprensivo di numero civico. |
| provincia | string | Sigla automobilistica della provincia. |
| cod_ufficio | string | Codice destinatario SDI utilizzato per la consegna della fattura elettronica. |
| email_pec | string | Indirizzo PEC del destinatario, utilizzato come canale alternativo di recapito. |
| nome | string | Nome del soggetto destinatario quando si tratta di persona fisica. |
| cognome | string | Cognome del soggetto destinatario quando si tratta di persona fisica. |
| CF | string | Codice fiscale del destinatario. |
| descrizione | string | Denominazione dell'azienda oppure nominativo completo del soggetto. |
| piva | string | Partita IVA del cliente o del soggetto destinatario. |
---
#### Articoli
L'array contiene le righe che verranno riportate nel corpo della fattura.
| Campo | Tipo | Descrizione |
| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| nome | string | Descrizione estesa del bene o servizio fornito. Sarà riportata nella riga della fattura elettronica. |
| codice | string | Codice interno dell'articolo, del servizio o della prestazione. |
| qta | decimal | Quantità del bene o numero di prestazioni fatturate. |
| prezzo | decimal | Prezzo unitario dell'articolo prima dell'applicazione di eventuali sconti. |
| iva | decimal | Percentuale IVA applicata alla riga. Per operazioni non imponibili utilizzare valore `0`. |
| sconto | decimal | Percentuale di sconto applicata esclusivamente alla singola riga. |
| sconto_mc | string | Eventuale maggiorazione o sconto espresso secondo logiche personalizzate del gestionale. |
| dal | date | Data iniziale del periodo di competenza del servizio fatturato. |
| al | date | Data finale del periodo di competenza del servizio fatturato. |
| natura | string | Codice natura IVA richiesto quando l'aliquota è pari a zero. Consente di identificare il motivo fiscale dell'esenzione o non imponibilità. |
#### Codici Natura IVA
| Codice | Descrizione |
| ------ | ------------------------------------------------------ |
| N1 | Operazioni escluse dal campo IVA ai sensi dell'art. 15 |
| N2.1 | Operazioni non soggette ad IVA |
| N2.2 | Operazioni non soggette per altri motivi |
| N3.x | Operazioni non imponibili |
| N4 | Operazioni esenti |
| N5 | Regime del margine |
| N6.x | Reverse charge |
| N7 | IVA assolta in altro Stato membro |
---
#### Rate di Pagamento
Definiscono le modalità e le scadenze previste per il saldo del documento.
| Campo | Tipo | Descrizione |
| ------- | ------- | ---------------------------------------------------------------------------- |
| data | date | Data entro la quale il pagamento della rata deve essere effettuato. |
| importo | decimal | Importo previsto per la singola scadenza. |
| tipo | string | Codice modalità di pagamento secondo il tracciato della fattura elettronica. |
##### Modalità di Pagamento
| Codice | Descrizione |
| ------ | ------------------ |
| MP01 | Contanti |
| MP02 | Assegno |
| MP05 | Bonifico bancario |
| MP08 | Carta di pagamento |
| MP12 | Ricevuta bancaria |
---
#### Incasso
Permette di indicare gli eventuali costi di incasso
| Campo | Tipo | Descrizione |
| ------- | ------- | --------------------------------------------------------------------- |
| importo | decimal | Importo delle spese di incasso. |
| iva | decimal | Aliquota IVA applicata alle spese di incasso. |
| natura | string | Natura IVA da specificare quando il costo non è imponibile. |
---
#### Trasporto
Contiene le informazioni relative alla spedizione della merce o all'esecuzione del trasporto.
| Campo | Tipo | Descrizione |
| ---------------- | ------- | -------------------------------------------------------------------- |
| causale | string | Motivazione del trasporto, ad esempio vendita, conto visione o reso. |
| peso_lordo | decimal | Peso complessivo della spedizione comprensivo degli imballaggi. |
| peso_netto | decimal | Peso netto della merce trasportata. |
| colli | integer | Numero totale dei colli che compongono la spedizione. |
| inizio_trasporto | date | Data di presa in carico della merce da parte del vettore. |
| vettore | string | Ragione sociale o denominazione del trasportatore. |
| piva | string | Partita IVA del vettore incaricato del trasporto. |
| iva | decimal | Aliquota IVA applicata alle eventuali spese di trasporto. |
| natura | string | Natura IVA da valorizzare in presenza di trasporto non imponibile. |
---
#### Bollo
Permette la gestione automatica dell'imposta di bollo virtuale prevista per specifiche tipologie di documenti.
| Campo | Tipo | Descrizione |
| --------- | ------- | ------------------------------------------------------------------- |
| importo | decimal | Importo dell'imposta di bollo applicata alla fattura. |
| applicato | string | Indica se il bollo deve essere riportato nel documento elettronico. |
| carico | string | Specifica il soggetto a cui viene addebitato il costo del bollo. |
---
#### Sconto Documento
Gli sconti definiti a livello documento vengono applicati all'intero imponibile della fattura.
| Campo | Tipo | Descrizione |
| ----------- | ------- | ----------------------------------------------------- |
| sconto | decimal | Valore assoluto dello sconto applicato. |
| sconto_perc | decimal | Percentuale di sconto applicata sul totale documento. |
---
#### Ritenuta
Contiene i dati relativi alle ritenute fiscali o previdenziali.
| Campo | Tipo | Descrizione |
| ------- | ------- | ---------------------------------------------------------- |
| tipo | string | Tipologia della ritenuta prevista dalla normativa fiscale. |
| importo | decimal | Importo della ritenuta trattenuta sul documento. |
##### Tipologie Ritenuta
| Codice | Descrizione |
| ------ | ------------------------------ |
| RT01 | Ritenuta persone fisiche |
| RT02 | Ritenuta persone giuridiche |
| RT03 | Contributo INPS |
| RT04 | Contributo ENASARCO |
| RT05 | Contributo ENPAM |
| RT06 | Altri contributi previdenziali |
---
#### Esigibilità IVA
| Codice | Descrizione |
| ------ | ---------------------------- |
| I | IVA ad esigibilità immediata |
| D | IVA ad esigibilità differita |
| S | Split Payment |
---
#### Documenti Collegati
Le sezioni `ordini`, `contratti`, `convenzioni`, `ricezioni` e `fatture` utilizzano la stessa struttura dati.
| Campo | Tipo | Descrizione |
| ------------------------- | ------ | -------------------------------------------------------------------------------------- |
| RiferimentoNumeroLinea | string | Numero o elenco delle righe della fattura a cui il documento collegato fa riferimento. |
| IdDocumento | string | Identificativo univoco del documento esterno collegato. |
| Data | date | Data di emissione del documento collegato. |
| CodiceCommessaConvenzione | string | Codice interno della commessa, convenzione o progetto associato. |
| CodiceCUP | string | Codice Unico di Progetto previsto negli appalti pubblici. |
| CodiceCIG | string | Codice Identificativo Gara utilizzato nelle procedure di appalto pubblico. |
##### Tipologie di Collegamento
| Sezione | Descrizione |
| ----------- | -------------------------------------- |
| ordini | Ordini di acquisto emessi dal cliente |
| contratti | Contratti commerciali o di fornitura |
| convenzioni | Convenzioni e accordi quadro |
| ricezioni | Documenti di ricezione merci o servizi |
| fatture | Fatture precedenti o correlate |
---
### 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:
```json
{
"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.:
```json
{
"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:
```json
{
"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.