Spedizioni & Vettori

L'Archivio Spedizioni e la pagina centrale del modulo. Presenta l'elenco di tutte le spedizioni registrate con strumenti di ricerca, filtri e indicatori di performance.

Filtri e ricerca

La barra superiore consente di filtrare le spedizioni per: stato, vettore, periodo (data creazione o data consegna prevista), destinatario e numero DDT collegato. La ricerca testuale opera su numero spedizione, ragione sociale destinatario e codice tracking.

KPI riepilogative

Stati della spedizione

Ogni spedizione segue un ciclo di vita definito dai seguenti stati:

Una spedizione puo essere creata in due modalita: dall'Archivio Spedizioni oppure direttamente da un DDT.

Modalita A — Dall'Archivio Spedizioni

1. Accedere a Logistica → Spedizioni e premere il pulsante + Nuova Spedizione.
2. Selezionare uno o piu DDT da collegare alla spedizione. Il sistema mostra i DDT in stato "Pronto per spedizione" non ancora associati.
3. I dati del destinatario vengono precompilati dal DDT selezionato (ragione sociale, indirizzo di consegna). E possibile modificare l'indirizzo di destinazione se diverso.
4. Selezionare il vettore tra quelli configurati in anagrafica. Il sistema propone il vettore predefinito del cliente, se impostato.
5. Compilare i campi di spedizione: numero colli, peso, volume, note per il vettore.
6. Confermare la data di ritiro prevista e l'eventuale consegna tassativa.
7. Premere Salva. La spedizione viene creata in stato IN_ATTESA.

Modalita B — Dal DDT

1. Aprire il DDT desiderato dall'Archivio DDT.
2. Premere il pulsante Crea Spedizione presente nell'intestazione del documento.
3. Il sistema pre-compila tutti i dati dalla testata del DDT (destinatario, indirizzo, vettore).
4. Completare i dati mancanti (colli, peso, note) e premere Salva.

La scheda dettaglio di ogni spedizione presenta una sezione Tracking che consente di monitorare lo stato di avanzamento della consegna.

1. Aprire la spedizione dall'Archivio Spedizioni.
2. Nella sezione Tracking viene visualizzata la timeline degli eventi: creazione, ritiro, transito, consegna o resa.
3. Se il vettore supporta il tracking integrato, gli aggiornamenti vengono ricevuti automaticamente e lo stato avanza in tempo reale.
4. Per i vettori senza integrazione, l'operatore puo inserire manualmente gli aggiornamenti premendo + Aggiorna Stato e selezionando il nuovo stato con data e ora.
5. Il codice tracking del vettore, se disponibile, viene visualizzato con un link diretto al portale di tracciamento esterno (configurato nel Tracking URL pattern del vettore).

I vettori sono soggetti dell'anagrafica con ruolo Vettore attivo. La configurazione avviene in due punti: nella scheda soggetto e nella pagina dedicata /vettori.

Configurazione dalla scheda soggetto

Quando un soggetto ha il ruolo Vettore attivo, la scheda presenta la sezione condizionale Configurazione Vettore con i seguenti campi:

Pagina /vettori

La pagina Logistica → Vettori fornisce una vista aggregata di tutti i soggetti con ruolo Vettore. Consente di:

• Confrontare le tariffe tra vettori per zona e fascia di peso.
• Visualizzare le statistiche di performance: tempi medi di consegna, tasso di resa, numero spedizioni gestite.
• Accedere rapidamente alla scheda soggetto del vettore per modificare la configurazione.
• Impostare il vettore predefinito per zona o per cliente.

Il modulo Spedizioni e strettamente integrato con l'Archivio DDT. Il collegamento bidirezionale garantisce tracciabilita completa della merce.

Pulsante "Crea Spedizione" dal DDT

Ogni DDT in stato "Pronto per spedizione" presenta nell'intestazione il pulsante Crea Spedizione. Premendolo si avvia la procedura guidata di creazione spedizione con i dati precompilati dal DDT (v. Sezione 2, Modalita B).

