Runbook Operativo MonosTech

Procedure operative quotidiane, gestione anomalie e troubleshooting — Ultimo aggiornamento: 19/08/2026

1. Operazioni Automatiche Giornaliere

Il sistema funziona in autonomia. Ogni giorno vengono eseguite automaticamente queste operazioni:

Cosa controllare ogni giorno

1. Report Telegram (bot @monostestacv_bot): dopo le 04:00 e le 16:00 arriva un riepilogo con numero prodotti aggiornati, alert WARNING / HOLD / CRITICAL, stato peak mode, eventuali errori.
2. n8n (https://n8n.srv1203683.hstgr.cloud): verificare che non ci siano workflow falliti nella sezione “Executions”.

2. Gestione Alert Telegram

Quando arriva un alert dal bot Telegram, ecco come interpretarlo e agire:

WARNING — Livello 1: Solo informativo

HOLD — Livello 2: Prezzo congelato, richiede revisione

CRITICAL — Livello 3: Fornitore escluso o prodotto in DRAFT

3. Procedure Manuali

3.1 Forzare un refresh prezzi

Se serve aggiornare i prezzi fuori dagli orari schedulati:

1. Andare su n8n → workflow Algoritmo Pricing Giornaliero
2. Cliccare “Test workflow”
3. Attendere il completamento (~105 secondi)
4. Verificare il report Telegram

3.2 Forzare sync Shopify

Se serve sincronizzare Shopify fuori dagli orari schedulati:

1. Andare su n8n → workflow Shopify - Sync Prezzi e Stock
2. Cliccare “Test workflow”
3. Attendere il completamento

3.3 Import manuale di un fornitore

Se un listino non si è aggiornato:

1. Andare su n8n → workflow di importazione del fornitore (es. Importazione Tdsynnex SQL)
2. Cliccare “Test workflow”
3. Verificare nella tabella prodotti che i dati siano aggiornati (colonna data_aggiornamento)

3.4 Bloccare un EAN dalla pubblicazione

1. Aggiungere l’EAN alla tabella ean_bloccati (via NocoDB o Supabase)
2. Campi: ean, motivo, data_inserimento
3. Al prossimo ciclo pricing, il prodotto verrà messo in DRAFT

3.5 Aggiungere un’eccezione promo

1. Aggiungere il record alla tabella promo_whitelist (via NocoDB)
2. Campi necessari: ean, fornitore, sconto_max_pct, data_inizio, data_fine
3. Il sistema PS-06 accetterà le deviazioni entro il limite specificato

3.6 Verificare discrepanze Shopify vs Database

1. Andare su n8n → workflow Verifica Shopify vs DB
2. Cliccare “Test workflow”
3. Il report arriva su Telegram con le discrepanze trovate

4. Tool Ordini Amazon

Pagina web per analizzare gli ordini Amazon e scegliere da dove evadere ogni riga: ordini-amazon.html.

4.1 Come si usa

1. Cliccare «Scarica ordini da Amazon» nella pagina e scegliere il periodo (§4.1b). In alternativa, esportare l’All Orders Report da Seller Central (Reports → Order Reports → All Orders) e trascinare il file nella pagina
2. Cliccare Analizza Ordini. Di default vengono analizzati solo gli ordini ancora da gestire: quelli già spediti o annullati sono esclusi automaticamente (per includerli tutti, spuntare «Includi anche ordini già spediti/annullati» prima di analizzare). Una nota sotto le card indica quante righe sono state escluse
3. Per ogni riga il tool abbina il prodotto al database (per ASIN/EAN, con fallback) e mostra il fornitore raccomandato con profitto e margine reali
4. Le righe escono ordinate per data massima di spedizione crescente (§4.7c): la più urgente in cima, e in fondo quelle per cui Amazon non comunica quella data, nell’ordine del report
5. Cliccando una riga si apre il confronto completo di tutte le opzioni disponibili: per ciascuna sono mostrati prezzo d’acquisto (col tipo di prezzo applicato: listino, promozione o prezzo bid — vedi §4.8), trasporto (con nolo e supplemento carburante separati dove la tariffa è a corriere), eventuali costi accessori, commissioni, profitto e margine — tutti gli importi sono netti IVA
6. Per accettare la fonte raccomandata basta Conferma sull’opzione consigliata: la riga risulta già gestita senza scrivere altro. Se invece si evade da una fonte diversa, usare Scegli sull’opzione preferita e registrare la motivazione (vedi §4.6)
7. Le righe già decise restano riconoscibili nelle analisi successive (“già gestita” sotto l’Order ID) e si possono nascondere con la spunta «Nascondi le righe già gestite». Gestita significa che qualcuno ha scelto la fonte, non che l’ordine sia stato evaso

4.1b Scarico ordini da Amazon: periodo e messaggi

Il bottone «Scarica ordini da Amazon» sopra l’area di caricamento chiede il report via Amazon SP-API e lo carica nel tool. Compare solo se l’interruttore spapi_import_report (NocoDB, tool_amazon_soglie) è acceso; con l’interruttore spento si usa il caricamento del file (§4.1).

1. Scegliere il periodo: “dall’ultimo scarico” (predefinito, se esiste già uno scarico riuscito) oppure 7/15/30/60/90 giorni
2. Cliccare il bottone: il tool attende che Amazon prepari il report (di solito decine di secondi, timeout a 10 minuti) e lo carica da solo
3. Cliccare Analizza Ordini come con un file caricato a mano

La finestra “dall’ultimo scarico” si sovrappone di un’ora con la precedente apposta: un ordine già visto non costa nulla (il tool lo segnala come già visto/gestito), mentre un ordine aggiornato fra due scarichi altrimenti sfuggirebbe. Stato e cronologia degli scarichi in amazon_report_scarichi.

4.2 Fonte merce e modalità di spedizione

Ogni opzione indica da dove proviene la merce e chi spedisce al cliente — due informazioni separate:

Le combinazioni ammesse e le tariffe si modificano da NocoDB senza toccare codice: tabella regole_fonte_spedizione (quali combinazioni esistono) e fornitori_spedizione (le tariffe).

Spedizioni Italia: il confronto a contratto nostro include BRT, GLS e FedEx, con le tariffe del contratto BC420 (zone FX_IT e FX_IT_CSS in corrieri_tariffe). FedEx risulta il più conveniente nella fascia 3–20 kg. Per Calabria, Sicilia e Sardegna vale un listino dedicato più caro, selezionato dal CAP del destinatario tramite il token IT_CSS. Fino al 20/08/2026 la sede di Catania lo usava sempre, a prescindere dalla destinazione (parametro fedex_zona_forzata in fornitori_spedizione.config_extra); rimosso dopo la conferma della cliente che conta solo la destinazione — oggi la zona FedEx dipende solo dal CAP del cliente, come per le altre fonti. Il supplemento carburante FedEx Italia è 18,92% (indice mensile scontato del 25% come da contratto) e va ricalcolato a ogni cambio di mese in corrieri_supplemento_carburante, chiudendo la riga precedente con valido_al e inserendone una nuova — mai modificando quella esistente.

Spedizioni estero: il trasporto a contratto nostro usa le tariffe reali per paese (GLS/BRT/FedEx, corriere più conveniente scelto in automatico); le isole (Canarie, Baleari, Madera, Azzorre, Corsica…) sono riconosciute dal CAP e costano più del continente (un costo reale, non un errore). Se nessun corriere copre la spedizione — peso oltre i massimi (GLS 40 kg, FedEx ~70 kg, BRT 150 kg) o paese/CAP non a tariffario — l’opzione segna “fuori copertura corriere”, non viene mai raccomandata e la riga passa in In verifica: verificare il costo a mano. Le fonti solo-Italia (V-Valley, conto deposito a gestione Esprinet) restano non disponibili per l’estero.

Contratto BRT estero: i listini esteri BRT sono quelli del contratto firmato il 22/07/2026 (validità 16/03–31/12/2026), con supplemento carburante è passato dal 16%/14,5% all’8%, quindi BRT vince molto più spesso il confronto con GLS e FedEx sulle tratte estere: sui prodotti Focelda verso la Germania, per esempio, il trasporto scende da €12,92 a €11,33. In più, BRT ora copre fino a 150 kg (prima si fermava a 100) e ha tariffe proprie per Norvegia, Andorra, Gibilterra, Ceuta/Melilla e per i territori insulari, dove prima era disponibile solo GLS. L’Italia non è stata rinnovata: il listino nazionale BRT resta quello del 2023 (vedi domande aperte). L’8% resta valido finché il gasolio non supera ~2,30 €/lt; quando cambierà, vale la stessa regola già in uso per FedEx — chiudere la riga in corrieri_supplemento_carburante con valido_al e inserirne una nuova, mai modificare quella esistente (a parità di validità la funzione sceglie la percentuale più alta, non la più recente).

4.3 Come leggere lo stato di ogni riga

4.4 Costo del conto deposito: certificato o stimato

Le opzioni conto deposito mostrano un badge sul costo:

• Costo certificato (verde): il costo viene dalle fatture di acquisto riconciliate — margine affidabile
• In verifica (arancio): costo solo stimato dal valore di magazzino Esprinet — margine indicativo, l’opzione non viene mai raccomandata automaticamente

Per certificare i costi: confermare le proposte di riconciliazione in NocoDB, tabella esprinet_depot_valorizzazione (filtrare stato = proposto, confermare o rifiutare ogni match fattura↔prodotto).

Come nascono le proposte: la quadratura

Il sistema non abbina più le fatture solo per codice EAN e quantità: confronta le fatture di acquisto con le spedizioni reali in uscita dal deposito (i DDT Esprinet, scaricati ogni mattina) e con la giacenza attuale. Vengono proposte solo le fatture la cui combinazione fa quadrare i conti: pezzi entrati − pezzi usciti = pezzi in giacenza, con date coerenti.

• La colonna match dettaglio spiega il calcolo per esteso: quanti pezzi sono entrati (e con quali fatture), quanti sono usciti, quanti restano in giacenza e quale quota della fattura proposta è ancora in deposito.
• La quantità assegnata è la parte di quella fattura ancora in giacenza, non l’intera fattura: le fatture già interamente spedite sono citate nel dettaglio ma non proposte.
• Le proposte non ancora confermate possono essere aggiornate o rimosse automaticamente nei giorni successivi se i conti cambiano. Le righe confermate o rifiutate non vengono mai toccate; lo stesso vale per le proposte con un testo nel campo note — scrivere una nota è quindi il modo per “bloccare” una proposta in valutazione.
• Se per un prodotto la quadratura non riesce (per esempio mancano fatture nel registro), le proposte seguono il vecchio criterio per EAN e quantità e il dettaglio inizia con “Quadratura non riuscita”: trattarle con più cautela.

Per una panoramica per prodotto (giacenza, pezzi usciti, copertura delle proposte) è consultabile in NocoDB la vista v_depot_quadratura_prodotto.

4.5 Commissioni Amazon

Il tool chiede ad Amazon la commissione reale di ogni riga (per prodotto, marketplace e prezzo di vendita) e la conserva in amazon_fee_cache per riusarla nelle analisi successive (validità spapi_fee_ttl_gg giorni, in tool_amazon_soglie). Non esiste una tabella di ripiego: una riga senza commissione resta In verifica, non viene raccomandata e va rianalizzata.

Ogni analisi scrive una riga in tool_amazon_analisi_log: se righe_fee_mancante o fee_fallite_permanenti crescono da un giorno all’altro, Amazon sta rifiutando le richieste e la colonna nota dice quali chiavi e con che errore.

4.6 Scelta manuale di una fonte (con motivazione)

Si può scegliere operativamente una fonte diversa da quella raccomandata, lasciando traccia del perché:

1. Aprire il confronto fornitori (click sulla riga) e cliccare Scegli sull’opzione preferita
2. Scrivere la motivazione (obbligatoria) e il proprio nome, poi Salva scelta
3. La riga mostra il badge viola SCELTA MANUALE al posto della raccomandazione; passando il mouse si leggono autore, data e motivazione

La scelta è salvata nel database: ricaricando lo stesso report nei giorni successivi riappare automaticamente. Per cambiarla basta scegliere un’altra opzione (la precedente resta in archivio); per rimuoverla usare Annulla scelta. Lo storico completo è consultabile in NocoDB, tabella tool_amazon_scelte.

4.7 Freschezza dei dati e tempi di consegna

Ogni opzione del confronto mostra quando sono stati aggiornati prezzo e disponibilità della fonte (riga “🕐 dato al gg/mm/aaaa hh:mm”):

• Nessuna nota: dato recente
• “non recente” (arancio): oltre la soglia di avviso — gli import dei cataloghi fornitori sono manuali, il listino potrebbe essere cambiato. La riga passa in stato Avviso
• “oltre soglia critica” (rosso): il dato è troppo vecchio — l’opzione non viene mai raccomandata automaticamente e la riga passa in In verifica. Per i cataloghi fornitore la soglia critica è di 30 giorni: riguarda soprattutto i listini non più aggiornati (es. Xpress, fermo all’11/12/2025) e le singole righe non più presenti nei CSV correnti

Le soglie si regolano da NocoDB, tabella tool_amazon_soglie (effetto immediato senza interventi tecnici). La stessa tabella contiene le soglie di aging conto deposito (merce ferma da segnalare, default 90 giorni), dell’avviso perdita (differenza minima in euro e in percentuale), del margine sulla consegna promessa (promise_margine_gg, §4.7b) e gli interruttori delle funzioni Amazon SP-API (spapi_*). La colonna unita dice come leggere il valore: ore, giorni, euro, percentuale o flag. Ogni opzione mostra anche il lead time (“🚚 lead time X gg”): per le opzioni Esprinet è lo SLA del corriere dai report Esprinet, mostrato per corriere (es. “GLS 2 gg · BRT 3 gg”) e sovrascritto a ogni report giornaliero; per gli altri fornitori resta provvisorio “(da confermare)”. Non blocca mai la raccomandazione. Riferimento SLA in lead_time_esprinet (NocoDB).

4.7b Consegna promessa ad Amazon

La colonna Consegna prom. riporta la data entro cui l’ordine è stato promesso al cliente, chiesta ad Amazon per ogni ordine del report e conservata in cache per 12 ore. È vuota quando Amazon non la comunica (ordini non gestiti da noi, o ancora in attesa).

Se la fonte raccomandata arriverebbe a ridosso o oltre quella data, la riga passa in Avviso con badge RITARDO e il motivo indica il margine in giorni. Il margine di preavviso è la soglia promise_margine_gg in tool_amazon_soglie (1 giorno di serie); l’interruttore è spapi_promise_date.

4.7c Data massima di spedizione

La colonna Spedire entro riporta la data limite di partenza dell’ordine (LatestShipDate), quella che su Seller Central sta nell’elenco degli ordini da spedire. Arriva dalla stessa chiamata getOrders della consegna promessa (§4.7b): stesso interruttore spapi_promise_date, stessa cache di 12 ore, nessuna richiesta aggiuntiva ad Amazon. Non serve caricare il report degli ordini non spediti.

I badge SCADUTA, OGGI e DOMANI compaiono in base ai giorni interi che restano, e negli stessi tre casi la riga porta un avviso in chiaro nel pannello di dettaglio. La card Da spedire entro oggi somma le righe scadute e quelle in scadenza; mostra “—” (non zero) quando nessuna riga del report ha quella data, per non far leggere “nessuna urgenza” dove il dato manca.

Con l’interruttore spento la colonna resta vuota e le righe tornano nell’ordine del report. In cache le date stanno su amazon_ordine_righe, colonne ship_earliest e ship_latest accanto a promise_earliest/promise_latest (visibili da NocoDB). Sono vuote per gli ordini che Amazon non gestisce come seller-fulfilled e per quelli in stato Pending/PendingAvailability/Canceled.

4.8 Prezzi: listino, promozioni e prezzi bid

Il prezzo d’acquisto di ogni opzione è il migliore tra listino, promozione e prezzo bid validi per quella riga (quantità e date comprese). Un badge indica quale prezzo è stato usato; passando il mouse sulla cella Prezzo Acq. si vede la composizione (base + eco-contributi).

Da dove arrivano i bid: quelli TD Synnex sono importati automaticamente dal file ShipAndDebit_EndCust.txt insieme agli altri file TD (a ogni import vengono sostituiti con la versione aggiornata del file). È possibile inserire bid a mano da NocoDB nella tabella prezzi_bid per qualsiasi fornitore (es. accordi IMA comunicati via email): impostare origine = manuale — le righe manuali non vengono mai toccate dagli import. Compilare almeno fornitore, sku (codice articolo del fornitore), prezzo e, se nota, la scadenza.

4.9 Ordini ai fornitori (strumento separato, non invia)

Pagina https://docs.srv1203683.hstgr.cloud/ordini-fornitore.html (nessun link dal tool ordini): dalle righe gestite compone un ordine per ordine Amazon e fornitore, lo controlla e lo tiene in attesa di conferma. Alla conferma il file XLS di TD Synnex viene scritto sul VPS in /local-files/ordini-fornitore/; email e richieste API Esprinet restano composte nel database. Nessun invio parte da qui. Guida: guida-ordini-fornitori.html.

• Ordine bloccato per indirizzo: caricare nella pagina il report «Ordini non spediti» di Seller Central (o inserire l’indirizzo a mano), poi Prepara ordini fornitore.
• Ordine TD bloccato per CodCli: manca il codice cliente in fornitori_ordine_config (NocoDB), riga MONOS × Tdsynnex.
• Riga «fuori_tolleranza»: la verifica prezzo (fn_tool_verifica_riga_ordine, tolleranze in tool_amazon_soglie) non riconosce il prezzo atteso fra bid, riservato, standard e promo del catalogo; controllare il listino del fornitore in prodotti.
• Tabelle: tool_ordini_fornitore, _righe, _verifiche, amazon_ordini, fornitori_ordine_config, tool_ordini_fornitore_esclusioni. Le tabelle ordini_fornitore* senza prefisso sono del foglio Google di Viviana: non toccarle.
• Spegnere lo strumento: ordini_fornitore_attivo = 0 in tool_amazon_soglie. Email di riepilogo alle 08:30 solo se ci sono ordini bloccati da >24 h o pronti da >48 h.
• Workflow: Ordini Fornitore - Indirizzi WOBqOAuLxArohHrN, Prepara Mjp29uOIvhkHc7GV, Conferma PzhvGuyCabo8zjKJ, File vdDPxTaGVEn6LLAM, Stato oSmd3plCp9gXV7Tw, Guardia PcVQGgX3ubCyYS8T.

5. Troubleshooting

5.1 Token Shopify scaduto

Sintomo: errori “Unauthorized” o “401” nei workflow Shopify.

5.2 Workflow n8n fallito

Sintomo: workflow con stato “Error” nella lista esecuzioni n8n.

Diagnosi:

1. Aprire l’esecuzione fallita in n8n
2. Individuare il nodo rosso (quello che ha generato l’errore)
3. Leggere il messaggio d’errore

Cause comuni:

5.3 n8n non raggiungibile

Sintomo: https://n8n.srv1203683.hstgr.cloud non risponde.

# Connettersi alla VPS
ssh root@srv1203683.hstgr.cloud

# Verificare stato container
cd /docker/n8n
docker compose ps

# Se container down, riavviare
docker compose restart

# Se non si riavvia, controllare log
docker logs n8n-n8n-1 --tail 100

5.4 Database Supabase lento o non risponde

Sintomo: workflow impiegano molto più del solito, timeout frequenti.

1. Dashboard Supabase → sezione “Database” → “Database Health”
2. Verificare utilizzo disco (il DB è ~346 MB, piano Free ha 500 MB)
3. Verificare connessioni attive (PgBouncer gestisce il pooling)

5.5 Import fornitore non aggiorna i dati

Sintomo: i dati di un fornitore nella tabella prodotti hanno data_aggiornamento vecchia.

1. Il workflow di import è attivo in n8n?
2. L’ultima esecuzione è andata a buon fine? (verificare in “Executions”)
3. Il server FTP del fornitore è raggiungibile?
4. Il file CSV del fornitore è stato aggiornato?

5.6 Prezzi o categorie Amazon non si aggiornano (Keepa)

Sintomo: la tabella amazon_prezzi ha date vecchie, oppure il tool ordini segnala molti prodotti senza categoria Amazon.

1. Il workflow Keepa - Aggiorna Prezzi Amazon è attivo?
2. Verificare se la quota API è esaurita. Il piano ricarica 60 token al minuto (tetto: 3.600 accumulabili) e ogni prodotto richiesto ne costa circa 2: la capacità reale è di circa 30 prodotti al minuto. Il saldo si legge in tempo reale su https://api.keepa.com/token?key=...; sotto 500 arriva una mail automatica a report@monostech.com. Non ridurre l’intervallo del workflow sotto i 4 minuti: a 2 minuti il consumo supera la ricarica e i token si esauriscono in circa un’ora e mezza (verificato il 20/07/2026).
3. Controllare la tabella keepa_coda: se vuota, fn_popola_keepa_coda() non è stata eseguita (gira dentro l’Algoritmo Pricing delle 04:00 e 16:00)

Cosa viene messo in coda: tutto il catalogo utilizzabile — prodotti non fuori produzione, con un prezzo d’acquisto e un EAN valido — a prescindere dal fatto che vadano su Shopify, perché gli stessi dati servono sia al prezzo del negozio sia alle commissioni del tool ordini. Sono ~112.000 prodotti, lavorati per priorità: 1 riaggiornamento prezzi dei prodotti già in vendita, 2 prodotti disponibili del resto del catalogo, 3 tutti gli altri. Una coda con molte righe di priorità 2 o 3 non è un’anomalia: è il recupero in corso, che alla prima passata richiede circa 4 giorni.

I prodotti per cui Keepa non restituisce la categoria (codice sconosciuto o scheda senza categoria) sono elencati in NocoDB nella vista v_categoria_da_mappare, da correggere a mano.

5.7 Tassi di cambio BCE fermi o mancanti

Sintomo: nel tool ordini compare l’avviso “Tassi di cambio non disponibili” o “non aggiornati” sopra i risultati, e le righe in valuta estera restano in In verifica senza essere convertite.

1. Verificare che il workflow Tassi Cambio - Aggiorna da BCE (Tl0H891mq6CpGjUe, gira ogni notte all’01:00) sia attivo e che l’ultima esecuzione sia andata a buon fine. Se ha fallito arriva anche una mail d’errore
2. Controllare la tabella tassi_cambio: SELECT max(data_riferimento) FROM tassi_cambio;. Se il dato è più vecchio della soglia tassi_cambio_stantio_giorni (NocoDB, tool_amazon_soglie), il tool tratta i tassi come non disponibili anche se la tabella non è vuota
3. Rilanciare a mano il workflow BCE se necessario. Non esiste un tasso cablato di ripiego: se la sincronia resta ferma, il comportamento corretto è che le righe estere restino in verifica finché il dato non torna aggiornato, non che vengano convertite con un cambio vecchio

6. Procedure di Recovery

6.1 Backup Database Supabase

Il backup viene gestito automaticamente da Supabase. Per un backup manuale:

1. Dashboard Supabase → Settings → Database → Backups
2. Scaricare il backup più recente

Per dump manuale via CLI:

pg_dump "postgresql://postgres.ffcrmgkbhxjcvxidjmns:[PASSWORD]@aws-1-eu-west-1.pooler.supabase.com:6543/postgres" > backup_YYYYMMDD.sql

6.2 Ripristino dopo errore pricing

6.3 Backup workflow n8n

I workflow n8n sono sincronizzati automaticamente nella cartella workflows/ del repository Git. In caso di problema:

1. I file JSON sono nella cartella workflows/ del progetto
2. Per reimportare: n8n → Import from File → selezionare il JSON

6.4 Recovery VPS n8n

1. Accedere al pannello Hostinger per verificare lo stato del server
2. Se il server è attivo ma n8n non risponde: ssh root@srv1203683.hstgr.cloud → docker compose restart
3. Se il server è down: riavviarlo dal pannello Hostinger
4. Dopo il riavvio, i container Docker si avviano automaticamente

7. Contatti e Escalation

MonosTech — Runbook Operativo — Ultimo aggiornamento: 19/08/2026