Playground API

Testa l'endpoint di lista prodotti.

Autenticazione Richiesta

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

Endpoint Lista Prodotti

Ottieni una lista paginata dei prodotti nel tuo inventario

GET

L'endpoint di lista prodotti consente di recuperare un elenco paginato dei prodotti presenti nel tuo inventario. La risposta include informazioni base su ciascun prodotto come codice, nome, marca, categoria e stato di pubblicazione.

La risposta è paginata con 50 prodotti per pagina e include metadati di paginazione per facilitare la navigazione tra le pagine.

URL dell'Endpoint
GET https://api.commerceclarity.io/products/index

Parametri della Richiesta

Parametro Tipo Obbligatorio Descrizione
page integer Opzionale Numero della pagina richiesta. Default: 1

Struttura della Risposta

Lista di tutti i prodotti (50 prodotti per pagina)

Risposta di Successo
{
  "status": "success",
  "data": {
    "current_page": 1,
    "data": [
      {
        "code": "4719512154854",
        "price": null,
        "shipping_cost": null,
        "thumb": "https://api.commerceclarity.io/storage/681a260241c6ccdf3308de44/0.jpg",
        "countries": {
          "it": {
            "name": "Cooler Master MasterLiquid 360 Core II AIO 360mm Dissipatore a Liquido Pompa Doppia Camera",
            "brand": "Cooler Master",
            "category": [
              "Dispositivi elettronici",
              "Accessori dispositivi elettronici",
              "Componenti per computer",
              "Componenti di raffreddamento per PC"
            ]
          },
          "de": {
            "name": "Cooler Master MasterLiquid 360 Core II AIO 360mm Flüssigkeitskühler Doppelkammersystem",
            "brand": "Cooler Master",
            "category": [
              "Elektronikgeräte",
              "Zubehör für Elektronikgeräte",
              "Computerkomponenten",
              "PC-Kühlkomponenten"
            ]
          },
          "fr": {
            "name": "Cooler Master MasterLiquid 360 Core II AIO 360mm Dissipateur à Liquide Pompe Double Chambre",
            "brand": "Cooler Master",
            "category": [
              "Dispositifs électroniques",
              "Accessoires dispositifs électroniques",
              "Composants pour ordinateurs",
              "Composants de refroidissement pour PC"
            ]
          }
        },
        "publication_state": "ready",
        "validation_messages": []
      },
      
      // ... altri prodotti ...
      
    ],
    "first_page_url": "https://api.commerceclarity.io/products/index?page=1",
    "from": 1,
    "last_page": 48,
    "last_page_url": "https://api.commerceclarity.io/products/index?page=48",
    "links": [
      {
        "url": null,
        "label": "pagination.previous",
        "active": false
      },
      {
        "url": "https://api.commerceclarity.io/products/index?page=1",
        "label": "1",
        "active": true
      },
      // ... altri link ...
    ],
    "next_page_url": "https://api.commerceclarity.io/products/index?page=2",
    "path": "https://api.commerceclarity.io/products/index",
    "per_page": 50,
    "prev_page_url": null,
    "to": 50,
    "total": 2369
  }
}

Struttura della Paginazione

Campo Tipo Descrizione
current_page integer Numero della pagina corrente
first_page_url string URL per la prima pagina
from integer Indice del primo elemento nella pagina corrente
last_page integer Numero dell'ultima pagina
last_page_url string URL per l'ultima pagina
links array Array di link per la navigazione
next_page_url string|null URL per la pagina successiva
path string URL base dell'endpoint
per_page integer Numero di elementi per pagina
prev_page_url string|null URL per la pagina precedente
to integer Indice dell'ultimo elemento nella pagina corrente
total integer Numero totale di elementi disponibili
data array Array di prodotti nella pagina corrente

Struttura di un Elemento Prodotto

Campo Tipo Descrizione
code string Codice principale del prodotto (EAN, ASIN o MINSAN)
price float|null Prezzo
shipping_cost float|null Costo Spedizione
thumb string|null URL dell'immagine di anteprima del prodotto
countries object Informazioni del prodotto per ogni paese supportato
countries.XX.name string Nome completo del prodotto (XX è il codice paese)
countries.XX.brand string Marca del prodotto (XX è il codice paese)
countries.XX.category array Alberatura categorie Google del prodotto (XX è il codice paese)
publication_state string Stato di pubblicazione del prodotto (es. "online", "ready")
validation_messages array Eventuali messaggi di validazione o avvisi relativi al prodotto

Navigazione tra le Pagine

  • Usa il parametro page nell'URL per specificare la pagina desiderata
  • I link per la navigazione sono forniti nei campi links, next_page_url e prev_page_url
  • Ogni risposta include metadati come total e last_page per aiutarti a gestire la paginazione

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',
    ]
]);

// Numero di pagina (Opzionale)
$page = 1; // Prima pagina

