ZincirX ZincirX

Documentazione

Guida rapida

Benvenuti in ZincirX! Questa guida la aiuterà a iniziare a usare la nostra piattaforma di tracciabilità della filiera.

Passaggio 1: crei il suo account

  1. Visiti ZincirX e faccia clic su "Registrati"
  2. Inserisca il suo nome e il suo indirizzo email
  3. Scelga una password di almeno otto caratteri, oppure si registri con il suo account Google o Facebook
  4. Accetti i Termini di servizio, la Politica di vendita, consegna e rimborso e le Condizioni sul trattamento dei dati, e legga l’Informativa sulla privacy
  5. Acceda con l’account appena creato

Passaggio 2: completi l’onboarding

  1. Indichi il suo indirizzo email per le notifiche
  2. Verifichi il suo indirizzo email tramite il link di conferma
  3. Inserisca le informazioni e la categoria della sua azienda
  4. Completi la configurazione del suo profilo aziendale

Passaggio 3: crei il suo primo modello

  1. Vada alla sezione Modelli
  2. Faccia clic su "Crea nuovo modello"
  3. Definisca le fasi del suo processo di filiera
  4. Imposti i requisiti di convalida per ogni fase
  5. Salvi e attivi il suo modello

Passaggio 4: inizi a tracciare i lotti

  1. Vada alla sezione Lotti
  2. Crei un nuovo lotto utilizzando il suo modello
  3. Esegua ogni fase man mano che i prodotti avanzano lungo la sua filiera
  4. Carichi la documentazione e i contenuti multimediali di supporto
  5. Condivida i link di verifica con le parti interessate

Concetti fondamentali

Modelli

I modelli definiscono il processo standard della sua filiera. Contengono una serie di fasi che i prodotti devono attraversare, insieme ai requisiti di convalida per ciascuna fase.

  • Definizioni di flussi di lavoro riutilizzabili
  • Requisiti delle fasi personalizzabili
  • Controlli di accesso basati sui ruoli
  • Regole di convalida e dipendenze

Lotti

I lotti rappresentano specifici cicli di produzione o gruppi di prodotti che seguono un modello. Ogni lotto ha un UUID univoco per il tracciamento e la verifica.

  • Identificazione univoca tramite UUID
  • Esecuzione fase per fase, con data e ora di ciascuna fase
  • Allegati multimediali e documentali
  • Funzionalità di verifica pubblica

Fasi del lotto

Le singole fasi nell’esecuzione di un lotto, ciascuna con il proprio stato, le proprie marcature temporali e la propria documentazione di supporto.

  • Monitoraggio dello stato (pending, in_progress, completed, failed)
  • Registrazione della marcatura temporale per ogni cambio di stato
  • Dati sulla posizione e coordinate GPS
  • File allegati e note

Profili aziendali

Informazioni sull’azienda collegate agli account utente, che consentono la collaborazione tra più parti e l’accesso basato sui ruoli.

  • Identificazione e verifica dell’azienda
  • Classificazione per categoria aziendale
  • Informazioni di contatto e preferenze
  • Gestione delle autorizzazioni di accesso

Ruoli e autorizzazioni degli utenti

Ruolo Autorizzazioni Caso d’uso tipico
Fabbricante Creare modelli, avviare lotti, eseguire tutte le fasi Produttori originali che creano e gestiscono prodotti
Distributore Eseguire fasi specifiche, aggiornare le posizioni, aggiungere documentazione Aziende di logistica e distribuzione che movimentano i prodotti
Rivenditore Visualizzare le informazioni sui lotti, eseguire le fasi finali, verifica rivolta al cliente Negozi e punti vendita che vendono ai consumatori finali
Ispettore Visualizzare tutti i dati, aggiungere certificazioni, documentazione del controllo qualità Organismi di regolamentazione e team di garanzia della qualità
Consumatore Verifica pubblica tramite UUID/codici QR Clienti finali che consultano il percorso registrato di un prodotto

Integrazione API

Autenticazione

ZincirX utilizza l’autenticazione tramite token API (Laravel Sanctum). Per integrarsi con la nostra API:

  1. Richieda un token inviando con una richiesta POST il suo indirizzo email e la sua password a /api/auth/login
  2. Invii tale token come bearer token nell’intestazione Authorization di ogni richiesta
  3. Gli endpoint di verifica pubblica sotto /api/public non richiedono alcun token

