DDT digitale web chiamabile dal gestionale Mexal: documento dinamico via WebAPI, con bypass DNS e debug live

Contesto

Nel gestionale Mexal l'utente apre un documento di trasporto — un DDT, un ordine cliente, un preventivo — e lo vede nella sua forma "tabulato DOS-like" tipica del gestionale. Questa rappresentazione va benissimo in ufficio ma non è la cosa migliore da spedire a un cliente o mostrare a un commerciale in visita: serve una versione più pulita, web, condivisibile via link, che mantenga però tutti i dati reali del gestionale senza duplicarli.

Sfida

Dare al gestionale un pulsante che, dal singolo documento, aprisse in un browser la sua versione web pronta per essere mostrata o inviata — sempre aggiornata rispetto a Mexal, senza database locale che duplicasse qualcosa, e che funzionasse anche dall'interno dell'infrastruttura PMI reale, con tutti i suoi limiti (DNS intranet a volte lento, certificati self-signed, IP filtrati). Un piccolo ponte, ma preciso.

Approccio

Stack PHP puro, senza framework, senza Scriptcase, senza Laravel. Tre file principali (circa 3.300 righe di codice core), una chiamata cURL verso Mexal WebAPI, composizione dinamica dell'HTML. Cinque feature che rendono il progetto non banale.

Un click dal gestionale, un URL web che si apre

Dentro Mexal è configurato un comando personalizzato che, sul documento selezionato, invoca l'URL della web app passando sigla, serie e numero documento come parametri. L'operatore clicca da Mexal e si apre il browser con la versione web. Nessuna esportazione, nessuna copia, nessun rischio di sfasamento dei dati: la pagina viene generata al momento leggendo dal gestionale stesso via WebAPI.

Sette endpoint WebAPI compongono il documento

Per ricostruire un DDT completo servono fonti diverse: movimenti di magazzino per le righe articolo, ordini-matrici per risalire all'ordine cliente d'origine, anagrafica cliente, anagrafica fornitore quando serve, indirizzi di spedizione alternativi, preventivi correlati. Il bridge orchestra sette endpoint Mexal WebAPI (movimenti-magazzino, ordini-matrici, ordini-clienti, preventivi, fornitori, indirizzi-spedizione, clienti) e assembla il documento in memoria, riga per riga, con totali, sconti, modalità di pagamento, dati del trasportatore e indirizzo di destinazione.

Bypass DNS intranet con IP hardcoded nel context cURL

Un dettaglio che un consulente junior non metterebbe: in alcuni momenti il DNS della rete interna PMI impiega fino a diciassette secondi a risolvere l'host di Mexal, rendendo l'apertura del documento inaccettabile. Ho hardcoded l'IP di Mexal nei file_get_contents context options con stream_context_create — quando il DNS non collabora, cURL va dritto all'IP e apre la connessione in un istante. Con fallback intelligente tra file_exists() per asset locali e get_headers() per URL remoti. È la classica micro-ottimizzazione che in un ambiente enterprise teorico non avrebbe senso, e che invece nella realtà delle PMI italiane cambia la differenza tra "va" e "non va".

Parsing robusto del codice documento

L'utente passa un identificativo tipo OC3/1234 o FT2/567: il parser estrae sigla (due caratteri), serie (un carattere), numero, e compone la tupla SIG+SERIE+NUM che serve a indirizzare la chiamata WebAPI al tipo documento giusto. Gestisce DDT, ordini cliente, fatture, preventivi con lo stesso codice di parsing, senza duplicarlo per ogni tipo.

Debug system su due canali, live durante l'esecuzione

Debuggare integrazioni con ERP legacy in produzione è notoriamente scomodo — tipicamente scrivi su un log e lo leggi dopo. Ho costruito un sistema di debug a due canali simultanei: un file (ddt_digitale_debug.log, con fflush() forzato dopo ogni write per vedere gli eventi man mano che accadono) e una visualizzazione HTML colorata in pagina con box blu per info e rossi per errori, timestamp al millisecondo, scritta durante l'esecuzione e non alla fine. Quando qualcosa va storto lo vedo in diretta sul browser, non dopo. Il file di log cresciuto durante una sessione intensa di troubleshooting è diventato di alcuni megabyte — lo tengo come testimonianza della disciplina con cui il progetto è stato messo in produzione.

Risultato

Piccolo progetto — circa 3.300 righe di PHP — ma quotidianamente usato: ogni volta che qualcuno in azienda ha bisogno di mandare un documento al cliente in forma decente, clicca il bottone dal gestionale e apre il web. Nessuna duplicazione di dati, sempre aggiornato, nessuna finestra di disallineamento. È l'esempio del pattern che mi piace di più portare in PMI: non ricostruire il gestionale, aggiungergli piccoli ponti che lo rendano utile in scenari moderni. Il DDT non è diventato "il nuovo software": è rimasto quello che era in Mexal, e intorno è cresciuta una pagina web che lo porta dove serve.