Integration Gateway
FenixTrace Integration Kit
A standalone kit that lets companies register products through the FenixTrace API in a fully automated way. Generate an API key from the dashboard, set it in the kit and send your products: FenixTrace handles everything server-side — IPFS upload, on-chain registration and notarization. No wallet, no private keys, no gas fees to manage.
What's new: no wallet anymore
Previously the kit had to hold a wallet key and sign on-chain transactions (plus manage IPFS and gas fees). Not anymore: you only need an API key generated from the dashboard. The kit sends the product to FenixTrace over HTTP and the server does everything — IPFS upload, on-chain signing and notarization. No wallet, no private keys, no gas fees to manage.
Who Is It For
Companies with CRM/ERP
Integrate traceability directly into your management system. The kit sends products to the FenixTrace API using your API key and registration happens automatically.
E-Commerce & Marketplace
Automatically register every sold product. Generate traceable labels with QR codes for your end customers, with no blockchain layer to manage.
Manufacturers & Supply Chain
Track every batch from production to GDO delivery. Send quality data, certifications and logistics: FenixTrace stores them on IPFS as immutable metadata.
Developers & Integrators
Use the FenixTrace REST APIs to build custom integrations. All it takes is an API key and an HTTP POST call from any language.
How It Works
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 pageThe kit sends each product to POST /api/v1/products, authenticating with your API key. FenixTrace does everything server-side: it uploads the metadata to IPFS (returning an immutable CID), signs the on-chain transaction, runs the notarization that proves integrity, and publishes a page on the FenixTrace Scanner. The API response contains the CID and transaction hash. You never manage wallets, private keys or gas fees.
Prerequisites
| Requirement | Details |
|---|---|
| Node.js | v16+ (v18 LTS recommended) |
| FenixTrace Subscription | Active plan on fenixtrace.com |
| API Key | Generated from the dashboard → API Keys section (format ftrace_<id>_<secret>) |
| Base URL | https://fenixtrace.com (prod) or http://localhost:3000 (dev) |
Step-by-Step Setup
1. Clone & Install
git clone https://github.com/SantoBaldassarre/FenixTrace-IOTA-auto-add-product-Integration-Kit
cd FenixTrace-IOTA-auto-add-product-Integration-Kit
npm install2. Generate an API Key
Log in to the FenixTrace dashboard with your email and OTP code, open the "API Keys" section and generate a new key. The full secret is shown only once: copy it immediately and store it securely.
# Generated from Dashboard → API Keys
# Format:
ftrace_<id>_<secret>
# Example:
ftrace_8f3a2c1b_a1B2c3D4e5F6g7H8i9J0kLmNoPqRsTuV3. Keep the Key Secure
The API key grants product-registration access for your company. Treat it like a password: keep it only in your server environment variables, never commit it to the repository. If it is compromised, revoke it from the dashboard and generate a new one.
From the FenixTrace dashboard, in the API Keys section, you can:
1. Generate a new key for each integration
2. Assign a recognizable name (e.g. "Odoo Production")
3. See creation date and last usage
4. Instantly revoke a compromised key
4. Configure .env file
Just two variables are needed. No private keys, on-chain objects, IPFS account or gas tokens: FenixTrace handles everything server-side.
cp .env.example .env| Variable | Where to Find It |
|---|---|
FENIXTRACE_API_KEY | FenixTrace Dashboard → API Keys (format ftrace_<id>_<secret>) |
FENIXTRACE_API_BASE_URL | https://fenixtrace.com (prod) or http://localhost:3000 (dev) |
FENIXTRACE_API_KEY=ftrace_8f3a2c1b_a1B2c3D4e5F6g7H8i9J0kLmNoPqRsTuV
FENIXTRACE_API_BASE_URL=https://fenixtrace.com5. Start the Server
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 keyUsage
Method 1: JSON Files
Drop a .json file in the uploads/ folder. The kit detects and processes it automatically within 1 minute.
cp my-product.json uploads/
# Auto-processed in ~1 min
# Or trigger manually:
curl -X POST http://localhost:3005/process-allMethod 2: REST API
Use REST endpoints for programmatic integrations. The kit exposes APIs to process, monitor, and verify.
# 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"Method 3: CRM/ERP
Your CRM or ERP writes JSON files to the uploads/ folder (via shared volume, SFTP, or API) and the kit processes them automatically.
# Mount shared volume
docker run -v /crm/exports:/app/uploads ...
# Or use SFTP to push files
sftp user@server:/app/uploads/
# Files are auto-processedProduct JSON Format
Each JSON file represents a product to register on-chain. Only the "name" field is required. All other fields are optional and stored as immutable metadata on IPFS.
{
"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"
}
}Direct API Call
If you prefer, you can send products directly to FenixTrace without going through the kit. Authenticate the request with your API key in the Authorization header. FenixTrace performs the IPFS upload, on-chain registration and notarization, and returns the CID and transaction hash.
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 | Description |
|---|---|---|
GET | / | Server info and available endpoints |
GET | /status | Kit status, FenixTrace base URL and API connectivity |
GET | /health | Full health check (API connectivity, filesystem, memory) |
GET | /ping | Liveness check — returns "pong" |
POST | /process-all | Process all JSON files in uploads/ |
POST | /process/:filename | Process a single file by name |
GET | /processed | List processed products with metadata |
GET | /logs | View available log files |
POST | /logs/cleanup | Clean up old log files |
Docker
Production
# 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 -fDevelopment
# 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 shCRM & eCommerce Plugins
Ready-to-use plugins to integrate FenixTrace directly into your CRM or eCommerce platform. Each plugin sends products to the FenixTrace REST API using your API key: registration and notarization happen automatically server-side.
FenixTrace for Odoo
Odoo 16/17 module with single sync, batch, auto cron and retry
FenixTrace for WooCommerce
WordPress/WooCommerce plugin with meta box, bulk action and auto-sync on publish
FenixTrace for PrestaShop
PrestaShop 1.7/8.x module with database sync, product tab and auto-sync on save
FenixTrace for Salesforce
Salesforce package with Apex classes, LWC component, scheduled batch sync and custom fields on Product2
FenixTrace for WordPress
Pure WordPress plugin with Custom Post Type, meta box, REST API and auto-sync — no WooCommerce required
Frequently Asked Questions
No. You need neither an IPFS account nor a wallet. All you need is an API key generated from the FenixTrace dashboard. IPFS upload, on-chain signing and notarization all happen automatically on the FenixTrace server side.
On-chain gas fees are included in your subscription and handled entirely by FenixTrace. You send the product via API, we take care of the rest: no tokens, no faucet, no gas fees to pay on the integrator side.
No. The kit requires an active FenixTrace subscription and a valid API key. The key identifies your company and enables product registration through the official APIs.
With the Authorization: Bearer ftrace_<id>_<secret> header. Generate the key from the dashboard in the API Keys section and set it as FENIXTRACE_API_KEY in the kit's .env file. You can revoke and regenerate it at any time.
The API response contains the IPFS CID and transaction hash. After processing, the kit moves the file to processed/ with the same metadata. You can verify the product in the FenixTrace Scanner.
Next Steps
Generate your API key from the dashboard, set it in the kit, and start registering products. Check the API documentation for advanced integrations via FenixTrace's public APIs.