SIGN IT - Calcolo dei valori e arrotondamento decimale

SIGN IT lite si basa sulla procedura web "Documento Commerciale Online" (DCO) dell'Agenzia delle Entrate. Questo articolo descrive come l'AdE calcola i valori del documento commerciale in questa procedura.

L'Agenzia delle Entrate si basa sui seguenti valori per calcolare tutti gli altri: 

• unit.quantity
• unit.price
• vat.percentage
• value.discount
• details.purpose, solo per le righe in omaggio ("GIFT"). L'AdE esclude le righe in omaggio dall'importo complessivo da saldare (Totale complessivo), ma queste concorrono comunque all'imponibile e all'IVA. 

Valori a livello di riga (entry) 

• unit.quantity: per questo valore sono ammessi solo 2 decimali. 
   
• vat.amount e vat.inclusive sono arrotondati all'ottava cifra decimale.
   
• value.base e vat.exclusive non sono mappati sul portale AdE, ma consigliamo di calcolarli con lo stesso arrotondamento descritto qui sopra.  

Valori a livello di totali del documento

• total_vat.amount / totals.vat.amount (a seconda della versione utilizzata): il portale AdE ricalcola il valore inviato e lo sovrascrive con la somma degli importi IVA di tutte le entries, righe in omaggio incluse. L'AdE arrotonda questo valore (in background) all’ottava cifra decimale.
   
• total_vat.inclusive / totals.vat.inclusive e total_vat.exclusive / totals.vat.exclusive (a seconda della versione utilizzata): questi campi non vengono inoltrati all'AdE, che calcola i propri totali del documento direttamente dai valori di riga elencati all'inizio dell'articolo. 
   
• payments[].details.amount e payments[].details.discount: per questi valori sono ammessi solo 2 decimali.

Warning ed errori più comuni

• WARNING di validazione "Validation checks failed.. Reasons: Received total VAT amount XXX is not equal to Tax Agency computed total VAT amount XXX"
  Cosa significa: l'importo IVA totale inviato non coincide con la somma degli importi IVA di riga calcolata dall'AdE. Il warning non è bloccante: il documento commerciale viene accettato con il valore ricalcolato dall'AdE (mostrato nel PDF arrotondato a 2 decimali). 
   
• Errori di trasmissione del record con ERROR di validazione "Validation checks failed.. Reasons: La somma delle tipologie di pagamento non risulta uguale al Totale complessivo"  
  Cosa significa: l'AdE verifica che la somma di tutti i pagamenti (Σ payments[].details.amount + Σ payments[].details.discount) coincida con l'importo complessivo da saldare (Totale complessivo), che l'AdE calcola a partire dalle righe (Σ [(unit.price.inclusive × unit.quantity) − value.discount]), escluse le righe in omaggio.

Esempio di payload

{
  "content": {
    "type": "TRANSACTION",
    "record": {
      "id": "{{intentionId}}"
    },
    "operation": {
      "type": "RECEIPT",
      "document": {
        "number": "INV-12346"
      },
      "entries": [
        {
          "type": "SALE",
          "details": {
            "concept": "GOOD"
          },
          "data": {
            "type": "ITEM",
            "text": "Prod A",
            "unit": {
              "quantity": "1.00",
              "price": {
                "inclusive": "9.00",
                "exclusive": "8.18181818"
              }
            },
            "value": {
              "base": "8.18181818",
              "discount": "1.00"
            },
            "vat": {
              "type": "VAT_RATE",
              "code": "REDUCED_1",
              "percentage": "10.00",
              "exclusive": "7.27272727",
              "inclusive": "8.00",
              "amount": "0.72727273"
            }
          }
        },
        {
          "type": "SALE",
          "details": {
            "concept": "GOOD"
          },
          "data": {
            "type": "ITEM",
            "text": "Prod B",
            "unit": {
              "quantity": "2.00",
              "price": {
                "inclusive": "1.20",
                "exclusive": "0.98360656"
              }
            },
            "value": {
              "base": "1.96721311",
              "discount": "0.05"
            },
            "vat": {
              "type": "VAT_RATE",
              "code": "STANDARD",
              "percentage": "22.00",
              "exclusive": "1.92622951",
              "inclusive": "2.35",
              "amount": "0.42377049"
            }
          }
        }
      ],
      "breakdown": [
        {
          "type": "VAT_RATE",
          "code": "REDUCED_1",
          "percentage": "10.00",
          "exclusive": "7.27272727",
          "inclusive": "8.00",
          "amount": "0.72727273"
        },
        {
          "type": "VAT_RATE",
          "code": "STANDARD",
          "percentage": "22.00",
          "exclusive": "1.92622951",
          "inclusive": "2.35",
          "amount": "0.42377049"
        }
      ],
      "totals": {
        "vat": {
          "amount": "1.15104322",
          "exclusive": "9.19895678",
          "inclusive": "10.35"
        }
      },
      "customer": {
        "type": "EXTERNAL"
      },
      "payments": [
        {
          "type": "CASH",
          "details": {
            "amount": "10.35"
          }
        }
      ]
    }
  }
}

Nota: il payload qui sopra riflette le modifiche alla struttura introdotte con la versione API 2026-06-01. Se stai integrando una versione precedente: sostituisci il campo totals.vat (a livello di operation) con il vecchio total_vat (a livello di document), rimuovi il campo breakdown e usa il formato semplice unit.price come stringa (solo inclusive, es. "price": "9.00") al posto dell'oggetto { inclusive, exclusive } mostrato qui.