Badge nella lista DDT

Nella lista dell'Archivio DDT, i documenti gia collegati a una spedizione mostrano il badge 🚚 accanto al numero. Cliccando sul badge si accede direttamente alla scheda della spedizione collegata.

Riferimenti incrociati

Dal modulo Documenti, è possibile creare una spedizione direttamente collegata a un DDT:

1. Aprire un documento di tipo DDT in modifica.
2. Nel footer del documento, premere il bottone Spedizione (ciano).
3. Il sistema crea una nuova spedizione pre-compilata con i dati del DDT: soggetto destinatario, indirizzo di spedizione, vettore, dati trasporto.
4. Completare eventuali dati mancanti (tracking, note vettore) e salvare.

A partire da aprile 2026, i DDT (Documenti di Trasporto) sono gestiti interamente nel modulo Documenti unificato. Non esiste più un archivio DDT separato.

Funzionalità DDT nel modulo Documenti

Aggiornamento strutturale del modulo Spedizioni con audit trail delle transizioni di stato, cestino limitato agli stati non finali e operazioni massive. Pensato per compliance (Art. 53 DPR 633/72) e tracciabilità delle consegne.

Audit trail su ogni modifica

Ogni PATCH/PUT sulla spedizione (cambio stato, tracking, date, costi, destinatario, note) viene registrato nella tabella log_modifiche_spedizioni. L'endpoint GET /api/spedizioni/:id/audit-log restituisce lo storico con valore precedente, valore nuovo, utente e data/ora.

Nella lista spedizioni e presente ora il pulsante 🕒 Storico modifiche che apre un modal con la cronologia. Risponde a: “chi ha marcato questa spedizione come consegnata e quando?”

Stessa logica su VettoreConfig: GET /api/spedizioni/vettori/:soggettoId/config-audit-log.

Validazione transizioni di stato

Il backend valida ora la matrice di transizioni ammesse. Tentativi di transizione non valida (es. CONSEGNATA → IN_ATTESA) vengono rifiutati con errore 409.

Cestino limitato agli stati non finali

Per rispetto della compliance, il soft-delete e consentito solo per spedizioni in stato IN_ATTESA o ANNULLATA. Le spedizioni CONSEGNATE restano immutabili per legge (traccia fiscale della consegna). Tentativi di eliminazione su altri stati vengono bloccati con errore 409.

• Pulsante 🗑 Apri cestino nell'header della lista.
• Azioni per riga nel cestino: ↺ Ripristina / ✗ Definitivo (hard delete irreversibile, solo se cancellata e stato IN_ATTESA/ANNULLATA).

Operazioni massive

Selezione multipla con checkbox sulla lista. Con almeno una spedizione selezionata compare una barra blu con:

• ✓ Marca consegnate: porta tutte le selezionate a CONSEGNATA con data comune. Le transizioni non valide vengono ignorate e riportate come invalidi nella risposta.
• ⇄ Cambia stato…: cambio stato massivo con validazione transizioni.
• 🗑 Cestino: soft-delete delle sole spedizioni IN_ATTESA/ANNULLATA; le altre vengono ignorate.

Endpoint: POST /api/spedizioni/bulk con action marca-consegnate, cambia-stato, soft-delete.

Timeline spedizione

L'endpoint GET /api/spedizioni/:id/timeline restituisce una vista cronologica che aggrega: audit modifiche + DDT collegati.

Audit configurazione vettore

Ogni modifica alla VettoreConfig (zone servite, tipi servizio, tariffe, referente, note operative) viene tracciata nella tabella log_modifiche_vettori_config. Utile per ricostruire variazioni di tariffario nel tempo.

Per le esigenze più sofisticate di spedizioni (etichette barcode, tracking corrieri, CMR internazionali, SSCC pallet, EDIFACT GDO, MUD rifiuti, ecc.) c'è una dashboard dedicata accessibile dal menu principale → Spedizioni avanzate.