try {
    $response = $client->get('/products/index', [
        'query' => [
            'page' => $page
        ]
    ]);
    
    $result = json_decode($response->getBody()->getContents(), true);
    
    echo "Stato: " . $result['status'] . "\n";
    echo "Pagina corrente: " . $result['data']['current_page'] . "\n";
    echo "Totale prodotti: " . $result['data']['total'] . "\n";
    echo "Prodotti per pagina: " . $result['data']['per_page'] . "\n";
    echo "Pagine totali: " . $result['data']['last_page'] . "\n\n";
    
    echo "Prodotti nella pagina corrente:\n";
    foreach ($result['data']['data'] as $index => $product) {
        echo ($index + 1) . ". ";
        
        // Prodotti in italiano se disponibili
        if (isset($product['countries']['it']['name'])) {
            echo $product['countries']['it']['name'];
        } else {
            echo "Prodotto " . $product['code'];
        }
        
        echo " (Stato: " . $product['publication_state'] . ")\n";
    }
    
    // Navigazione
    echo "\nNavigazione:\n";
    echo "Pagina precedente: " . ($result['data']['prev_page_url'] ?? "Non disponibile") . "\n";
    echo "Pagina successiva: " . ($result['data']['next_page_url'] ?? "Non disponibile") . "\n";
    
} catch (RequestException $e) {
    echo "Errore: " . $e->getMessage() . "\n";
    
    if ($e->hasResponse()) {
        $errorResponse = json_decode($e->getResponse()->getBody()->getContents(), true);
        echo "Stato: " . ($errorResponse['status'] ?? 'sconosciuto') . "\n";
        echo "Messaggio: " . ($errorResponse['message'] ?? 'nessun messaggio') . "\n";
    }
}
Esempio JavaScript (Fetch API)
// Configurazione API
const apiUrl = 'https://api.commerceclarity.io/products/index';
const token = 'IL_TUO_TOKEN_API';

// Numero di pagina (Opzionale)
const page = 1; // Prima pagina

// Effettua una richiesta API
const requestUrl = `${apiUrl}?page=${page}`;

// Configurazione della richiesta
const requestOptions = {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Accept': 'application/json'
  }
};

// Effettua una richiesta API
fetch(requestUrl, requestOptions)
  .then(response => {
    if (!response.ok) {
      return response.json().then(errorData => {
        throw new Error(errorData.message || `Status: ${response.status}`);
      });
    }
    return response.json();
  })
  .then(data => {
    console.log('Risposta:', data);
    
    // Struttura della Paginazione
    console.log(`Pagina corrente: ${data.data.current_page}`);
    console.log(`Totale prodotti: ${data.data.total}`);
    console.log(`Prodotti per pagina: ${data.data.per_page}`);
    console.log(`Pagine totali: ${data.data.last_page}`);
    
    // Elabora i dati
    const products = data.data.data;
    console.log(`Prodotti nella pagina corrente: ${products.length}`);
    
    // Esempio: visualizzazione dei prodotti in una tabella
    const productList = document.getElementById('product-list');
    if (productList) {
      // Svuota la lista esistente
      productList.innerHTML = '';
      
      // Crea intestazione tabella
      const headerRow = document.createElement('tr');
      headerRow.innerHTML = `
        Codice
        Nome completo del prodotto
        Marca del prodotto
        Status
      `;
      productList.appendChild(headerRow);
      
      // Aggiungi ogni prodotto
      products.forEach(product => {
        const productRow = document.createElement('tr');
        
        // Ottieni le informazioni del prodotto (preferibilmente in italiano se disponibile)
        const productInfo = product.countries.it || product.countries.en || Object.values(product.countries)[0] || {};
        
        productRow.innerHTML = `
          ${product.code}
          ${productInfo.name || 'N/D'}
          ${productInfo.brand || 'N/D'}
          ${product.publication_state}
        `;
        
        productList.appendChild(productRow);
      });
    }
    
    // Aggiorna i controlli di paginazione
    updatePaginationControls(data.data);
  })
  .catch(error => {
    console.error('Errore durante il recupero dei prezzi dei concorrenti:', error.message);
    
    // Mostra un messaggio di errore all'utente
    showNotification(`Errore: ${error.message}`, 'error');
  });

// Funzione di utilità per determinare il colore dello stato di pubblicazione
function getStatusColor(state) {
  switch (state) {
    case 'online':
      return 'success';
    case 'ready':
      return 'primary';
    case 'pending_review':
      return 'warning';
    default:
      return 'secondary';
  }
}

