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": {
        "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: 

{
    "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: 

{
    "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.

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

{
    "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
{
  "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:

{
    "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.