Devo gestire chiavi IPFS o un wallet?

No. Ti serve solo una chiave API generata dalla dashboard FenixTrace. Upload IPFS, firma on-chain e notarizzazione avvengono automaticamente lato server FenixTrace.

Quanto costa registrare un prodotto?

Le gas fee on-chain sono incluse e gestite da FenixTrace. Tu invii il prodotto via API, al resto pensiamo noi.

Il kit funziona senza FenixTrace?

No. Il kit richiede una subscription attiva e una chiave API valida generata dalla tua dashboard FenixTrace.

Come autentico le richieste?

Con header Authorization: Bearer ftrace_ _ . La chiave si genera dalla dashboard nella sezione Chiavi API.

Come verifico che un prodotto è stato registrato?

La risposta API include CID IPFS e transaction hash. Puoi verificarlo nello Scanner FenixTrace.

Gateway di integrazione

Torna alla Documentazione

Integration Gateway

FenixTrace Integration Kit

Un kit standalone che permette alle aziende di registrare prodotti tramite le API di FenixTrace in modo completamente automatizzato. Genera una chiave API dalla dashboard, configurala nel kit e invia i prodotti: FenixTrace gestisce tutto lato server — upload IPFS, registrazione on-chain e notarizzazione. Nessun wallet, nessuna chiave privata, nessuna gas fee da gestire.

Node.js

API Key

REST API

Docker Ready

PM2 Ready

Auto-Processing

Server-Side Signing

IPFS Included

Novità: niente più wallet

Prima il kit doveva custodire una chiave di wallet e firmare le transazioni on-chain (oltre a gestire IPFS e le gas fee). Ora no: ti serve solo una chiave API generata dalla dashboard. Il kit invia il prodotto a FenixTrace via HTTP e il server fa tutto — upload su IPFS, firma on-chain e notarizzazione. Nessun wallet, nessuna chiave privata, nessuna gas fee da gestire.

A Chi è Destinato

Aziende con CRM/ERP

Integra la tracciabilità direttamente nel tuo sistema gestionale. Il kit invia i prodotti alle API di FenixTrace usando la tua chiave API e la registrazione avviene automaticamente.

E-Commerce & Marketplace

Registra automaticamente ogni prodotto venduto. Genera etichette tracciabili con QR code per i tuoi clienti finali, senza gestire nulla a livello blockchain.

Produttori & Supply Chain

Traccia ogni lotto dalla produzione alla consegna al GDO. Invia dati di qualità, certificazioni e logistica: FenixTrace li archivia su IPFS come metadati immutabili.

Sviluppatori & Integratori

Usa le REST API di FenixTrace per costruire integrazioni personalizzate. Basta una chiave API e una chiamata HTTP POST da qualsiasi linguaggio.

Come Funziona

flow

Your System          Integration Kit                  FenixTrace (server-side)
──────────           ───────────────                  ───────────────
 JSON file   ──►  POST /api/v1/products          ──►  1. IPFS upload   → CID
                  Authorization: Bearer ftrace_...     2. On-chain add  → Tx Hash
                                                       3. Notarization  → Notar. Tx
                  ◄── JSON response (CID + txHash) ◄──  4. Public Scanner page

Il kit invia ogni prodotto a POST /api/v1/products autenticandosi con la tua chiave API. FenixTrace fa tutto lato server: carica i metadati su IPFS (ottenendo un CID immutabile), firma la transazione on-chain, esegue la notarizzazione che prova l'integrità e pubblica una pagina nello Scanner FenixTrace. La risposta API contiene CID e transaction hash. Tu non gestisci wallet, chiavi private né gas fee.

Prerequisiti

Requisito	Dettagli
Node.js	v16+ (v18 LTS consigliato)
Subscription FenixTrace	Piano attivo su fenixtrace.com
Chiave API	Generata dalla dashboard → sezione Chiavi API (formato ftrace_<id>_<secret>)
Base URL	https://fenixtrace.com (prod) o http://localhost:3000 (dev)

Setup Passo per Passo

1. Clona e Installa

bash

git clone https://github.com/SantoBaldassarre/FenixTrace-IOTA-auto-add-product-Integration-Kit
cd FenixTrace-IOTA-auto-add-product-Integration-Kit
npm install

2. Genera una Chiave API

Accedi alla dashboard FenixTrace con email e codice OTP, apri la sezione "Chiavi API" e genera una nuova chiave. Il segreto completo è mostrato una sola volta: copialo subito e conservalo in modo sicuro.

api key

# Generated from Dashboard → API Keys
# Format:
ftrace_<id>_<secret>

# Example:
ftrace_8f3a2c1b_a1B2c3D4e5F6g7H8i9J0kLmNoPqRsTuV

