Smart Item API

API Version

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

Overview

The Smart Item API is an AI-enhanced service for the intelligent management of warehouse items. It uses machine learning algorithms to optimize CRUD operations and provide predictive insights on item data.

Versione API

Versione attuale: 1.0.0
OpenAPI: 3.1.0
AI-Enhanced: With metadati AI per every endpoint

Key Features

• Intelligent item management with AI validation
• Native AI extensions for each operation
• Standardizzed Pattern URL multi-tenant
• Automatic Validation customer data
• Intent recognition for automatic categorization

Available Endpoint

Base URL Pattern

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

Global Parameters

Parameter	Type	Description
product	string	TSE product identifier
version	string	API version (e.g. "v1")
companyId	string	Unique company ID

Operazioni API

1. Create a new customer

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"
}

Data Schema

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

Responses

Code	Description
201	Item created successfully
400	Invalid request

Esempio JavaScript

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. Retrieve all customers

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

AI Metadata:

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

Parameters

Only global path parameters (product, version, companyId).

Responses

Code	Description
200	Item list returned successfully
404	Items not found

3. Retrieve a specific customer

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

AI Metadata:

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

Additional Parameters

Parameter	Type	Description
itemId	string	Unique item ID

Responses

Code	Description
200	Item details returned successfully
404	Item not found

4. Delete a item

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

AI Metadata:

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

Parameters

Parameter	Type	Description
itemId	string	ID of item to delete

Responses

Code	Description
204	Item deleted successfully
404	Item not found

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");

Centralized error handling

const handleApiError = (response) => {
  switch(response.status) {
    case 400:
      throw new Error('Invalid request data');
    case 401:
      throw new Error('Invalid authentication token');
    case 404:
      throw new Error('Resource not found');
    case 500:
      throw new Error('Internal server error');
    default:
      throw new Error(`API Error: ${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