Le 17 sezioni della dashboard

Come si usa

Ogni sezione ha una lista (elenco dei record esistenti) e, dove applicabile, un pulsante Nuovo per creare. L'interfaccia è semplice:

• Sidebar a sinistra — lista delle 17 sezioni. Click per cambiare vista
• Area centrale — tabella con i dati della sezione scelta
• Intestazione — pulsanti contestuali (Nuovo / Esporta / Filtra)

A partire dalla versione 2.2, il modulo Spedizioni adotta lo standard di certificazione NOX con i seguenti presidi:

Cestino e soft-delete

Gli elementi cancellati non vengono rimossi fisicamente ma spostati in un cestino interno (campi cancellatoIl / cancellatoDa). Dalla toolbar il pulsante Cestino alterna tra vista attivi e vista cestino. Dal cestino è possibile:

• Ripristinare l'elemento (riportarlo nella lista attiva) — operazione riservata ad amministratori.
• Eliminare definitivamente con motivazione obbligatoria — azione irreversibile, riservata ad amministratori, tracciata nell'audit log.

Azioni massive (bulk)

È possibile selezionare più elementi con le checkbox della prima colonna. Appare una barra inferiore con le azioni disponibili: Audit separato per config vettore. La risposta indica N operazioni riuscite / M fallite; i dettagli delle fallite compaiono nella console browser (F12).

Storico modifiche (audit log)

L'icona history nelle azioni di riga apre un modal con la storia completa delle modifiche: data, campo, valore precedente, valore nuovo, operatore, eventuale motivazione. I record di audit non sono modificabili né eliminabili via UI. Conservazione: indefinita (art. 2220 c.c. — 10 anni minimo).

Mascheramento dati sensibili (GDPR art. 32)

Se i campi modificati contengono dati sensibili (IBAN, Codice Fiscale, Partita IVA, password/token), l'audit log salva il valore mascherato anziché in chiaro:

Timeline aggregata

Per ciascun elemento è disponibile una vista Timeline che aggrega in ordine cronologico audit, eventi del ciclo di vita ed eventuali entità collegate (es. documenti, movimenti, storni).

RBAC uniforme

Tutte le azioni distruttive o massive (soft-delete, ripristino, eliminazione definitiva, bulk, storno) richiedono il ruolo ADMIN o superiore. Gli operatori possono continuare a creare / modificare / consultare secondo le proprie abilitazioni.

BOLLETTAZIONE v 2.2 — 9ª ondata (ALTA + MEDIA priorità)

