Introduzione

ArticoFlow è un software per la gestione completa e automatizzata degli articoli. Permette di organizzare il catalogo prodotti, automatizzare i processi ripetitivi e sincronizzare i dati su tutti i canali di vendita. Questa documentazione ti guida nell'utilizzo di tutte le funzionalità disponibili.

Requisiti di Sistema

ArticoFlow è un'applicazione web accessibile da qualsiasi browser moderno. Non è richiesta alcuna installazione locale.

• Browser supportati: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
• Connessione internet stabile
• Risoluzione minima consigliata: 1280x720

Installazione

Per iniziare ad usare ArticoFlow, basta registrarsi sulla piattaforma. Per l'integrazione via API, installa il nostro SDK:

npm install @articoflow/sdk

Poi inizializza il client con la tua chiave API:

import { ArticoFlow } from '@articoflow/sdk'

const client = new ArticoFlow({
  apiKey: process.env.ARTICOFLOW_API_KEY,
  region: 'eu-west-1'
})

Primo Accesso

Dopo la registrazione, verrai guidato attraverso una procedura di onboarding che include la configurazione del tuo primo catalogo, l'import dei dati esistenti e la connessione dei canali di vendita.

Creare un Articolo

Per creare un nuovo articolo, accedi alla sezione Catalogo e clicca su "Nuovo Articolo". Ogni articolo supporta:

• Titolo, descrizione e descrizione breve
• SKU, codice a barre (EAN/UPC), codice interno
• Prezzi multipli (listino, scontato, costo)
• Immagini illimitate con ordinamento drag-and-drop
• Attributi personalizzati illimitati

Oppure via API:

const article = await client.articles.create({
  title: 'Maglietta Premium',
  sku: 'MAG-001',
  price: 29.90,
  cost: 12.00,
  category: 'abbigliamento',
  attributes: {
    colore: 'nero',
    taglia: 'M',
    materiale: '100% cotone'
  }
})

Categorie e Attributi

Le categorie supportano nidificazione illimitata (es. Abbigliamento > Uomo > Magliette). Gli attributi personalizzati possono essere di tipo testo, numero, selezione, data o booleano. Una volta definiti, gli attributi vengono ereditati dalle sottocategorie.

Varianti di Prodotto

Ogni articolo può avere varianti basate su attributi (es. taglia, colore). Le varianti ereditano i dati dell'articolo principale ma possono avere prezzi, SKU, scorte e immagini indipendenti.

const variant = await client.articles.createVariant('art_123', {
  attributes: { taglia: 'L', colore: 'blu' },
  sku: 'MAG-001-L-BLU',
  price: 31.90,
  stock: 150
})

Import ed Export

ArticoFlow supporta import ed export in formato CSV, Excel (.xlsx) e JSON. L'import include mappatura automatica dei campi, validazione dei dati e gestione duplicati. I file possono essere caricati fino a 500MB.

Regole Automatiche

Le automazioni permettono di eseguire azioni in modo automatico al verificarsi di determinate condizioni. Ogni regola è composta da un trigger (evento), condizioni (filtri) e azioni da eseguire.

// Esempio: ridurre il prezzo del 10% se le scorte superano 500 unità
const rule = await client.automations.create({
  name: 'Sconto scorte elevate',
  trigger: 'stock_updated',
  conditions: [
    { field: 'stock', operator: 'greater_than', value: 500 }
  ],
  actions: [
    { type: 'update_price', modifier: 'percentage', value: -10 }
  ]
})

Aggiornamento Prezzi

Configura regole per aggiornare automaticamente i prezzi in base a variazioni di costo, margini target, prezzi della concorrenza o stagionalità. Le regole possono essere applicate a singoli articoli, categorie o all'intero catalogo.

Riordino Scorte

Imposta soglie di riordino per ogni articolo o categoria. Quando le scorte scendono sotto la soglia, ArticoFlow può inviare notifiche, generare ordini di acquisto o attivare webhook verso il tuo sistema ERP.

Trigger Personalizzati

Oltre ai trigger predefiniti (creazione articolo, aggiornamento scorte, variazione prezzo), puoi creare trigger personalizzati basati su qualsiasi campo o combinazione di campi del catalogo.

Canali Supportati

ArticoFlow si integra nativamente con i principali canali di vendita:

Configurazione Sync

Per ogni canale puoi configurare la direzione della sincronizzazione (unidirezionale o bidirezionale), la frequenza (tempo reale, ogni ora, giornaliera) e i campi da sincronizzare. Le impostazioni di mapping permettono di adattare i dati al formato specifico di ogni piattaforma.

Risoluzione Conflitti

In caso di modifiche simultanee su più canali, ArticoFlow applica una strategia di risoluzione configurabile: priorità al canale master, ultimo aggiornamento vince, o revisione manuale. I conflitti vengono registrati nel log per la tracciabilità completa.

Autenticazione API

L'API di ArticoFlow utilizza autenticazione tramite API Key. Le chiavi possono essere generate dalla dashboard nella sezione Impostazioni. Ogni chiave può avere permessi granulari.

curl -X GET https://api.articoflow.com/v1/articles \
  -H "Authorization: Bearer af_sk_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Endpoint Articoli

Gli endpoint principali per la gestione degli articoli:

Endpoint Categorie

Le categorie seguono la stessa struttura REST degli articoli. Gli endpoint supportano nidificazione, ordinamento e filtri avanzati.

const categories = await client.categories.list({
  parent: 'cat_abbigliamento',
  depth: 2,
  include_count: true
})

// Risposta:
// [
//   { id: 'cat_uomo', name: 'Uomo', article_count: 342, children: [...] },
//   { id: 'cat_donna', name: 'Donna', article_count: 518, children: [...] }
// ]

Webhook

Configura webhook per ricevere notifiche in tempo reale quando si verificano eventi nel tuo catalogo. Ogni webhook include una firma HMAC per la verifica dell'autenticità.

// Eventi disponibili:
// article.created, article.updated, article.deleted
// stock.low, stock.updated
// sync.completed, sync.failed
// automation.executed

const webhook = await client.webhooks.create({
  url: 'https://tuoserver.com/webhook',
  events: ['article.created', 'stock.low'],
  secret: 'whsec_xxxxxxxx'
})

Rate Limits

Le richieste API sono soggette a limiti per garantire la stabilità del servizio. I limiti si applicano per chiave API:

• Lettura: 1.000 richieste/minuto
• Scrittura: 200 richieste/minuto
• Bulk operations: 10 richieste/minuto

Gli header di risposta includono X-RateLimit-Remaining e X-RateLimit-Reset per monitorare l'utilizzo.

Gestione Utenti

Invita membri del team tramite email. Ogni utente può avere uno o più ruoli che determinano i permessi di accesso alle diverse sezioni della piattaforma.

Ruoli e Permessi

I ruoli predefiniti includono Admin, Editor, Viewer e API-only. Puoi creare ruoli personalizzati con permessi granulari per ogni sezione (catalogo, automazioni, sync, analytics, impostazioni).

Fatturazione

Il modello pay-as-you-go fattura mensilmente in base all'utilizzo effettivo. La dashboard fatturazione mostra in tempo reale i consumi correnti, le stime di costo e lo storico delle fatture. I metodi di pagamento accettati includono carta di credito, addebito diretto SEPA e bonifico bancario (per volumi superiori a 500/mese).

Sicurezza

ArticoFlow implementa crittografia end-to-end per tutti i dati, autenticazione a due fattori (2FA), SSO tramite SAML 2.0 per piani enterprise, audit log completo di tutte le operazioni e backup automatici giornalieri con retention di 30 giorni.