Guida: Importazione Punti Vendita da Cassa in Cloud

Panoramica

Questa guida spiega come importare e gestire i punti vendita da Cassa in Cloud nell’applicazione FoodCost.

Perché importare i punti vendita?

I punti vendita (Outlets) servono per:

Filtrare i dati per specifici punti vendita nelle vendite, incassi e report
Organizzare le informazioni per location
Analizzare le performance per singolo punto vendita
Gestire magazzini e operazioni separate per ogni punto vendita

Come verificare quali punti vendita mancano

Metodo 1: Usare lo script di verifica


node scripts/check-missing-outlets.js

Questo script:

Si connette al database
Recupera tutti i punti vendita da Cassa in Cloud
Verifica quali sono già sincronizzati
Mostra un report dettagliato dei punti vendita mancanti

Metodo 2: Interfaccia web

Accedi all’applicazione
Vai su Impostazioni > Punti Vendita
Nella sezione “Sincronizzazione Punti Vendita” vedrai:
- Numero di punti vendita disponibili su Cassa in Cloud
- Stato della sincronizzazione

Come importare i punti vendita

Metodo automatico (Raccomandato)

Vai su Impostazioni > Punti Vendita
Trova la card “Sincronizzazione Punti Vendita”
Clicca su “Sincronizza Punti Vendita”
Attendi il completamento della sincronizzazione
Verrai notificato del numero di punti vendita creati e aggiornati

La sincronizzazione:

Crea nuovi outlet per i punti vendita non ancora presenti
Aggiorna gli outlet esistenti con i dati più recenti da Cassa in Cloud
Previene duplicati usando il campo cassaincloud_id
Preserva le personalizzazioni locali (logo, orari, note)

Metodo manuale

Se preferisci creare un punto vendita manualmente:

Vai su Impostazioni > Punti Vendita
Clicca su “Nuovo Punto Vendita”
Compila i campi richiesti:
- Nome: Nome del punto vendita
- Punto Vendita Cassa in Cloud: Seleziona il punto vendita corrispondente
- Indirizzo: Indirizzo completo
- Contatti: Email, telefono, ecc.
- Orari di apertura: Imposta gli orari per ogni giorno
Clicca su “Salva”

⚠️ Importante: Assicurati di collegare ogni outlet al corrispondente punto vendita su Cassa in Cloud per permettere il corretto filtraggio dei dati.

Caratteristiche dei punti vendita

Punto vendita primario

Il primo punto vendita creato viene automaticamente impostato come primario (⭐). Questo è il punto vendita predefinito per:

Filtri nei report
Nuove operazioni
Dashboard

Puoi cambiare il punto vendita primario modificando un outlet e selezionando “Punto vendita principale”.

Integrazione con Cassa in Cloud

Ogni outlet sincronizzato ha:

cassaincloud_id: ID univoco del punto vendita su Cassa in Cloud
Sincronizzazione automatica: I dati vengono aggiornati durante la sincronizzazione
Filtri nelle API: Quando richiedi dati da Cassa in Cloud, puoi filtrare per punto vendita

Dati aggiuntivi

Oltre ai dati sincronizzati da Cassa in Cloud, puoi aggiungere:

Logo e immagine di copertina
Icona personalizzata (da libreria Lucide o immagine custom)
Orari di apertura dettagliati
Social media (Facebook, Instagram, Twitter, LinkedIn)
Impostazioni (consegna a domicilio, ritiro)
Note

Utilizzo nei report e filtri

Report Finanziari

Nella pagina Report > Report Finanziari puoi:

Selezionare un punto vendita specifico dal menu a tendina
Visualizzare i dati filtrati solo per quel punto vendita
Confrontare le performance tra diversi punti vendita

Vendite e Incassi

Quando visualizzi le vendite da Cassa in Cloud:

Filtra per punto vendita usando il parametro idsSalesPoint
Ottieni solo i dati relativi agli outlet selezionati
Analizza le vendite per prodotto e categoria per ogni punto vendita

