Consuntivazione accordi fornitori con parser XML fatture elettroniche, pack a categoria combinata e collage SPRIX bidirezionale su Mexal

Contesto

PMI del settore distribuzione tecnica B2B, rete di centinaia di fornitori, decine di marchi merceologici, operatività quotidiana appoggiata su Mexal/Passepartout per il ciclo ordini-fatture. La parte commerciale più delicata non è scrivere gli accordi — è consuntivarli: a fine anno bisogna capire, fornitore per fornitore, quanto è maturato di accredito in base a sconti a volume, rebate su marchio, premi di categoria. Prima del mio intervento, questa parte viveva tra Excel, vecchie maschere Scriptcase e controlli manuali su migliaia di righe fattura.

Sfida

Costruire un sistema che leggesse in automatico le fatture elettroniche in arrivo, le collegasse all'accordo corretto, calcolasse gli accrediti maturati per ogni fornitore (anche con logiche non banali — pacchetti a categoria combinata, scaglioni a soglia, periodicità diverse), e si agganciasse a Mexal al momento dell'emissione di un ordine fornitore, per proporre al buyer l'accordo pack applicabile. Il tutto senza imporre allo staff commerciale un tool parallelo: la sincronizzazione col gestionale doveva essere trasparente.

Approccio

Stack PHP + SPRIX + MySQL, con Mexal come sistema di verità per ordini, fatture e anagrafiche. SPRIX — il linguaggio di scripting interno di Passepartout — è la chiave: permette di agganciarsi a eventi del gestionale (apertura ordine fornitore) e dialogare con backend esterni via CALLWEBSVC. Cinque feature che fanno di questo sistema un caso particolare.

Parser XML fatture elettroniche con mapping ad articoli di marchio

Ogni fattura elettronica FatturaPA che arriva dai fornitori viene parsata (DOM con gestione namespaces, non regex) e riversata nella tabella imp_xml_fatture: numero, data, codice articolo fornitore, importo, quantità, id mittente. Una view v_imp_xml_qualifica_prodotti fa il mapping tra codice fornitore e marchio interno, risolvendo l'ambiguità dei cataloghi dove lo stesso articolo ha codici diversi per fornitore e per gestionale. Oltre 500 file XML processati in archivio. Questo è il carburante di tutto: senza la fattura digerita, non esistono accrediti calcolabili.

Accordi pack a categoria combinata

La feature più distintiva e meno ovvia. Un pack è un template di accordo che obbliga più categorie merceologiche in un'unica promozione — ad esempio "promo cucina" con frigorifero + lavastoviglie + forno, ognuno con la sua percentuale o valore fisso di accredito. Il template genera N istanze reali nel tempo (tabella for_accordi_pack_ordini): ogni volta che il buyer apre un ordine fornitore che matcha il pack, si crea un'istanza consuntivabile con il dettaglio righe salvato come JSON. La consuntivazione non è per accordo astratto, ma per singola istanza — cosa che il modello "sconto fisso su fatturato annuo" non sa fare.

Collage SPRIX bidirezionale su eventi Mexal (649 righe)

Il cuore dell'integrazione. Uno script SPRIX di ~650 righe (collage_pack_ordini.spr) si attiva sull'apertura/salvataggio di un ordine fornitore Mexal (OFP): via CALLWEBSVC interroga l'endpoint PHP api_accordi_pack.php?id_mittente=XXX per sapere quali pack sono attivi per quel fornitore, e propone al buyer la selezione. Alla conferma, SPRIX spedisce un POST con JSON nativo (JSONCREATE, JSONADDSTR, JSONADDARR — funzioni SPRIX introdotte nelle ultime release, alternativa pulita alla concatenazione stringa con limite 255 caratteri) al backend, che crea l'istanza pack. Se l'OFP viene poi cancellato in Mexal, un evento DELETE richiama l'API per ripulire l'istanza lato PHP. La sincronizzazione è bidirezionale e autopulente.

Calcolo accrediti multi-modalità con scaglioni e periodicità

Il modulo api_v2/calcoli.php (~800 righe) supporta quattro modalità di accredito — per articolo specifico, per percentuale sul totale acquistato, per valore fisso, per scaglioni a soglia (es. 10% fino a 50 mila euro di acquistato, 15% oltre) — combinabili con esclusione di marchi merceologici (tipicamente per separare il canale e-commerce) e periodicità di liquidazione variabile (1/2/3/6/12 mesi). È la parte che rende il sistema difendibile contro "ma si può fare con Excel": Excel non gestisce quattro modalità intrecciate senza diventare illeggibile.

Tracciamento stato a due livelli: acquisti e amministrazione

Ogni accordo e ogni pack hanno due coppie di flag gestiti da ruoli diversi: il flag attivo in capo agli acquisti (accordo valido o sospeso) e i flag in_gestione + chiuso in capo all'amministrazione (nota di credito collegata o ancora da abbinare). L'accordo può essere "commercialmente valido" ma "non ancora consuntivato" — due stati indipendenti, loggati separatamente. Evita la confusione tipica dei sistemi a singolo campo "stato" dove non si capisce mai se la pratica è aperta per uno o per l'altro.

Rendiconto annuale di controllo come punto di verità

Un report rendiconto_controllo.php di circa 1.400 righe compone il quadro fine anno: per ogni fornitore, accordi standard + pack, fatture collegate, accrediti maturati, note di credito già emesse, delta da emettere. È il documento che il controllo di gestione firma per chiudere l'esercizio e che l'amministrazione usa per richiedere le note di credito mancanti.

Risultato

Il sistema è in produzione alla versione 2.1, gira in modo silente sotto al gestionale Mexal senza che il buyer sia costretto a cambiare strumento: lui apre l'ordine fornitore come sempre, vede la proposta del pack applicabile, conferma. La parte di consuntivazione, che prima richiedeva giornate di Excel a fine anno, oggi si legge da un singolo report. La competenza che questo progetto richiede è rara in Italia — PHP + SPRIX + DOM XML FatturaPA + logica rebate a scaglioni + gestionale Mexal — ed è il tipo di mix che mi permette di lavorare su problemi che un consulente puramente "moderno" (solo stack JavaScript) non saprebbe affrontare, e che un consulente puramente "legacy" (solo gestionale) non saprebbe modernizzare.