Spedizioni & Vettori

L'Archivio Spedizioni è la pagina centrale del modulo: l'elenco delle spedizioni, con filtri, contatori e le azioni di ogni riga.

Filtri e ricerca

Si filtra per stato, vettore e periodo (sulla data di ritiro prevista). La ricerca testuale cerca nel numero della spedizione, nel numero di tracking, nella località e nel nome del destinatario. I DDT di una spedizione si vedono col pulsante 📄 DDT collegati.

Contatori

In alto: totale, in attesa, in transito (ritirate e in viaggio) e consegnate fra quelle in elenco. Tempi medi di consegna e tasso di resa non ci sono.

Colonne

Numero, data, destinatario, vettore, colli, peso (in formato italiano, «12,5 kg»), costo, ritiro previsto e stato con il numero di tracking. Uno zero resta zero: una spedizione gratuita mostra 0,00 €, non «—». Il costo lo vede solo chi ha il permesso «Vedere costi e margini».

Stati della spedizione

Chi può fare cosa

• Creare, modificare e aggiornare lo stato: chi ha il permesso di registrare movimenti di magazzino (il magazziniere, l'autista).
• Cestino e ripristino, configurazione dei vettori: gli amministratori.
• Costi e tariffe: chi ha il permesso «Vedere costi e margini». Chi non lo ha non li vede e non li cambia.

I pulsanti che non puoi usare non compaiono.

1. Premi + Nuova Spedizione (oppure, da un DDT, il pulsante Spedizione: vedi sezione 6).
2. Scegli il vettore fra quelli configurati (obbligatorio).
3. Scegli i DDT da collegare: l'elenco li cerca per numero, cliente o località, e mostra solo i DDT di vendita emessi che non sono già in un'altra spedizione (le bozze no: la merce parte col DDT emesso). Colli e peso dei DDT scelti si sommano.
4. Il destinatario si cerca fra i clienti; con «Precompila indirizzo dal primo DDT» l'indirizzo arriva dal DDT.
5. Colli, peso, aspetto della merce, data di ritiro prevista, note per il vettore.
6. Il costo (se vedi i costi): scrivilo, oppure premi Calcola dalle tariffe del vettore. Per ogni tariffa del vettore il programma calcola base + €/kg × peso + €/collo × colli e segna quella della zona di destinazione (provincia o paese); clicchi quella che vale.
7. Crea Spedizione: nasce IN_ATTESA.

Il vettore va sul DDT

Salvando, il vettore della spedizione viene scritto sui DDT collegati, e il DDT stampato lo riporta. Se un DDT non aveva colli, peso o aspetto e la spedizione ha un DDT solo, anche quelli passano sul DDT. Ogni cambio finisce nel registro modifiche del DDT. Se un DDT indicava un altro vettore, prende quello della spedizione e il messaggio di conferma lo dice.

Modificare una spedizione

Il pulsante ✏️ della riga riapre la stessa finestra: si cambiano i campi, si aggiungono o tolgono DDT. Si scrive solo quello che hai cambiato, e tutto va nello storico (🕒). Una spedizione CONSEGNATA o ANNULLATA non si modifica più.

Cosa non c'è

• Addebito del trasporto al cliente: il costo della spedizione non diventa una riga di DDT o di fattura. Le spese di trasporto da far pagare al cliente si scrivono come riga del documento.
• Contrassegno: non si gestisce.
• Etichette per collo: non dalle Spedizioni (esistono solo in Strumenti di spedizione).
• Volume: non si chiede.

1. Pulsante 📍 Aggiorna stato della riga.
2. Scegli il nuovo stato fra quelli ammessi; per RITIRATA e CONSEGNATA la data proposta è oggi in Italia (si può cambiare).
3. Scrivi il numero di tracking del corriere e una nota, se serve.

Col numero di tracking, l'elenco mostra il link al sito del corriere: per BRT, GLS, SDA, Poste, DHL, TNT, FedEx e UPS lo deduce dal nome del vettore, per gli altri usa l'indirizzo scritto nella configurazione del vettore. Il programma non interroga i corrieri: il link si apre nel loro sito.

Con più spedizioni selezionate, ✓ Marca consegnate e ⇄ Cambia stato… aprono una finestra con l'elenco degli stati e il calendario per la data; le spedizioni per cui il passaggio non è consentito restano come sono, e il programma lo dice.

Un vettore è un soggetto dell'anagrafica col ruolo Vettore. La sua configurazione si scrive dalla scheda del soggetto o dalla pagina Vettori (solo amministratori):

La pagina Vettori fa parte del pacchetto Vendite B2B, come le spedizioni: in Aziende & Licenze il modulo Vettori sta lì. Chi non ha Vendite B2B non vede la pagina (le sue configurazioni si salvano nelle API delle spedizioni, che sono di quel pacchetto); il vettore da scrivere su un DDT resta un soggetto dell'anagrafica e si sceglie come sempre.

La pagina Vettori elenca i vettori configurati e non. Confronto tariffe, statistiche dei vettori e vettore predefinito per cliente non ci sono.

Il collegamento è nei due versi:

Mettendo una spedizione nel cestino, i suoi DDT si sganciano (tornano fra quelli da collegare) e lo storico lo registra; il ripristino li riaggancia, se nel frattempo non sono finiti in un'altra spedizione.

1. Apri il DDT dai Documenti.
2. Premi Spedizione: si apre la nuova spedizione con quel DDT già scelto.
3. Scegli il vettore, completa e salva: il vettore arriva sul DDT.

I DDT (Documenti di Trasporto) sono gestiti interamente nel modulo Documenti unificato. Non esiste più un archivio DDT separato.

Funzionalità DDT nel modulo Documenti

Ogni spedizione tiene lo storico delle sue modifiche, accetta solo i passaggi di stato sensati e va nel cestino solo se non è partita.

Audit trail su ogni modifica

Ogni modifica della spedizione (cambio stato, tracking, date, costi, destinatario, DDT collegati, note), la consegna automatica dalla firma del DDT e lo sgancio dei DDT nel cestino vengono registrati 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 la data scelta nel calendario (proposta: oggi). Le transizioni non valide restano come sono e il programma le conta.
• ⇄ Cambia stato…: lo stato si sceglie da un elenco.
• 🗑 Cestino (amministratori): solo le spedizioni IN_ATTESA/ANNULLATA; i loro DDT si sganciano.

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 le modifiche e i DDT collegati (non c'è ancora una schermata che la mostri).

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: menu Magazzino → Strumenti di spedizione.

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)

Cosa fanno le sezioni

• Gli elenchi mostrano i dati: packing list, destinazioni multiple, DAU, prove di consegna (POD), messaggi EDIFACT, storico degli import CSV del tracking e formulari MUD/FIR elencano quello che è stato registrato.
• Ogni sezione ha il suo modulo «Nuovo», con i campi che servono a quella sezione (per esempio il DDT di partenza, oppure cliente e codice GLN per un messaggio EDIFACT).
• Consegna registrata: quando il tracciamento o il corriere segnala che la merce è consegnata, la spedizione passa da sola a consegnata, con la data di consegna. Un rientro la segna come resa, un annullamento come annullata.
• DDT di reso con nota di credito: per un reso del cliente puoi chiedere di creare insieme anche la nota di credito collegata. Nascono tutti e due, o nessuno dei due.
• Numeri dal sezionale: DDT di reso, DDT creati da un ordine e autofatture nascono in bozza e prendono il numero quando li emetti, come tutti gli altri documenti. Così non si creano numeri doppi o salti.

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) crea insieme anche la nota di credito (TD04) collegata, con gli importi scritti in positivo (il segno lo dà il tipo di documento). DDT e nota nascono insieme o non nasce nessuno dei due; entrambi in bozza, e prendono il numero all'emissione

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