Skip to main content
Version: 1.0.0 (beta)

Smart Supplier Management API

API Version

Smart Supplier Management 1.0.0
API basata su OpenAPI 3.1.0 con AI-enhanced metadata

Panoramica​

La Smart Supplier Management API è un servizio AI-enhanced per la gestione intelligente dei fornitori aziendali. Utilizza algoritmi di machine learning per ottimizzare le operazioni CRUD e fornire insights predittivi sui dati dei fornitori.

Versione API

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

Caratteristiche principali​

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

Endpoint disponibili​

Base URL Pattern​

/api/\{product\}/\{version\}/company/\{companyId\}/Supplier

Parametri globali​

ParametroTipoDescrizione
productstringIdentificativo del prodotto TSE
versionstringVersione API (es. "v1")
companyIdstringID univoco dell'azienda

Operazioni API​

1. Creare un nuovo fornitore​

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

AI Metadata:

  • Purpose: Supplier_creation
  • Entity: Supplier
  • Intent: create

Request Body​

{
  "first-name": "Paolo",
  "last-name": "Rossi", 
  "email": "paolo.rossi@example.com",
  "vat-number": "IT12345678901"
}

Schema dei dati​

CampoTipoObbligatorioDescrizione
first-namestringObbligatorioNome del fornitore
last-namestringObbligatorioCognome del fornitore
emailstringObbligatorioEmail (formato valido)
vat-numberstringObbligatorioPartita IVA fornitore

Risposte​

CodiceDescrizione
201fornitore creato con successo
400Richiesta non valida

Esempio JavaScript​

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

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

await createSupplier("company123", nuovofornitore);

2. Recuperare tutti i fornitori​

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

AI Metadata:

  • Purpose: Supplier_listing
  • Entity: Supplier
  • Intent: retrieve

Parametri​

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

Risposte​

CodiceDescrizione
200Elenco fornitori restituito con successo
404fornitori non trovati

Esempio C#​

using System.Text.Json;

public async Task<List<Supplier>> GetAllSuppliersAsync(string companyId)
{
    try
    {
        var url = $"/api/tse/v1/company/{companyId}/Supplier";
        var response = await httpClient.GetAsync(url);
        
        if (response.IsSuccessStatusCode)
        {
            var json = await response.Content.ReadAsStringAsync();
            var Suppliers = JsonSerializer.Deserialize<List<Supplier>>(json);
            Console.WriteLine($"Recuperati {Suppliers.Count} fornitori");
            return Suppliers;
        }
        
        throw new HttpRequestException($"Errore {response.StatusCode}");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Errore recupero fornitori: {ex.Message}");
        return new List<Supplier>();
    }
}

// Utilizzo
var fornitori = await GetAllSuppliersAsync("company123");

3. Recuperare un fornitore specifico​

Endpoint: GET /api/\{product\}/\{version\}/company/\{companyId\}/Supplier/\{SupplierId\}

AI Metadata:

  • Purpose: Supplier_detail
  • Entity: Supplier
  • Intent: retrieve

Parametri aggiuntivi​

ParametroTipoDescrizione
SupplierIdstringID univoco del fornitore

Risposte​

CodiceDescrizione
200Dettagli fornitore restituiti con successo
404fornitore non trovato

Esempio Python​

import requests
import json

async def get_Supplier_details(company_id: str, Supplier_id: str) -> dict:
    """
    Recupera i dettagli di un fornitore specifico
    
    Args:
        company_id: ID dell'azienda
        Supplier_id: ID del fornitore
        
    Returns:
        dict: Dati del fornitore o None se non trovato
    """
    try:
        url = f"/api/tse/v1/company/{company_id}/Supplier/{Supplier_id}"
        headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
        
        response = requests.get(url, headers=headers)
        
        if response.status_code == 200:
            Supplier_data = response.json()
            print(f"fornitore {Supplier_id} recuperato con successo")
            return Supplier_data
        elif response.status_code == 404:
            print(f"fornitore {Supplier_id} non trovato")
            return None
        else:
            raise requests.HTTPError(f"Errore {response.status_code}")
            
    except Exception as e:
        print(f"Errore recupero fornitore: {e}")
        return None

# Utilizzo
fornitore = await get_Supplier_details("company123", "456")

4. Eliminare un fornitore​

Endpoint: DELETE /api/{product}/{version}/company/{companyId}/Supplier/{SupplierId}

AI Metadata:

  • Purpose: Supplier_deletion
  • Entity: Supplier
  • Intent: delete

Parametri​

ParametroTipoDescrizione
SupplierIdstringID del fornitore da eliminare

Risposte​

CodiceDescrizione
204fornitore eliminato con successo
404fornitore non trovato

Esempio JavaScript con conferma​

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

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

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

Funzionalità AI integrate​

Metadati AI per ogni endpoint​

Ogni operazione include metadati AI specifici:

{
  "x-ai-purpose": "Supplier_creation",
  "x-ai-entity": "Supplier", 
  "x-ai-intent": "create",
  "x-ai-sample": {
    "first-name": "Mario",
    "last-name": "Rossi",
    "email": "mario.rossi@example.com",
    "vat-number": "IT12345678901"
  }
}

Intent Recognition​

IntentDescrizioneEndpoint
createCreazione nuovo fornitorePOST /Supplier
retrieveRecupero dati fornitore/iGET /Supplier
deleteEliminazione fornitoreDELETE /Supplier/{id}

🔧 Configurazione​

Autenticazione​

// Setup headers per tutte le richieste
const defaultHeaders = {
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${accessToken}`,
  'X-API-Version': '1.0.0'
};

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 validateSupplierData = (Supplier) => {
  const errors = [];
  
  if (!Supplier['first-name']?.trim()) {
    errors.push('Nome obbligatorio');
  }
  
  if (!Supplier['email']?.includes('@')) {
    errors.push('Email non valida');
  }
  
  if (!Supplier['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 SupplierCache = new Map();

const getCachedSupplier = async (companyId, SupplierId) => {
  const cacheKey = `${companyId}:${SupplierId}`;
  
  if (SupplierCache.has(cacheKey)) {
    const cached = SupplierCache.get(cacheKey);
    if (Date.now() - cached.timestamp < 300000) { // 5 minuti
      return cached.data;
    }
  }
  
  const Supplier = await getSupplierDetails(companyId, SupplierId);
  SupplierCache.set(cacheKey, {
    data: Supplier,
    timestamp: Date.now()
  });
  
  return Supplier;
};

📞 Supporto​

Per domande specifiche sulla Smart Supplier API:

Last updated on