Playground API

Testa l'endpoint di analisi prodotti con i tuoi dati.

Autenticazione Richiesta

Devi essere loggato per utilizzare il Playground API. Accedi per continuare.

Endpoint Analisi Prodotti

Invia prodotti per analisi e arricchimento dei dati

POST

L'endpoint di analisi consente di inviare codici prodotto (EAN, ASIN o MINSAN) per analisi e arricchimento. Questo processo creerà o aggiornerà i record dei prodotti nel tuo inventario con informazioni dettagliate provenienti da diverse fonti.

Ogni richiesta di analisi consumerà crediti in base ai servizi richiesti e al modello selezionato.

URL dell'Endpoint
POST https://api.commerceclarity.io/products/analyze

Parametri della Richiesta

Parametro Tipo Obbligatorio Descrizione
codes string Obbligatorio* Uno o più codici prodotto (EAN, ASIN o MINSAN) separati da virgola. *Non richiesto se viene fornito il parametro visual
agent_model string Opzionale Modello dell'agente. Valori accettati: "v2" (default) - modello migliore, "v1". Influisce sul tipo di crediti consumati. *Per le richieste visual il modello non può essere impostato ed è sempre v2
price numeric Condizionale Il prezzo del tuo prodotto. Obbligatorio se viene richiesto il servizio competitors_prices
shipping_cost numeric Condizionale Il costo di spedizione. Obbligatorio se viene richiesto il servizio competitors_prices
operation string Opzionale Operazioni di rinnovo del prodotto. Valori: "refresh" (disponibile solo per prodotti presumibilmente errati, ricrea il prodotto senza consumare crediti) o "renew" (aggiorna gratuitamente il prodotto fino a 3 volte con dati aggiuntivi)
additional_data string Opzionale Dati aggiuntivi per l'analisi. Utilizzabile solo quando si specifica un singolo codice prodotto
services array|object Opzionale Servizi da attivare. Servizi disponibili: "import", "competitors_prices". È possibile passare questo parametro sia come object "services":{"import":true} che come array "services": ["import"]
services.import boolean Opzionale Abilita il servizio di importazione prodotti. L'import delle schede funzionerà solamente se abilitato sull'account
services.competitors_prices boolean Opzionale Abilita l'analisi dei prezzi dei concorrenti. L'analisi dei prezzi dei concorrenti funzionerà solamente se abilitata sull'account
countries array Opzionale Paesi target per l'analisi (es. ["it", "uk", "de"]). Default: ["it"]. Disponibili: ['it', 'uk', 'de', 'fr', 'es']. L'import per paesi diversi funzionerà solamente se abilitati sull'account. Non disponibile per i prezzi dei competitor
visual object Opzionale Informazioni visive per l'analisi basata su immagini
visual.title string Obbligatorio** Titolo del prodotto. **Obbligatorio se viene usato visual
visual.brand string Obbligatorio** Marca del prodotto. **Obbligatorio se viene usato visual
visual.images_list array Obbligatorio** Lista di URL delle immagini del prodotto. Minimo 1, massimo 5. **Obbligatorio se viene usato visual
visual.customer_product_id string Obbligatorio** ID interno del prodotto (SKU). **Obbligatorio se viene usato visual
visual.product_specifications string Opzionale Specifiche tecniche del prodotto in formato testo
visual.description string Opzionale Descrizione del prodotto in formato testo

Esempi di Richieste

