Cos'è un'API di registro a partita doppia per i marketplace?
Un'API di registro a partita doppia registra i movimenti di denaro di un marketplace sotto forma di scritture contabili bilanciate e immutabili, così sai sempre a chi spetta cosa e perché.
Un marketplace può sembrare solido nella sua tabella degli orders e continuare ad avere una situazione finanziaria errata. L'ordine risulta "pagato". La dashboard del venditore mostra un saldo. Eppure, nessun dato in quella tabella dimostra quanto denaro contante detenga la piattaforma, quanto debba a ciascun venditore, quale quota del pagamento rappresenti i ricavi delle commissioni o quanta IVA sia ora esigibile. Un'API di registro a partita doppia (double-entry ledger API) esiste proprio per registrare queste conseguenze finanziarie in modo corretto, una transazione bilanciata alla volta.
In parole semplici: un'API di registro a partita doppia è un sistema contabile programmabile. La tua applicazione le invia un evento finanziario, come un pagamento contabilizzato o un payout approvato, e il registro scrive quell'evento sotto forma di prima nota con addebiti e accrediti uguali su conti specifici. Non sposta denaro. Registra la verità sul denaro che è stato spostato altrove.
Cosa significa "registro a partita doppia" in questo contesto
Un registro è la cronologia delle variazioni dei conti, non una tabella che si limita a mostrare il saldo più recente. Un registro funzionante si basa su tre concetti interconnessi:
- Conto (Account): una posizione finanziaria denominata, come crediti verso il processore di pagamento, debiti verso i venditori, ricavi da commissioni o IVA a debito.
- Transazione (Prima nota / Journal): un singolo evento finanziario atomico contenente più righe bilanciate.
- Scrittura (Posting / Entry): una singola riga di dare o avere all'interno di quella transazione.
L'invariante che tiene insieme l'intera struttura è semplice: il totale dei dari deve essere uguale al totale degli averi, per ogni transazione e per ogni valuta. Di norma, le API di registro rifiutano una scrittura non bilanciata prima ancora che venga memorizzata. La documentazione di Modern Treasury definisce una transazione di registro come un'operazione che coinvolge due o più conti con almeno un dare e un avere di importi uguali, e tratta una transazione registrata come immutabile.
Partita doppia non significa esattamente due righe. Una singola vendita su un marketplace richiede spesso un dare e diversi accrediti. Questo è l'aspetto che viene frainteso più spesso.
Perché i marketplace hanno bisogno di un registro e non solo di una tabella dei pagamenti
Un marketplace gestisce diversi rapporti finanziari nello stesso momento. Un acquirente paga. Un processore liquida i fondi. La piattaforma potrebbe controllare temporaneamente il denaro. Il venditore matura una quota. La piattaforma trattiene una commissione. L'imposta diventa esigibile. Può essere trattenuta una riserva. In seguito, un payout sposta il denaro all'esterno, mentre rimborsi o chargeback ne invertono alcune parti.
Una tabella dei payments può indicare lo stato commerciale di un ordine. Non può indicare con certezza:
- l'ammontare dei crediti verso il processore o della liquidità
- quanto è dovuto a ciascun venditore
- quali ricavi appartengono alla piattaforma
- quanta IVA è dovuta e in quale paese
- quanto è accantonato a fronte di rimborsi o controversie
- se un payout ha ridotto correttamente la passività verso il venditore
- se le liquidazioni del processore corrispondono alle aspettative della piattaforma
La guida di Nordlet alle API di registro a partita doppia per la contabilità dei marketplace traccia una linea netta: le tabelle applicative descrivono lo stato del prodotto, mentre il registro annota le conseguenze finanziarie di quello stato. Sottolinea inoltre un concetto che vale la pena ripetere: i report dei processori di pagamento sono dati di input per la riconciliazione, non libri contabili completi in partita doppia.
Un esempio pratico di vendita su un marketplace
Immagina che un acquirente paghi 100 €, che al venditore spettino 85 € e che la commissione della piattaforma sia di 15 €. Per semplicità, tralasciamo l'IVA e le commissioni del processore.
| Conto | Dare | Avere | Motivo |
|---|---|---|---|
| Crediti v/processore di pagamento | 100 € | Il processore deve alla piattaforma il pagamento incassato | |
| Debiti v/venditori | 85 € | La piattaforma deve i soldi al venditore | |
| Ricavi da commissioni | 15 € | La piattaforma ha guadagnato la sua commissione | |
| Totale | 100 € | 100 € | Bilanciato |
La classificazione importante qui è che gli 85 € dovuti al venditore costituiscono una passività, non un ricavo della piattaforma. Secondo il quadro concettuale IFRS, una passività è un'obbligazione attuale di trasferire una risorsa economica. Un marketplace non dovrebbe registrare l'intero incasso della vendita del venditore come proprio reddito semplicemente perché l'acquirente ha pagato tramite la sua piattaforma. Il ruolo di intermediario (agent), principale (principal) o fornitore debitore d'imposta (deemed supplier) modifica il trattamento contabile, ma il meccanismo del registro rimane invariato.
Quando il venditore diventa idonei per il payout, non viene riconosciuto alcun nuovo ricavo. Si procede alla liquidazione della passività:
| Conto | Dare | Avere |
|---|---|---|
| Debiti v/venditori | 85 € | |
| Banca o conto transitorio payout | 85 € | |
| Totale | 85 € | 85 € |
Se il processore trattiene una commissione di 3 € prima della liquidazione, il movimento di cassa diventa una prima nota a tre righe: 97 € in banca, 3 € in costi di elaborazione, 100 € in uscita dai crediti v/processore. Ogni variazione di posizione ha un'origine e una destinazione.
Come funziona l'API, passo dopo passo
1. La tua applicazione rileva un evento di business. Un pagamento viene acquisito, un ordine viene evaso, un payout viene approvato, viene emesso un rimborso, si apre un chargeback, arriva una liquidazione. Il tuo database gestisce ancora lo stato operativo. Il registro registra l'effetto monetario.
2. Invii una richiesta strutturata. Di solito contiene il tipo di evento, importo e valuta, ID dell'ordine o del pagamento, identificativi di acquirente e venditore, commissione, dati fiscali, conti coinvolti, date di competenza e di registrazione, chiave di idempotenza (idempotency key) e metadati di collegamento ai record del processore e del prodotto. L'esempio di API pubblica di Nordlet mostra una richiesta di vendita concettuale con ID venditore, tipo di vendita, importo, valuta, paese e aliquota IVA.
3. L'API effettua la validazione. Verifica che dare e avere siano in equilibrio, che i conti esistano e siano movimentabili, che la valuta sia supportata, che l'importo utilizzi una gestione precisa delle unità frazionarie, che la chiave di idempotenza non sia riutilizzata per un risultato diverso, che il periodo contabile sia aperto e che siano presenti i metadati richiesti. Un controllo fallito non lascia alcuna prima nota parziale.
4. Esegue la registrazione in modo atomico. L'intera transazione viene scritta come un unico blocco. Non deve mai verificarsi il caso in cui la registrazione del dare vada a buon fine mentre l'accredito corrispondente fallisce. Per un marketplace, una divisione parziale potrebbe creare un saldo fittizio del venditore senza la cassa corrispondente, o registrare una commissione senza l'obbligazione verso il venditore.
5. Saldi e report derivano dal registro. Dopo la registrazione, è possibile leggere i saldi dei conti, i saldi in sospeso e disponibili del venditore, il bilancio di verifica (trial balance), l'attività del libro mastro (general ledger), i riepiloghi IVA e lo storico riferito a una data passata. Il saldo del venditore deve poter essere ricostruito a partire dalle scritture, anziché essere affidato a un campo modificabile.
6. I webhook notificano il tuo prodotto. Eventi come sale_invoice.paid, una prima nota registrata, un payout disponibile o un'eccezione di riconciliazione vengono inviati tramite notifiche push. Elaborali in modo idempotente. Un webhook è una notifica, non l'autorizzazione ad applicare l'evento finanziario una seconda volta. Le convenzioni API descrivono in dettaglio gli ambiti (scopes), le chiavi di idempotenza, la struttura degli errori e la firma dei webhook.
I saldi dei venditori non sono un numero unico
La maggior parte dei marketplace incontra difficoltà perché tratta il saldo di un venditore come un'unica cifra. Il denaro dovrebbe essere suddiviso in diversi stati:
| Stato | Significato |
|---|---|
| In sospeso (Pending) | Il venditore potrebbe averne diritto, ma le condizioni di svincolo non sono soddisfatte |
| Disponibile (Available) | Idoneo per il payout |
| Riservato (Reserved) | Trattenuto a fronte di rimborsi, resi o contestazioni |
| Pagato (Paid out) | Obbligazione estinta tramite bonifico |
| Negativo (Negative) | Rimborsi, chargeback o commissioni superano i fondi disponibili |
I modelli dei processori rispecchiano questa struttura. Il flusso di addebiti e trasferimenti separati di Stripe consente a una piattaforma di addebitare il proprio conto e poi trasferire porzioni ai conti collegati, con commissioni, rimborsi e chargeback che incidono sul saldo della piattaforma. Il modello marketplace di Adyen distingue i conti di saldo utente, che trattengono i fondi fino al payout, da un conto di saldo passivo (liable balance account) in grado di assorbire i saldi negativi derivanti da rimborsi o chargeback. Questi elementi costituiscono input utili per il tuo registro, ma non rappresentano il tuo modello contabile completo.
Payout e compensi dei venditori avvengono in momenti diversi
Un venditore può maturare un guadagno di lunedì e ricevere il pagamento il lunedì successivo. Tra questi due momenti, un ordine viene evaso, viene trattenuta una riserva, viene generato un lotto di payout, il processore liquida le somme al netto delle commissioni e arriva l'accredito bancario. Il registro deve preservare ciascuna fase anziché sovrascrivere l'ordine con un "pagato" finale. È questo che ti permette di spiegare le differenze temporali tra l'attività degli ordini, il diritto del venditore, la liquidazione, l'avvio del payout e l'incasso in banca.
Rimborsi e chargeback: storno, non riscrittura
I rimborsi e i chargeback sono nuovi eventi collegati al pagamento originale. In un registro immutabile, si corregge la situazione inserendo una scrittura di storno seguita da una scrittura correttiva, in modo che l'operazione originale rimanga visibile a fini di auditing. Modern Treasury tratta le transazioni registrate come immutabili e supporta le chiavi di idempotenza per evitare oggetti duplicati in caso di nuovi tentativi.
Un rimborso tipicamente riduce la cassa o i crediti verso l'acquirente, storna il debito verso il venditore, può stornare parte della commissione a seconda delle policy, rettifica l'imposta e può intaccare una riserva per rimborsi. Un chargeback riduce la cassa o i crediti verso il processore, può riaprire un importo dovuto dal venditore o dalla piattaforma, registra un costo per contenzioso e una commissione del processore, e movimenta i fondi attraverso un conto di riserva.
Riconciliazione: collegare il registro al denaro reale
Un registro può essere bilanciato internamente e tuttavia riportare dati errati rispetto al mondo esterno. La riconciliazione confronta le registrazioni interne con i riscontri esterni: rendiconti di liquidazione dei processori, estratti conto bancari, file dei payout, registri dei rimborsi e delle contestazioni.
Un ciclo operativo efficace si sviluppa in questo modo:
- Importa il lotto di liquidazione o l'estratto conto bancario.
- Abbina ciascuna riga a un ordine, pagamento, rimborso, commissione, payout o contestazione.
- Confronta il lordo atteso, le trattenute, le riserve e il netto.
- Registra i movimenti confermati nel registro.
- Invia gli elementi non abbinati a un apposito conto sospeso (suspense account).
- Analizza le eccezioni.
- Chiudi il periodo contabile.
La documentazione di Nordlet sulla riconciliazione descrive esattamente questo processo: importazione dei lotti di liquidazione, abbinamento delle righe di addebito e rimborso, e instradamento degli incassi non abbinati verso un conto sospeso anziché indovinare a quale fattura appartengano. Due controlli sono fondamentali e nessuno dei due sostituisce l'altro: la validazione a partita doppia verifica se ogni prima nota è bilanciata, mentre la riconciliazione verifica se essa concorda con il processore, la banca e l'evento di business.
Dettagli di progettazione che determinano il successo
Idempotenza. Associa la chiave a un evento stabile, come payment_captured:pi_123. Un nuovo tentativo restituisce il risultato originale, non una seconda prima nota.
Atomicità. Tutte le righe di un evento vengono registrate insieme o nessuna di esse viene scritta.
Immutabilità e storni. Lo storico registrato non è modificabile tramite normali aggiornamenti. Le correzioni creano voci collegate che preservano l'importo originale, la data, la classificazione, il motivo e l'autore.
Precisione monetaria. Nessun numero in virgola mobile binario (binary floating point). Utilizza interi per le unità frazionarie o decimali esatti, valuta esplicita e una regola di arrotondamento deterministica per le suddivisioni. Se dividi 100 € tra venditori e commissioni senza queste accortezze, un centesimo disperso romperà il bilanciamento.
Date di competenza e di registrazione. Il momento in cui l'acquirente ha pagato, il momento in cui il venditore ha maturato il compenso, la data di liquidazione bancaria e la data di registrazione contabile sono momenti differenti. Confonderle rende inaffidabili i report periodici e la corretta imputazione temporale delle imposte.
Multi-valuta. Dare e avere devono essere bilanciati all'interno della stessa valuta. La conversione richiede un evento di tasso di cambio esplicito con conti dedicati per la commissione, l'arrotondamento e qualsiasi guadagno o perdita su cambi. Accettare un campo currency non trasforma un registro in un motore di cambio valutario.
Ciò che un'API di registro non farà al posto tuo
Non deciderà il tuo piano dei conti. Spetta ancora a te determinare se agisci in qualità di principale o intermediario, quando viene maturata la commissione, quale parte sostiene le commissioni del processore, in che modo i rimborsi influiscono sulle commissioni e come l'IVA viene calcolata e dichiarata. Le linee guida di Nordlet consigliano di mappare prima i flussi di denaro, redigere il piano dei conti, farlo esaminare da un commercialista e quindi implementare un flusso completo, dall'ordine al payout fino alla riconciliazione, prima di procedere alla scalabilità.
Non risolverà i dubbi di natura fiscale. L'IVA dipende dalla posizione di acquirente e venditore, dal tipo di prodotto, dallo stato di registrazione ai fini fiscali e dalle norme relative ai fornitori debitori d'imposta (deemed-supplier rules); la guida all'IVA UE definisce ciò che il motore calcola automaticamente e ciò che segnala per la revisione umana. La copertura IVA di Nordlet è focalizzata sull'UE e sullo SEE, pertanto non si estende alle imposte sulle vendite negli Stati Uniti (US sales tax) o alla fatturazione elettronica latinoamericana. Né risolverà le ambiguità operative: se un termine di reso sia scaduto, se un payout debba essere bloccato o se un pagamento sia fraudolento. Queste sono decisioni di tua competenza. Il registro si limita a registrare il loro risultato finanziario.
Dove si posiziona Nordlet
Nordlet è un'API di contabilità creata per piattaforme e marketplace, dotata di un registro immutabile a partita doppia, gestione dei payout, gestione dell'IVA UE, endpoint REST, SDK tipizzati e webhook accessibili tramite un'unica interfaccia. La sua caratteristica distintiva è la presenza di una contabilità integrata direttamente nel tuo prodotto, anziché in un sistema di checkout di terze parti. Al momento in cui scriviamo, il prodotto è in accesso anticipato con una sandbox per i partner di progettazione, quindi va considerato come un valido esempio della categoria, valutandone la maturità per la produzione, l'uptime e la copertura giurisprudenziale in base al tuo specifico caso d'uso prima di procedere all'adozione.
Per gli sviluppatori di marketplace e piattaforme, il modello mentale utile consiste nel separare il movimento dei pagamenti dalla verità finanziaria. Il processore sposta il denaro. Un'API di registro a partita doppia registra a chi è dovuto il denaro, quanto hai guadagnato, quali imposte e riserve detieni e se la realtà esterna quadra con i tuoi libri contabili.
FAQ
Un'API di registro a partita doppia è la stessa cosa di un processore di pagamento?
No. Un processore autorizza, acquisisce, liquida e talvolta eroga fondi. Un'API di registro registra le conseguenze contabili di quegli eventi. La maggior parte dei marketplace utilizza entrambi i sistemi: un processore come Stripe o Adyen per i flussi di cassa e un registro per la contabilità.
Posso usare semplicemente la dashboard del mio processore come libro mastro generale?
Puoi provarci, ma col tempo non supererà un audit. I report dei processori mostrano addebiti, commissioni, trasferimenti e liquidazioni, ma di solito non rappresentano per intero le obbligazioni verso i venditori, le passività fiscali, le spese non relative al processore o le rettifiche contabili. Consideralo come un input per la riconciliazione.
Un registro bilanciato significa che i miei libri contabili sono corretti?
Significa solo che le tue registrazioni soddisfano la regola del dare-avere. Una transazione perfettamente bilanciata può comunque essere registrata sul conto sbagliato, associata al venditore errato o gestita con il trattamento fiscale scorretto. Il bilanciamento è necessario, ma non sufficiente. La riconciliazione è ciò che individua il resto degli errori.
Se il registro è immutabile, come posso correggere gli errori?
Inserisci una scrittura di storno e successivamente una scrittura correttiva. L'operazione originale rimane visibile, ed è proprio questo il punto centrale. L'immutabilità protegge la pista di controllo (audit trail), non ti intrappola nei tuoi errori.
Un'API di contabilità mi rende automaticamente conforme alle normative?
No. L'API impone una struttura contabile e produce registri utilizzabili. La conformità legale dipende comunque dalla tua giurisdizione, dal tuo ruolo contrattuale, dal trattamento fiscale, dalle normative sui pagamenti, dai processi antiriciclaggio e di verifica dell'identità (KYC e AML) e dagli obblighi di rendicontazione.