Smart Item API

API Version

Smart Item v1.0.0 (beta)
API basata su OpenAPI 3.1.0 con AI-enhanced metadata

Panoramica

La Smart Item API è un servizio AI-enhanced per la gestione intelligente degli articoli di magazzino. Utilizza algoritmi di machine learning per ottimizzare le operazioni CRUD e fornire insights predittivi sui dati degli articoli.

Versione API

Versione attuale: 1.0.0
OpenAPI: 3.1.0
AI-Enhanced: Con metadati AI per ogni endpoint

Caratteristiche principali

• Gestione articoli intelligente con validazione AI
• Estensioni AI native per ogni operazione
• Pattern URL standardizzato multi-tenant
• Validazione automatica dati cliente
• Intent recognition per categorizzazione automatica

Endpoint disponibili

Base URL Pattern

/api/\{product\}/\{version\}/company/\{companyId\}/warehouse/item

Parametri globali

Parametro	Tipo	Descrizione
product	string	Identificativo del prodotto TSE
version	string	Versione API (es. "v1")
companyId	string	ID univoco dell'azienda

Operazioni API

1. Creare un nuovo articolo

Endpoint: POST /api/\{product\}/\{version\}/company/\{companyId\}/warehouse/item

AI Metadata:

• Purpose: item_creation
• Entity: Item
• Intent: create

Request Body

{
    "code": "SS1",
    "creation-date": "2025-09-09T12:34:56.789Z",
    "update-date": "2025-09-09T12:34:56.789Z",
    "description": "Articolo Smart SS1",
    "vatcode": "22",
    "um": "PZ",
    "barcode": "9863214752175",
    "stockstoragecode": "00"
}

Schema dei dati

Campo	Tipo	Obbligatorio	Descrizione
code	string	Obbligatorio	codice articolo
creation-date	string	Obbligatorio	Data creazione
update-date	string	Obbligatorio	Data aggiornamento
description	string	Obbligatorio	Descrizione articolo
vatcode	string	Obbligatorio	Aliquota IVA
um	string	Non Obbligatorio	Unità di misura
barcode	string	Non Obbligatorio	Codice a barre
stockstoragecode	string	Obbligatorio	Deposito magazzino articolo

Risposte

Codice	Descrizione
201	Articolo creato con successo
400	Richiesta non valida

Esempio JavaScript

DA RIVEDERE

const createCustomer = async (companyId, customerData) => {
  try {
    const response = await fetch(`/api/tse/v1/company/${companyId}/customer`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`
      },
      body: JSON.stringify(customerData)
    });
    
    if (response.status === 201) {
      console.log('Cliente creato con successo');
      return await response.json();
    }
    throw new Error(`Errore ${response.status}`);
  } catch (error) {
    console.error('Errore creazione cliente:', error);
  }
};

// Utilizzo
const nuovoCliente = {
  "first-name": "Mario",
  "last-name": "Rossi",
  "email": "mario.rossi@example.com", 
  "vat-number": "IT12345678901"
};

await createCustomer("company123", nuovoCliente);

2. Recuperare tutti gli articoli

Endpoint: GET /api/\{product\}/\{version\}/company/\{companyId\}/warehouse/items

AI Metadata:

• Purpose: items_listing
• Entity: Item
• Intent: retrieve

Parametri

Solo i parametri path globali (product, version, companyId).

Risposte

Codice	Descrizione
200	Elenco articoli restituito con successo
404	Articoli non trovati

3. Recuperare un articolo specifico

Endpoint: GET /api/\{product\}/\{version\}/company/\{companyId\}/warehouse/item/\{itemId\}

AI Metadata:

• Purpose: item_detail
• Entity: Item
• Intent: retrieve

Parametri aggiuntivi

Parametro	Tipo	Descrizione
ItemId	string	ID univoco del codice articolo

Risposte

Codice	Descrizione
200	Dettagli articolo restituiti con successo
404	Articolo non trovato

4. Eliminare un articolo

Endpoint: DELETE /api/{product}/{version}/company/{companyId}/warehouse/item/\{itemId\}

AI Metadata:

• Purpose: item_deletion
• Entity: Item
• Intent: delete

Parametri

Parametro	Tipo	Descrizione
itemId	string	ID del codice articolo da eliminare

Risposte

Codice	Descrizione
204	Articolo eliminato con successo
404	Articolo non trovato

Esempio JavaScript con conferma

const deleteCustomer = async (companyId, customerId) => {
  // Conferma eliminazione
  const confirmed = confirm(`Sei sicuro di voler eliminare il cliente ${customerId}?`);
  if (!confirmed) return false;

  try {
    const response = await fetch(`/api/tse/v1/company/${companyId}/customer/${customerId}`, {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${token}`
      }
    });
    
    if (response.status === 204) {
      console.log(`Cliente ${customerId} eliminato con successo`);
      return true;
    } else if (response.status === 404) {
      console.warn(`Cliente ${customerId} non trovato`);
      return false;
    }
    
    throw new Error(`Errore ${response.status}`);
  } catch (error) {
    console.error('Errore eliminazione cliente:', error);
    return false;
  }
};

// Utilizzo
const eliminated = await deleteCustomer("company123", "456");

Gestione errori centralizzata

const handleApiError = (response) => {
  switch(response.status) {
    case 400:
      throw new Error('Dati richiesta non validi');
    case 401:
      throw new Error('Token di autenticazione non valido');
    case 404:
      throw new Error('Risorsa non trovata');
    case 500:
      throw new Error('Errore interno del server');
    default:
      throw new Error(`Errore API: ${response.status}`);
  }
};

Best practices

1. Validazione lato client

const validateCustomerData = (customer) => {
  const errors = [];
  
  if (!customer['first-name']?.trim()) {
    errors.push('Nome obbligatorio');
  }
  
  if (!customer['email']?.includes('@')) {
    errors.push('Email non valida');
  }
  
  if (!customer['vat-number']?.match(/^[A-Z]{2}\d{11}$/)) {
    errors.push('Partita IVA formato non valido');
  }
  
  return errors;
};

2. Retry logic per resilienza

const apiCallWithRetry = async (apiCall, maxRetries = 3) => {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await apiCall();
    } catch (error) {
      if (attempt === maxRetries) throw error;
      
      // Exponential backoff
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
};

3. Caching intelligente

const customerCache = new Map();

const getCachedCustomer = async (companyId, customerId) => {
  const cacheKey = `${companyId}:${customerId}`;
  
  if (customerCache.has(cacheKey)) {
    const cached = customerCache.get(cacheKey);
    if (Date.now() - cached.timestamp < 300000) { // 5 minuti
      return cached.data;
    }
  }
  
  const customer = await getCustomerDetails(companyId, customerId);
  customerCache.set(cacheKey, {
    data: customer,
    timestamp: Date.now()
  });
  
  return customer;
};

Link correlati

• Getting Started - Setup iniziale
• Autenticazione - Configurazione token
• SDK Overview - Librerie client
• AI Services Overview - Altri servizi AI

📞 Supporto

Per domande specifiche sulla Smart Customer API:

• 📧 Email: smart-services@tse.it
• 📚 Documentazione: TSE Smart Services Hub
• 🐛 Bug Report: GitHub Issues