Analisi Prodotto Base
{
  "codes": "8004120057724", 
  "services": [
    "import",
    "competitors_prices"
  ],
  "price": 12.99,
  "shipping_cost": 4.99,
  "countries": ["it"]
}
Analisi Prodotti Multipli
{
  "codes": "8004120057724,8004120061721,8004120057731",
  "services": [
    "import",
    "competitors_prices"
  ],
  "price": 15.99,
  "shipping_cost": 4.99,
  "countries": ["it"]
}
Opzioni Analisi Avanzate
{
  "codes": "8004120057724",
  "agent_model": "v2",
  "price": 12.99,
  "shipping_cost": 4.99,
  "services": {
    "import": true,
    "competitors_prices": true
  },
  "operation": "renew",
  "additional_data": "Prodotto premium con packaging ecologico",
  "countries": ["it", "uk", "de"]
}
Analisi Visuale
{
"visual": {
  "title": "Crema Idratante Organica",
  "brand": "NaturaSkin",
  "images_list": [
    "https://example.com/images/product1.jpg",
    "https://example.com/images/product1-angle.jpg",
    "https://example.com/images/product1-ingredients.jpg"
  ],
  "customer_product_id": "NS-CRIO-001",
  "product_specifications": "Ingredienti: Aqua, Aloe Barbadensis Leaf Juice, Glycerin, Cetearyl Alcohol. Contenuto: 50ml",
  "description": "Crema idratante biologica formulata con ingredienti naturali. Ideale per pelli sensibili e secche."
},
"services": {
  "import": true,
  "competitors_prices": true
},
"price": 19.99,
"shipping_cost": 3.99,
"countries": ["it"]
}

Risposta

L'endpoint di analisi restituisce un oggetto di stato con informazioni sul successo o fallimento della richiesta, insieme al saldo aggiornato dei crediti per il tuo account.

Risposta di Successo
{
  "status": "success",
  "message": "I codici richiesti sono stati aggiunti alla coda di elaborazione con successo",
  "credits": {
    "content": {
      "max": 100,
      "used": 27
    },
    "analytics": {
      "max": 100,
      "used": 34
    }
  }
}
Risposta di Errore - Validazione
{
  "status": "error",
  "errors": [
    "Non hai abbastanza crediti per elaborare questo prodotto",
    "Il campo 'price' è obbligatorio quando si richiede l'analisi dei prezzi concorrenti."
  ]
}

Consumo di Crediti

Ogni chiamata API all'endpoint di analisi consumerà crediti dal tuo account in base ai servizi richiesti e al modello dell'agente selezionato.

Servizio Modello Crediti Utilizzati Descrizione
import v1 1 credito content Importazione prodotto con il modello base
import v2 (predefinito) 5 Crediti Content Importazione prodotto con modello alternativo
competitors_prices Qualsiasi 1 credito analytics Analisi dei prezzi dei concorrenti su vari marketplace

Flusso di Elaborazione

Una volta che un prodotto viene elaborato tramite l'endpoint di analisi, sarà aggiunto al tuo inventario. Il processo di analisi segue questi passaggi:

Flusso di Elaborazione
  1. La tua applicazione invia una richiesta all'endpoint <code>/api/products/analyze</code> con i codici prodotto e i servizi desiderati.
  2. L'API convalida la richiesta e verifica la disponibilità di crediti sufficienti.
  3. Se valida, il prodotto viene aggiunto alla coda di elaborazione.
  4. I sistemi di CommerceClarity elaborano il prodotto in modo asincrono:
    • Raccolta dei dati del prodotto da più fonti
    • Se richiesto, analisi dei prezzi dei concorrenti da vari marketplace
    • Creazione o aggiornamento del prodotto nel tuo inventario
  5. Puoi monitorare lo stato del prodotto tramite la dashboard o l'API.

Limitazioni di Frequenza

L'endpoint di analisi è soggetto a limitazioni di frequenza per garantire la stabilità del sistema. Limiti attuali:

  • Massimo 5 richieste al secondo
  • Massimo 50 codici per richiesta
  • Per l'analisi visuale: un solo prodotto per richiesta

Se hai bisogno di limiti più elevati, contatta il nostro team di supporto.

Esempi di Codice

Esempio PHP (Utilizzo del Client HTTP Guzzle)
<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new Client([
    'base_uri' => 'https://api.commerceclarity.io',
    'timeout'  => 10.0,
    'headers' => [
        'Authorization' => 'Bearer IL_TUO_TOKEN_API',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ]
]);

$productData = [
    'codes' => '8004120057724',
    'services' => [
        'import' => true,
        'competitors_prices' => true
    ],
    'price' => 12.99,
    'shipping_cost' => 4.99,
    'countries' => ['it']
];