3. Conserva la Chiave in Modo Sicuro

La chiave API dà accesso alla registrazione dei prodotti per la tua azienda. Tienila riservata come una password: mettila solo nelle variabili d'ambiente del server, non committarla mai nel repository. Se viene compromessa, revocala dalla dashboard e generane una nuova.

Dalla dashboard FenixTrace, nella sezione Chiavi API, puoi:

1. Generare una nuova chiave per ogni integrazione

2. Assegnare un nome riconoscibile (es. "Odoo Produzione")

3. Vedere data di creazione e ultimo utilizzo

4. Revocare immediatamente una chiave compromessa

4. Configura il file .env

Bastano due variabili. Non servono chiavi private, oggetti on-chain, account IPFS né token per le gas fee: FenixTrace gestisce tutto lato server.

bash

cp .env.example .env

Variabile	Dove Trovarla
FENIXTRACE_API_KEY	Dashboard FenixTrace → Chiavi API (formato ftrace_<id>_<secret>)
FENIXTRACE_API_BASE_URL	https://fenixtrace.com (prod) o http://localhost:3000 (dev)

.env

FENIXTRACE_API_KEY=ftrace_8f3a2c1b_a1B2c3D4e5F6g7H8i9J0kLmNoPqRsTuV
FENIXTRACE_API_BASE_URL=https://fenixtrace.com

5. Avvia il Server

bash

npm start
# Server starts on port 3005
# Auto-processing monitors uploads/ folder every minute
# Each product is sent to POST /api/v1/products with your API key

Utilizzo

Metodo 1: File JSON

Inserisci un file .json nella cartella uploads/. Il kit lo rileva e lo processa automaticamente entro 1 minuto.

cp my-product.json uploads/
# Auto-processed in ~1 min
# Or trigger manually:
curl -X POST http://localhost:3005/process-all

Metodo 2: REST API

Usa gli endpoint REST per integrazioni programmatiche. Il kit espone API per processare, monitorare e verificare.

# Process all files
curl -X POST localhost:3005/process-all

# Process single file
curl -X POST localhost:3005/process/my.json

# Check kit status & connectivity
curl "localhost:3005/status"

Metodo 3: CRM/ERP

Il tuo CRM o ERP scrive file JSON nella cartella uploads/ (via volume condiviso, SFTP, o API) e il kit li processa automaticamente.

# Mount shared volume
docker run -v /crm/exports:/app/uploads ...

# Or use SFTP to push files
sftp user@server:/app/uploads/

# Files are auto-processed

Formato JSON del Prodotto

Ogni file JSON rappresenta un prodotto da registrare on-chain. Solo il campo "name" è obbligatorio. Tutti gli altri campi sono opzionali e vengono archiviati come metadati immutabili su IPFS.

json

{
  "name": "Annurca Apple",              // REQUIRED
  "company": "Your Company Name",       // Optional
  "template": "agro",                   // Optional: agro|pharma|fashion|logistics|...
  "batchId": "BATCH-2026-001",          // Optional
  "product": {
    "variety": "Annurca IGP",
    "category": "Fresh Fruit",
    "organicCertified": true,
    "certifications": ["GlobalGAP", "IGP Campania"],
    "weightKg": 12.5
  },
  "origin": {
    "region": "Campania",
    "province": "Avellino",
    "farmName": "Azienda Agricola Rossi"
  },
  "qualityControl": {
    "brixLevel": "14.2",
    "residueTestPassed": true,
    "testLabName": "Lab Analysis SRL"
  }
}

Templates:

generic

agro

pharma

fashion

logistics

electronics

art

automotive

cosmetics

chemicals

machinery

custom

Chiamata diretta alle API

Se preferisci, puoi inviare i prodotti direttamente a FenixTrace senza passare dal kit. Autentica la richiesta con la tua chiave API nell'header Authorization. FenixTrace esegue upload IPFS, registrazione on-chain e notarizzazione, e restituisce CID e transaction hash.

bash

curl -X POST https://fenixtrace.com/api/v1/products \
  -H "Authorization: Bearer ftrace_8f3a2c1b_a1B2c3D4e5F6g7H8i9J0kLmNoPqRsTuV" \
  -H "Content-Type: application/json" \
  -d @my-product.json

# Response:
# {
#   "ok": true,
#   "ipfsCid": "bafy...",
#   "txHash": "0x...",
#   "scannerUrl": "https://fenixtrace.com/scanner/0x..."
# }

API Reference