Best Practices

1. Sincronizzazione regolare

Esegui la sincronizzazione:

Settimanalmente per mantenere i dati aggiornati
Dopo modifiche su Cassa in Cloud (nuovi punti vendita, cambi indirizzo, ecc.)
Prima di analisi importanti per avere dati accurati

2. Gestione outlet

Mantieni attivi solo i punti vendita in uso
Imposta il punto vendita primario come quello con più operazioni
Completa le informazioni di contatto per ogni outlet
Configura gli orari di apertura per una gestione ottimale

3. Dati completi

Aggiungi logo e icona per identificare visivamente ogni punto vendita
Completa l’indirizzo con coordinate GPS per la mappa
Configura consegna e ritiro in base alle capacità del punto vendita
Mantieni aggiornate le informazioni fiscali (P.IVA, Codice Fiscale)

Risoluzione problemi

Errore: “API Key di Cassa in Cloud non configurata”

Soluzione:

Vai su Impostazioni > Generali
Inserisci l’API Key di Cassa in Cloud
Salva le impostazioni
Riprova la sincronizzazione

Errore: “Nessun punto vendita disponibile”

Possibili cause:

Non ci sono punti vendita attivi su Cassa in Cloud
Il parametro hasActiveLicense sta filtrando tutti i punti vendita
Problemi di connessione con Cassa in Cloud

Soluzione: Verifica su Cassa in Cloud che ci siano punti vendita con licenza attiva.

Duplicati dopo sincronizzazione

Causa: Alcuni outlet potrebbero non avere il campo cassaincloud_id impostato.

Soluzione:

Identifica gli outlet duplicati
Verifica quale ha il cassaincloud_id
Elimina quello senza cassaincloud_id
Oppure usa lo script di verifica per trovare outlet senza collegamento

Punti vendita non visibili nei filtri

Causa: Il punto vendita potrebbe essere inattivo o non collegato correttamente.

Soluzione:

Verifica che l’outlet sia attivo (isActive = true)
Verifica che abbia un cassaincloud_id valido
Ricarica la pagina

Script di manutenzione

check-missing-outlets.js

Verifica quali punti vendita da Cassa in Cloud non sono ancora sincronizzati:


node scripts/check-missing-outlets.js

Output:

Lista completa punti vendita su Cassa in Cloud
Lista completa outlet nel database
Report dettagliato dei punti vendita mancanti
Outlet senza collegamento a Cassa in Cloud

API Reference

GET /api/outlets

Restituisce tutti i punti vendita del tenant corrente.

POST /api/outlets/sync

Sincronizza i punti vendita da Cassa in Cloud.

Body:


{
  "salesPoints": [
    {
      "id": "123",
      "description": "Punto Vendita Centro",
      "address": "Via Roma 1",
      "city": "Milano",
      "country": "Italia"
    }
  ]
}

GET /api/cassa-in-cloud/salespoints

Recupera i punti vendita direttamente da Cassa in Cloud.

Query params:

hasActiveLicense: boolean (default: true) - Filtra solo punti vendita con licenza attiva

Esempio di flusso completo

Verifica punti vendita mancanti
```
node scripts/check-missing-outlets.js
```
Sincronizza via web
- Vai su Impostazioni > Punti Vendita
- Clicca “Sincronizza Punti Vendita”
Personalizza gli outlet
- Per ogni punto vendita, aggiungi logo e informazioni
- Configura orari di apertura
- Imposta il punto vendita primario
Usa nei report
- Vai su Report > Report Finanziari
- Seleziona un punto vendita
- Analizza i dati filtrati

Documentazione correlata

OUTLETS_INTEGRATION.md - Documentazione tecnica completa
API di Cassa in Cloud: https://api-doc.cassanova.com/

Supporto

Per problemi o domande:

Verifica questa guida
Controlla i log dell’applicazione
Esegui lo script di verifica
Contatta il supporto tecnico