try {
    $response = $client->post('/products/analyze', [
        'json' => $productData
    ]);
    
    $result = json_decode($response->getBody()->getContents(), true);
    
    echo "Status: " . $result['status'] . "\n";
    echo "Messaggio: " . $result['message'] . "\n";
    
    // Visualizza i crediti rimanenti
    if (isset($result['credits'])) {
        echo "Crediti Content: " . ($result['credits']['content']['max'] - $result['credits']['content']['used']) . "\n";
        echo "Crediti Analytics: " . ($result['credits']['analytics']['max'] - $result['credits']['analytics']['used']) . "\n";
    }
    
} catch (RequestException $e) {
    echo "Errore: " . $e->getMessage() . "\n";
    
    if ($e->hasResponse()) {
        $errorResponse = json_decode($e->getResponse()->getBody()->getContents(), true);
        
        if (isset($errorResponse['errors'])) {
            echo "Errori di validazione:\n";
            foreach ($errorResponse['errors'] as $error) {
                echo "- " . $error . "\n";
            }
        }
    }
}
Esempio JavaScript (Fetch API)
// Dati del prodotto da analizzare
const productData = {
  codes: '8004120057724',
  services: {
    import: true,
    competitors_prices: true
  },
  price: 12.99,
  shipping_cost: 4.99,
  countries: ['it']
};

// Configurazione della richiesta
const apiUrl = 'https://api.commerceclarity.io/products/analyze';
const token = 'IL_TUO_TOKEN_API';

// Effettua una richiesta API
fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify(productData)
})
.then(response => {
  if (!response.ok) {
    return response.json().then(errorData => {
      throw new Error(errorData.errors ? errorData.errors.join(', ') : `Status: ${response.status}`);
    });
  }
  return response.json();
})
.then(data => {
  console.log('Risposta:', data);
  
  // Gestione della risposta
  if (data.status === 'success') {
    console.log('Messaggio:', data.message);
    
    // Visualizza i crediti rimanenti
    if (data.credits) {
      console.log('Crediti Content:', data.credits.content.max - data.credits.content.used);
      console.log('Crediti Analytics:', data.credits.analytics.max - data.credits.analytics.used);
    }
  }
})
.catch(error => {
  console.error('Errore durante l'analisi del prodotto:', error.message);
});
Esempio Python (Requests)
import requests
import json

# Configurazione API
api_url = 'https://api.commerceclarity.io/products/analyze'
token = 'IL_TUO_TOKEN_API'

headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
}

# Dati del prodotto da analizzare
product_data = {
    'codes': '8004120057724',
    'services': {
        'import': True,
        'competitors_prices': True
    },
    'price': 12.99,
    'shipping_cost': 4.99,
    'countries': ['it']
}

try:
    # Effettua la richiesta POST
    response = requests.post(
        api_url,
        headers=headers,
        json=product_data
    )
    
    # Solleva un'eccezione per risposte HTTP 4XX/5XX
    response.raise_for_status()
    
    # Estrai i dati dalla risposta
    result = response.json()
    
    print(f"Status: {result['status']}")
    print(f"Messaggio: {result['message']}")
    
    # Visualizza i crediti rimanenti
    if 'credits' in result:
        credits = result['credits']
        print(f"Crediti Content: {credits['content']['max'] - credits['content']['used']}")
        print(f"Crediti Analytics: {credits['analytics']['max'] - credits['analytics']['used']}")
        
except requests.exceptions.HTTPError as err:
    print(f"Errore HTTP: {err}")
    if response.text:
        error_data = response.json()
        if 'errors' in error_data:
            print("Errori di validazione:")
            for error in error_data['errors']:
                print(f"- {error}")
        
except requests.exceptions.RequestException as err:
    print(f"Errore durante la richiesta: {err}")
Esempio cURL
curl -X POST "https://api.commerceclarity.io/products/analyze" \
     -H "Authorization: Bearer IL_TUO_TOKEN_API" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
       "codes": "8004120057724",
       "services": {
         "import": true,
         "competitors_prices": true
       },
       "price": 12.99,
       "shipping_cost": 4.99,
       "countries": ["it"]
     }'

Risorse Correlate

Autenticazione

Impara come autenticare le tue richieste API con token di accesso.

Vai all'Autenticazione
Dettagli Prodotto

Verifica lo stato attuale di un prodotto specifico nel tuo inventario.

Vai a Dettagli Prodotto
Stato Prodotto

Gestisci lo stato di pubblicazione dei tuoi prodotti.

Vai a Stato Prodotto