Method	Endpoint	Descrizione
GET	/	Info server e endpoint disponibili
GET	/status	Stato kit, base URL FenixTrace e connettività API
GET	/health	Health check completo (connettività API, filesystem, memoria)
GET	/ping	Liveness check — ritorna "pong"
POST	/process-all	Processa tutti i file JSON in uploads/
POST	/process/:filename	Processa un singolo file per nome
GET	/processed	Lista prodotti processati con metadati
GET	/logs	Visualizza file di log disponibili
POST	/logs/cleanup	Pulisci file di log vecchi

Docker

Production

bash

# Configure
cp .env.example .env
# Edit .env with your values

# Build and start
docker compose up -d

# Check health
curl http://localhost:3005/health

# View logs
docker compose logs -f

Development

bash

# Hot-reload mode
docker compose -f docker-compose.dev.yml up

# Useful commands
docker compose down          # Stop
docker compose up -d --build # Rebuild
docker exec -it fenixtrace-integration-kit sh

Plugin CRM & eCommerce

Plugin pronti all'uso per integrare FenixTrace direttamente nel tuo CRM o piattaforma eCommerce. Ogni plugin invia i prodotti alle REST API di FenixTrace con la tua chiave API: la registrazione e la notarizzazione avvengono automaticamente lato server.

FenixTrace for Odoo

Modulo Odoo 16/17 con sync singolo, batch, cron automatico e retry

Python

Odoo 16/17

Scarica da GitHub

FenixTrace for WooCommerce

Plugin WordPress/WooCommerce con meta box, bulk action e auto-sync su publish

PHP

WordPress

Scarica da GitHub

FenixTrace for PrestaShop

Modulo PrestaShop 1.7/8.x con database sync, tab prodotto e auto-sync su save

PHP

PrestaShop

Scarica da GitHub

FenixTrace for Salesforce

Package Salesforce con Apex classes, LWC component, scheduled batch sync e custom fields su Product2

Apex

Salesforce

Scarica da GitHub

FenixTrace for WordPress

Plugin WordPress puro con Custom Post Type, meta box, REST API e auto-sync — senza WooCommerce

PHP

WordPress

Scarica da GitHub

Domande Frequenti

No. Non ti serve né un account IPFS né un wallet. Ti basta una chiave API generata dalla dashboard FenixTrace. Upload su IPFS, firma on-chain e notarizzazione avvengono automaticamente lato server FenixTrace.

Le gas fee on-chain sono incluse nella tua subscription e gestite interamente da FenixTrace. Tu invii il prodotto via API, al resto pensiamo noi: nessun token, nessun faucet, nessuna gas fee da pagare lato integratore.

No. Il kit richiede una subscription attiva su FenixTrace e una chiave API valida. La chiave identifica la tua azienda e abilita la registrazione dei prodotti tramite le API ufficiali.

Con l'header Authorization: Bearer ftrace_<id>_<secret>. Genera la chiave dalla dashboard nella sezione Chiavi API e impostala come FENIXTRACE_API_KEY nel file .env del kit. Puoi revocarla e rigenerarla in qualsiasi momento.

La risposta delle API contiene CID IPFS e transaction hash. Dopo il processing, il kit sposta il file in processed/ con gli stessi metadati. Puoi verificare il prodotto nello Scanner FenixTrace.

Prossimi Passi

Genera la tua chiave API dalla dashboard, configurala nel kit e inizia a registrare prodotti. Consulta la documentazione API per integrazioni avanzate tramite le API pubbliche di FenixTrace.

Genera Chiave API API Reference Scanner Torna alla Documentazione

Integration Gateway

FenixTrace Integration Kit

Novità: niente più wallet

A Chi è Destinato

Aziende con CRM/ERP

E-Commerce & Marketplace

Produttori & Supply Chain

Sviluppatori & Integratori

Come Funziona

Prerequisiti

Setup Passo per Passo

1. Clona e Installa

2. Genera una Chiave API

3. Conserva la Chiave in Modo Sicuro

4. Configura il file .env

5. Avvia il Server

Utilizzo

Metodo 1: File JSON

Metodo 2: REST API

Metodo 3: CRM/ERP

Formato JSON del Prodotto

Chiamata diretta alle API

API Reference

Docker

Production

Development

Plugin CRM & eCommerce

FenixTrace for Odoo

FenixTrace for WooCommerce

FenixTrace for PrestaShop

FenixTrace for Salesforce

FenixTrace for WordPress

Domande Frequenti

Devo gestire chiavi IPFS o un wallet?

Devo gestire chiavi IPFS o un wallet?

Quanto costa registrare un prodotto?

Quanto costa registrare un prodotto?

Il kit funziona senza FenixTrace?

Il kit funziona senza FenixTrace?

Come autentico le richieste alle API?

Come autentico le richieste alle API?

Come verifico che un prodotto è stato registrato?

Come verifico che un prodotto è stato registrato?

Prossimi Passi