Consuntivazione automatica dei rebate fornitore: dalle fatture elettroniche in ingresso al rendiconto delle note di credito da chiedere

Contesto

Un'azienda di distribuzione B2B tecnica multi-marchio compra da centinaia di fornitori-produttori e ogni anno negozia con ciascuno un pacchetto di accordi commerciali: sconti in fattura, sconti a volume, rebate sul fatturato annuo, premi di categoria, pack promozionali stagionali. Tutta questa parte è operativa (il buyer compra, le fatture arrivano) — ma c'è un secondo tempo, la consuntivazione a fine periodo, dove bisogna calcolare, fornitore per fornitore, quanto rebate è maturato in base a quello che si è effettivamente comprato, e chiedere al fornitore le note di credito corrispondenti. Se questo pezzo è approssimativo si perdono soldi veri — accrediti dimenticati, rebate calcolati male, NC mai richieste. In molte PMI italiane questa parte vive in Excel e su controlli manuali di migliaia di righe fattura.

Sfida

Chiudere il ciclo end-to-end, in modo automatico e verificabile: dalla fattura elettronica ricevuta via SDI, al calcolo degli accrediti maturati per ogni accordo attivo, fino al rendiconto che l'amministrazione usa per chiedere le NC ai fornitori. Senza sostituire il gestionale (Mexal resta il sistema di verità di ordini e fatture), senza duplicare le anagrafiche, e senza costringere buyer e amministrazione a cambiare strumenti. Un layer che sta accanto al gestionale e fa quello che il gestionale non fa.

Approccio

Stack PHP + SPRIX Collage + MySQL, con Mexal come fonte di ordini/fatture/anagrafiche. Il sistema si compone di sei meccanismi che, messi in fila, coprono l'intero ciclo.

1. Ingestione delle fatture elettroniche in arrivo

Le FatturaPA dei fornitori entrano in SDI e da lì arrivano nel gestionale. Un parser PHP legge il loro XML (DOM con gestione namespaces) e riversa ogni riga in imp_xml_fatture: numero, data, codice articolo fornitore, descrizione, quantità, importo, mittente. Una view v_imp_xml_qualifica_prodotti fa il mapping tra codice fornitore e marchio merceologico interno — è il passaggio che trasforma il dato grezzo della fattura in dato consuntivabile, perché gli accordi sono su marchio, non sul codice articolo originale. Oltre cinquecento file XML processati in archivio, con storicità pluriennale.

2. Anagrafica accordi standard con calcolo multi-modalità

Ogni fornitore ha uno o più accordi attivi configurati nel sistema. Ciascun accordo specifica come si calcola l'accredito maturato — quattro modalità combinabili: per articolo specifico (tot euro a pezzo), per percentuale sul totale acquistato, per valore fisso al raggiungimento di soglia, per scaglioni a soglia (tipico: 10% fino a 50.000 euro di acquistato nel periodo, 15% oltre). Ogni accordo può escludere marchi merceologici specifici (classico: separare il canale e-commerce) e ha una periodicità di liquidazione variabile (1, 2, 3, 6, 12 mesi). Il modulo api_v2/calcoli.php (~800 righe) è quello che trasforma "fatture ricevute nel periodo + accordo" in "euro di accredito maturato".

3. Accordi pack a categoria combinata (la feature meno banale)

I pack sono un tipo di accordo più sofisticato: non "sconto sul marchio X", ma "se nell'ordine sono presenti tutte queste categorie merceologiche contemporaneamente (es. frigo + lavastoviglie + forno dello stesso brand), allora maturi questo accredito". Un pack è un template riutilizzabile che, quando il buyer apre un ordine fornitore che lo matcha, genera una istanza reale (tabella for_accordi_pack_ordini) con il dettaglio righe salvato come JSON. La consuntivazione è per istanza, non per accordo astratto — ogni volta che il pack viene "usato" su un ordine reale, si accumula un'istanza calcolabile.

4. Collage SPRIX bidirezionale sugli eventi Mexal

Il buyer non apre un tool parallelo, lavora dentro Mexal come sempre. Un collage SPRIX di circa 650 righe (collage_pack_ordini.spr) si attiva sull'apertura/salvataggio di un ordine fornitore Mexal: via CALLWEBSVC chiede al backend PHP quali pack sono attivi per quel fornitore in quel momento, li propone al buyer. Alla conferma, SPRIX invia un POST con JSON nativo al backend che crea l'istanza pack collegata all'ordine. Se l'ordine viene cancellato in Mexal, un evento DELETE richiama l'API e ripulisce l'istanza. La sincronizzazione è bidirezionale e autopulente — zero istanze orfane.

5. Stato a due livelli: acquisti e amministrazione

Ogni accordo e ogni pack hanno due coppie di flag indipendenti, gestite da ruoli diversi: il flag attivo lato acquisti (l'accordo è valido o sospeso commercialmente) e i flag in_gestione + chiuso lato amministrazione (la nota di credito è stata chiesta, abbinata, contabilizzata). Un accordo può essere "commercialmente valido" ma "consuntivazione non ancora chiusa". È la distinzione che evita la confusione tipica dei sistemi a singolo campo "stato" dove non si capisce mai se la pratica è aperta per acquisti o per amministrazione — e permette alle due funzioni di procedere in parallelo senza stepparsi i piedi.

6. Rendiconto di controllo: il punto di verità per l'esercizio

Il report rendiconto_controllo.php (circa 1.400 righe) compone a fine periodo il quadro fornitore per fornitore: accordi standard attivi, pack attivi, fatture collegate nel periodo, accredito maturato totale, note di credito già ricevute, delta residuo da chiedere. È il documento operativo con cui il controllo di gestione chiude l'esercizio e con cui l'amministrazione bussa al fornitore per le NC mancanti. Prima dell'esistenza di questo report, il quadro si ricostruiva a mano in Excel — con il risultato che una percentuale non nulla di accrediti maturati finiva per non essere mai richiesta.

Risultato

Il sistema è in produzione alla versione 2.1 e gira in modo silente sotto al gestionale. Il buyer lavora come sempre dentro Mexal; il collage SPRIX gli propone i pack quando servono; il backend PHP accumula le istanze; le fatture elettroniche entrano, vengono qualificate per marchio, e incrociate con gli accordi. A fine periodo — trimestre, semestre, anno — il rendiconto è già lì. La consuntivazione che prima costava giornate di Excel oggi si legge in un report, e il delta da richiedere ai fornitori è tracciato senza ambiguità.

Il mix di competenze che il progetto richiede — PHP + SPRIX Collage + DOM FatturaPA + logica rebate a scaglioni + gestionale Mexal — è quello che mi permette di lavorare a problemi che un consulente puramente moderno non saprebbe affrontare, e che un consulente puramente legacy non saprebbe modernizzare. È anche il tipo di problema che a mio avviso ha un mercato più ampio del singolo cliente: tutte le distribuzioni B2B multi-marchio italiane hanno la stessa catena business, e gran parte la gestisce ancora a mano.