Endpoint principali

Operazioni sui lotti

  • GET /api/batches
  • POST /api/batches
  • GET /api/batches/{id}
  • POST /api/batches/{id}/steps/{stepId}/complete

Gestione dei modelli

  • GET /api/templates
  • POST /api/templates
  • PUT /api/templates/{id}

Verifica pubblica

  • GET /verify/{uuid}
  • GET /qr/{uuid}/image

Registrazioni e verifica

Dove sono conservati i suoi dati

  • Archiviazione: Il database di ZincirX, su server gestiti da noi
  • Revisioni del passaporto: Di sola aggiunta — una modifica viene registrata come nuova revisione e quelle precedenti vengono conservate
  • File probatori: Ogni caricamento riporta un’impronta SHA-256, in modo da poter dimostrare che un file non è stato modificato
  • Disponibilità: Un passaporto resta raggiungibile per il periodo venduto con esso, dieci anni per impostazione predefinita, a decorrere dal giorno dell’emissione

Funzionalità di verifica

Le registrazioni della filiera sono conservate nel database di ZincirX, sui suoi server. La piattaforma è costruita per rendere tali registrazioni verificabili da terzi:

  • Registrazione dei modelli, incluso un GTIN facoltativo per il prodotto
  • Registrazioni della creazione dei lotti e del completamento delle fasi, con marcature temporali
  • Un’impronta SHA-256 per ogni file caricato, in modo da poter dimostrare che un file non è stato modificato
  • Revisioni di sola aggiunta del passaporto digitale del prodotto: una modifica viene registrata come nuova revisione e quelle precedenti vengono conservate

Buone pratiche

Sicurezza

  • Usi una password robusta e univoca per il suo account ZincirX e non condivida mai le sue credenziali di accesso
  • Controlli regolarmente i membri della sua azienda e rimuova gli accessi non più necessari
  • Controlli i dettagli di una fase e i file allegati prima di contrassegnarla come completata
  • Usi password robuste per l’account email della sua azienda

Gestione dei dati

  • Fornisca informazioni accurate e complete per ogni fase
  • Carichi file multimediali chiari e pertinenti ai fini della verifica
  • Usi convenzioni di denominazione coerenti per lotti e modelli
  • Riveda e aggiorni regolarmente il suo profilo aziendale

Collaborazione

  • Condivida l’accesso ai lotti con i partner pertinenti della filiera
  • Comunichi chiaramente i requisiti delle fasi a tutti i partecipanti
  • Usi i codici QR per una verifica semplice da parte dei clienti finali
  • Mantenga una comunicazione regolare con la sua rete di filiera

Risoluzione dei problemi

Problemi di accesso

  • Controlli di aver inserito correttamente il suo indirizzo email e la password
  • Se la registrazione è avvenuta con Google o Facebook, acceda con lo stesso provider
  • Cancelli la cache e i cookie del browser
  • Se non ricorda la password, usi il link per reimpostarla nella pagina di accesso

Errori nei lotti e nei caricamenti

  • Prima di creare un lotto, controlli di avere passaporti prepagati (UUID) disponibili
  • Si assicuri che la connessione di rete sia stabile
  • Attenda che un caricamento precedente sia terminato prima di avviarne un altro
  • Controlli che ogni file caricato rientri nel limite di dimensione indicato nel modulo di caricamento

Problemi di prestazioni

  • Usi browser moderni (Chrome, Firefox, Safari)
  • Chiuda le schede del browser e le applicazioni non necessarie
  • Controlli la velocità della sua connessione internet
  • Se necessario, cancelli i dati del browser e lo riavvii

Assistenza e risorse

Supporto della community

Entri in contatto con altri utenti di ZincirX e ottenga dalla community supporto per le sue domande e difficoltà.

  • Forum e discussioni degli utenti
  • Condivisione delle buone pratiche
  • Richieste di funzionalità e feedback

Assistenza tecnica

Riceva assistenza diretta dal nostro team tecnico per l’integrazione e per problemi specifici della piattaforma.

  • Supporto per l’integrazione API
  • Indicazioni sul passaporto digitale del prodotto e su GS1 Digital Link
  • Consulenza su soluzioni personalizzate
Inizia ora