Estensione completa del pacchetto di bollettazione/spedizioni con 13 macro-feature. Tutti gli endpoint sono montati sotto /api/bollettazione/* (router bollettazione-v22-wave9.routes.js). Dipendenza aggiunta: bwip-js (barcode Code128/EAN13); pdfkit e qrcode già presenti.

A. Etichette spedizione PDF 10x15 cm + barcode/QR

• Tabella etichette_spedizione: formato (10x15 / 10x20 / A6 / A4), tipo barcode (code128 / QR / code39 / ean13), hash SHA-256, numero/totale colli
• POST /api/bollettazione/etichette/genera body {spedizioneId | ddtId, formato, barcodeType, barcodeValue, numeroCollo, totaleColli}
• GET /api/bollettazione/etichette/download/:id — download PDF binario
• GET /api/bollettazione/etichette?spedizioneId=X — lista etichette generate
• File salvati in /app/etichette-pdf/

B. Corrieri — configurazione + creazione LDV programmatica

Adapter pattern per 6 provider: MOCK (funzionante, test), DHL Express, SDA Poste Italiane, GLS Italy, BRT Bartolini, TNT/FedEx (stub con TODO integrazione reale).

• Tabella corriere_config con api_endpoint, api_key, api_secret, account_number, flag attivo
• GET /api/bollettazione/corrieri/config — lista provider
• PUT /api/bollettazione/corrieri/config/:id [ADMIN] — imposta credenziali + attivazione
• POST /api/bollettazione/corrieri/crea-ldv/:spedizioneId [ADMIN] body {corriereCodice} — genera LDV, salva tracking su spedizioni.rifVettore, crea evento PRESA_IN_CARICO

C. Tracking real-time + webhook

• Tabella spedizione_tracking_eventi: stato (PRESA_IN_CARICO, IN_TRANSITO, IN_CONSEGNA, CONSEGNATA, GIACENZA, ECCEZIONE, RIENTRO), località, timestamp, fonte (manuale/webhook/polling/import), payload grezzo JSONB
• GET /api/bollettazione/tracking/:spedizioneId — storico eventi (DESC)
• POST /api/bollettazione/tracking/:spedizioneId/evento — aggiunge evento manuale
• POST /api/bollettazione/tracking/webhook/:corriereCodice — endpoint pubblico per push corrieri (body: trackingNumber, stato, localita...)
• Sync automatico stato spedizione su CONSEGNATA/RIENTRO/ANNULLATA

D. Packing list multi-collo

Gestione dimensioni e peso per singolo collo, essenziale per spedizioni fragili, pesanti o ADR (merci pericolose).

• Tabella packing_list: numero collo, peso kg, dimensioni LxPxH cm, contenuto, flag fragile/pericoloso, codice ADR UN number, temperatura controllata
• GET/POST /api/bollettazione/packing-list/:ddtId body {colli:[{pesoKg, lunghezzaCm, larghezzaCm, altezzaCm, contenutoDescrizione, fragile, pericoloso, codiceAdr}]}
• Aggiorna automaticamente documenti.numeroColli e documenti.peso sul documento DDT

E. DDT di reso cliente / fornitore (art. 53 DPR 633/72)

Workflow dedicato per i resi con creazione automatica del DDT di reso + opzionale nota di credito collegata.

• Nuovi campi documenti: resoTipo (RESO_CLIENTE | RESO_FORNITORE), resoDocumentoOrigineId, resoMotivazione, resoNotaCreditoId
• POST /api/bollettazione/ddt-reso/:docOrigineId [ADMIN] body {tipo, motivazione, righeDaStornare?, creaNotaCredito?}
• Genera DDT con causale RESO_DA_CLIENTE / RESO_A_FORNITORE; se creaNotaCredito=true (solo RESO_CLIENTE) emette anche TD04 con importi negativi collegata

F. Conto deposito / visione / lavorazione (art. 53)

Workflow completo per DDT in conto deposito (merce depositata), visione (da approvare) e lavorazione (da lavorare e restituire).

• Tabella conto_deposito: data consegna + scadenza rientro, stato (APERTO / RIENTRATO_PARZIALE / RIENTRATO / FATTURATO / SCADUTO), firma fornitore base64, fattura definitiva collegata
• POST /api/bollettazione/conto-deposito/:ddtId [ADMIN] body {tipo, dataConsegna, dataScadenzaRientro, note}
• PATCH /conto-deposito/:id/rientro [ADMIN] body {ddtRientroId, conformita, firmaBase64, parziale}
• PATCH /conto-deposito/:id/fattura [ADMIN] — vendita definitiva (stato FATTURATO)
• GET /conto-deposito?stato=APERTO&tipo=VISIONE

G. DDT cumulativi multi-destinazione

• Tabella ddt_destinazioni_multiple: array di destinatari con indirizzo + lista righe associate
• GET/POST /api/bollettazione/ddt-multi-dest/:ddtId

H. Bolle doganali DAU (export extra-UE)

• Tabella bolle_doganali: DAU MRN, regime doganale (10 export / 31 riesportazione), ufficio dogana, paese destinazione, peso lordo/netto, valore SDV, certificato origine (EUR1/ATR), INCOTERMS, modo trasporto
• Stato workflow: BOZZA → PRESENTATA → ACCETTATA → USCITA_CONFERMATA
• POST/GET /api/bollettazione/bolle-doganali, PATCH /:id/stato [ADMIN]

I. CMR (Convention Marchandises Routiers)

Lettera di vettura internazionale (Convenzione di Ginevra 19.05.1956) per trasporti UE.

• Tabella cmr_dichiarazioni: mittente, destinatario, luoghi presa/consegna, targhe motrice/rimorchio, merci (peso/volume/colli/imballaggio), classe ADR, porto, istruzioni
• POST /api/bollettazione/cmr — crea dichiarazione
• POST /api/bollettazione/cmr/:id/genera-pdf [ADMIN] — produce PDF A4 conforme schema internazionale, salva in /app/cmr-pdf/

J. POD — Proof of Delivery firma digitale destinatario

• Tabella pod_consegne: firma touch base64, documento identità (CI/PATENTE/PASSAPORTO), IP, timestamp, hash SHA-256 integrità
• POST /api/bollettazione/pod body {spedizioneId | ddtId, firmatoDaNome, firmatoDaRuolo, documentoIdentitaTipo, documentoIdentitaNumero, firmaBase64, note}
• Auto-aggiorna spedizione a CONSEGNATA con evento tracking
• GET /api/bollettazione/pod/:spedizioneId — storico firme

K. Magazzino automatico da DDT

Trigger di scarico/carico magazzino automatico dopo emissione DDT.

• Tabella log_magazzino_auto: tipo trigger (DDT_EMESSO/DDT_RESO/DDT_RESO_FORN), movimenti generati[], esito, errore
• POST /api/bollettazione/magazzino-auto/ddt/:docId [ADMIN] body {magazzinoId, forza?}
• Pattern: DDT vendita → SCARICO_VENDITA, reso cliente → CARICO_RESO_CLIENTE, reso fornitore → SCARICO_RESO_FORN
• Previene doppia esecuzione (flag forza per override)

L. Fattura accompagnatoria (flag TD01 + trasporto)

Alternativa al DDT+fattura differita: TD01 con tutti i dati trasporto contestuali.

• Campo documenti.fatturaAccompagnatoriaFlag
• PATCH /api/bollettazione/fattura-accomp/:docId body {attiva}
• Validazione: flag attivabile solo su TD01 con dataInizioTrasporto compilata

Chiusura dei residui BASSA: SSCC GS1 per pallet GDO, EDIFACT DESADV, MUD/FIR rifiuti, import tracking CSV, trasformazione automatica ordine cliente → DDT, scaffolding HTTP reale corrieri con logging request/response. Dipendenze già disponibili (pdfkit, bwip-js, multer, csv-parse).

A. SSCC GS1 — Serial Shipping Container Code (pallet GDO)

Codice 18 cifre standard GS1 (ext_digit + company_prefix + serial + check_digit) calcolato con algoritmo MOD-10 GS1. Essenziale per etichettatura pallet destinati alla GDO (Coop, Conad, Esselunga, Carrefour) e tracciabilità lotti.

• Tabelle: sscc_codici (univoco 18 cifre) + sscc_contatore (serial per company prefix)
• POST /api/bollettazione/sscc/assegna [ADMIN] body {companyPrefix, quantita, ddtId?, packingListId?, extDigit?} — genera N SSCC consecutivi
• POST /api/bollettazione/sscc/:id/genera-etichetta — PDF A5 con barcode GS1-128 AI(00) + destinazione DDT
• GET /api/bollettazione/sscc?ddtId=X&stato=ASSEGNATO
• Stati: ASSEGNATO → SPEDITO → RICONSEGNATO / ANNULLATO

B. EDIFACT DESADV per GDO (UN/EDIFACT D01B)

Generazione del messaggio DESADV (Despatch Advice 351) conforme standard UN/EDIFACT D01B EAN005 per comunicazione anticipata di spedizione ai portali della Grande Distribuzione.

• Tabella edifact_messaggi: tipo (DESADV/INVOIC/ORDERS/RECADV), partner_gdo, partner_gln (13 cifre Global Location Number), esito (BOZZA/INVIATO/ACCETTATO/RIFIUTATO)
• POST /api/bollettazione/edifact/desadv/:ddtId [ADMIN] body {partnerGdo, partnerGln, glnMittente}
• Genera UNB+UNH+BGM+DTM+NAD+CPS+PAC+PCI+GIN+LIN+IMD+QTY+UNS+CNT+UNT+UNZ con segmenti SSCC se presenti
• GET /api/bollettazione/edifact/:id/download — download testo .edi
• GET /api/bollettazione/edifact?partnerGdo=COOP&ddtId=X

C. MUD/FIR — Formulario Identificazione Rifiuti (art. 193 D.Lgs 152/2006)

Documento obbligatorio per il trasporto dei rifiuti con tracciabilità produttore → trasportatore → destinatario. Sezioni complete secondo DM 1/4/1998 n.145.

• Tabella formulari_rifiuti con 25+ campi: dati produttore, trasportatore (iscrizione Albo Gestori Ambientali), destinatario (autorizzazione), rifiuto (CER, stato fisico, classe pericolo HP1-HP15, quantità kg, destinazione R/D)
• Anagrafica cer_codici con 18 codici CER seed (150101-150110, 200101-200301, 080317-080318, 160213-160214, 180103-180104)
• GET /api/bollettazione/fir/cer?q=150&pericoloso=true — cerca codici CER
• POST /api/bollettazione/fir [ADMIN] — crea FIR (numeroFir, dataEmissione, produttoreRagioneSociale, cerCodice, rifiutoQuantitaKg obbligatori)
• POST /api/bollettazione/fir/:id/genera-pdf [ADMIN] — PDF A4 conforme schema
• GET /api/bollettazione/fir?stato=EMESSO&cerCodice=150106

D. Import tracking CSV

Fallback per corrieri senza webhook/API real-time: upload CSV ricevuto dal corriere con mapping automatico delle colonne (tracking_number, stato, localita, descrizione, timestamp supportati in varianti multilingua).

• Tabella tracking_import_batch: nome file, righe totali/importate/scartate, esito (OK/ERRORE/PARZIALE)
• POST /api/bollettazione/tracking-import/:corriereCodice [ADMIN] form-data file (CSV, max 10MB)
• Supporta delimitatori , ; \t; matching spedizione via rifVettore; righe senza match → scartate
• GET /api/bollettazione/tracking-import/batch — storico batch

E. Ordine cliente (ORD) → DDT

Trasformazione automatica di un documento tipo ORD (Ordine Cliente) in un DDT con clonazione righe e campi destinazione. Supporta evasione parziale (subset di righe) + chiusura ordine contestuale.

• GET /api/bollettazione/ordine-to-ddt/ordini-evadibili?soggettoId=X — elenco ORD in stato EMESSO/CONFERMATO/BOZZA
• POST /api/bollettazione/ordine-to-ddt/:ordineId [ADMIN] body {righeDaEvadere?:[ids], chiudiOrdine?:bool}
• Genera DDT con: causale VENDITA, numero progressivo DDT dell'anno, riferimento a documentoOrigineId, campi destinazione copiati dall'ordine

F. Corriere HTTP — integrazione reale scaffolding

Endpoint /corriere-http/* con logging di tutte le chiamate HTTP verso i corrieri reali. Utile per debug integrazione + audit compliance. Base per l'implementazione adapter reali DHL Express SDK, SDA SOAP, GLS REST, BRT, TNT/FedEx.

• Tabella corriere_api_log: endpoint, method, request_body (JSONB), response_status, response_body (JSONB), durata_ms, esito (OK/ERRORE/TIMEOUT)
• POST /api/bollettazione/corriere-http/test/:corriereCodice [ADMIN] — test connettività + logging
• GET /api/bollettazione/corriere-http/log?corriereCodice=DHL&spedizioneId=X