// Funzione per aggiornare i controlli di paginazione
function updatePaginationControls(pagination) {
  const paginationElement = document.getElementById('pagination');
  if (!paginationElement) return;
  
  paginationElement.innerHTML = '';
  
  // Crea pulsante per la pagina precedente
  const prevButton = document.createElement('button');
  prevButton.classList.add('btn', 'btn-outline-primary', 'me-2');
  prevButton.innerHTML = '« Precedente';
  prevButton.disabled = !pagination.prev_page_url;
  prevButton.onclick = () => loadPage(pagination.current_page - 1);
  paginationElement.appendChild(prevButton);
  
  // Aggiungi pulsanti per le pagine numeriche
  pagination.links.forEach(link => {
    if (link.url && !isNaN(link.label) && link.label !== '...') {
      const pageButton = document.createElement('button');
      pageButton.classList.add('btn', 'btn-outline-primary', 'me-2');
      if (link.active) {
        pageButton.classList.add('active');
      }
      pageButton.textContent = link.label;
      pageButton.onclick = () => loadPage(parseInt(link.label));
      paginationElement.appendChild(pageButton);
    }
  });
  
  // Crea pulsante per la pagina successiva
  const nextButton = document.createElement('button');
  nextButton.classList.add('btn', 'btn-outline-primary');
  nextButton.innerHTML = 'Successivo »';
  nextButton.disabled = !pagination.next_page_url;
  nextButton.onclick = () => loadPage(pagination.current_page + 1);
  paginationElement.appendChild(nextButton);
}

// Funzione per caricare una pagina specifica
function loadPage(pageNumber) {
  // Aggiorna l'URL con il nuovo numero di pagina e ricarica i dati
  window.location.href = `?page=${pageNumber}`;
}

// Funzione di utilità per mostrare notifiche
function showNotification(message, type) {
  // Implementazione della tua funzione di notifica
  console.log(`[${type.toUpperCase()}] ${message}`);
}
Esempio Python (Requests)
import requests
import json

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

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

# Parametri della Richiesta
params = {
    'page': 1  # Prima pagina (Opzionale)
}

try:
    # Effettua la richiesta POST
    response = requests.get(
        api_url,
        headers=headers,
        params=params
    )
    
    # Solleva un'eccezione per risposte HTTP 4XX/5XX
    response.raise_for_status()
    
    # Estrai i dati dalla risposta
    result = response.json()
    
    print(f"Stato: {result['status']}")
    print(f"Pagina corrente: {result['data']['current_page']}")
    print(f"Totale prodotti: {result['data']['total']}")
    print(f"Prodotti per pagina: {result['data']['per_page']}")
    print(f"Pagine totali: {result['data']['last_page']}\n")
    
    print("Prodotti nella pagina corrente:")
    for index, product in enumerate(result['data']['data']):
        print(f"{index + 1}. ", end="")
        
        # Show the product name for the IT country if available
        if 'it' in product['countries'] and 'name' in product['countries']['it']:
            print(f"{product['countries']['it']['name']}", end="")
        else:
            print(f"Prodotto {product['code']}", end="")
        
        print(f" (Stato: {product['publication_state']})")
    
    # Navigazione tra le Pagine
    print("\nNavigazione:")
    prev_page_url = result['data']['prev_page_url']
    next_page_url = result['data']['next_page_url']
    print(f"Pagina precedente: {prev_page_url if prev_page_url else 'Non disponibile'}")
    print(f"Pagina successiva: {next_page_url if next_page_url else 'Non disponibile'}")
    
    # Esempio: automatic navigation between pages
    def fetch_all_products():
        """Utility function to retrieve all products through pagination."""
        all_products = []
        current_page = 1
        last_page = result['data']['last_page']
        
        print(f"\nRecupero di tutti i prodotti ({result['data']['total']}) attraverso {last_page} pagine...")
        
        while current_page <= last_page:
            print(f"Recupero pagina {current_page}...")
            
            page_response = requests.get(
                api_url,
                headers=headers,
                params={'page': current_page}
            )
            page_response.raise_for_status()
            page_data = page_response.json()
            
            # Add the products from the current page to the complete list
            all_products.extend(page_data['data']['data'])
            
            current_page += 1
        
        print(f"Totale prodotti recuperati: {len(all_products)}")
        return all_products
    
    # Uncomment to execute the retrieval of all products (warning: this may take a long time)
    # all_products = fetch_all_products()
    
except requests.exceptions.HTTPError as err:
    print(f"Errore HTTP: {err}")
    if response.text:
        error_data = response.json()
        print(f"Stato: {error_data.get('status', 'sconosciuto')}")
        print(f"Messaggio: {error_data.get('message', 'nessun messaggio')}")
        
except requests.exceptions.RequestException as err:
    print(f"Errore durante la richiesta: {err}")
Esempio cURL
curl -X GET "https://api.commerceclarity.io/products/index?page=1" \
     -H "Authorization: Bearer IL_TUO_TOKEN_API" \
     -H "Accept: application/json"

Risorse Correlate

Autenticazione

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

Vai all'Autenticazione
Analisi Prodotti

Aggiungi nuovi prodotti al tuo inventario per poterne recuperare i dettagli.

Vedi Endpoint
Dettagli Prodotto

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

Vedi Endpoint