API Prodotti

🤖 Spiega con l'intelligenza artificiale

L’API Prodotti è progettata per gestire i dati dei prodotti in modo efficiente all’interno di un ambiente e-commerce. Supporta la creazione, la modifica e l’eliminazione dei prodotti, gestendo i dettagli dei prezzi, le informazioni sulle scorte, le impostazioni di ricorrenza, le tasse e la gestione delle immagini.

L’API garantisce risposte chiare e coerenti, inclusa una gestione dettagliata degli errori e il supporto per più valute con una corretta validazione della precisione.

Creare un prodotto¶

Questo endpoint consente di creare un nuovo prodotto nel sistema inviando una richiesta POST con i dettagli del prodotto, come nome, descrizione, prezzo, valuta, scorte, tasse, immagini e impostazioni di ricorrenza.

Parametri di query:

Campi del corpo della richiesta:

Formato dell’oggetto di ricorrenza:

{
  "recurrence": "period",           // o "specific_billing_day"
  "duration_period": 1              // Valido: 1, 2, 3, 4, 6, 12 (mesi)
}

Oppure:

{
  "recurrence": "specific_billing_day",
  "payday": 15                       // Valido: 1-28
}

Parametri di caricamento file:

Richiesta:

curl -X POST 'https://api.4geeks.io/v1/products/?test=false' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -F 'name=Premium Widget' \
     -F 'description=This is a premium widget product' \
     -F 'price=99.99' \
     -F 'currency=USD' \
     -F 'stock=50' \
     -F 'is_physical=true' \
     -F 'taxes=1,3' \
     -F 'sku=PREMIUM-WIDGET-001' \
     -F 'image_default=@/path/to/image.jpg' \
     -F 'recurrence={"recurrence":"period","duration_period":3}'

Risposta (201 Created):

{
  "code": 201,
  "title": "Registrazione completata",
  "content": "La registrazione è stata completata con successo.",
  "type": "success",
  "data": {
    "id": "d36a4a5c-9fa9-4d55-b47f-4f1d50f2a180"
  }
}

Ottenere tutti i prodotti¶

Questo endpoint recupera un elenco paginato di tutti i prodotti con supporto per il filtraggio avanzato. Supporta paginazione, ricerca, filtraggio per tipo, intervallo di prezzo e livelli di scorte.

Parametri di query:

Richiesta:

curl -X GET 'https://api.4geeks.io/v1/products/?page=1&page_size=10&test=false' \
     -u 'sk_test_51O62xYzAbcDef123:'

Richiesta (Con filtri):

curl -X GET 'https://api.4geeks.io/v1/products/?page=1&search=widget&type=physical&price_min=10&price_max=100&stock_min=5' \
     -u 'sk_test_51O62xYzAbcDef123:'

Risposta (200 OK):

{
  "count": 25,
  "current_page": 1,
  "total_pages": 3,
  "results": [
    {
      "id": "a232cccc-956a-44ca-a2e8-d763afddc89f",
      "name": "Premium Widget",
      "short_description": "Widget di alta qualità",
      "description": "Questo è un prodotto widget premium con funzionalità avanzate",
      "stock": 50,
      "price": "99.99",
      "currency": "USD",
      "total_price": "109.99",
      "is_physical": true,
      "bar_code": "123456789012",
      "sku": "PREMIUM-WIDGET-001",
      "recurrence": {
        "recurrence": "period",
        "duration_period": 3
      },
      "images": {
        "default": "https://storage.googleapis.com/bucket/image-default.jpg",
        "additional_images": [
          {"image": "https://storage.googleapis.com/bucket/image-1.jpg"},
          {"image": "https://storage.googleapis.com/bucket/image-2.jpg"}
        ]
      },
      "payment_link": false,
      "created_on": "2025-12-04T10:30:00Z",
      "test": false,
      "taxes": [
        {"id": 1, "name": "IVA", "value": 10.0}
      ]
    }
  ]
}

Ottenere un prodotto specifico¶

Questo endpoint recupera i dettagli completi di un prodotto specifico tramite il suo ID univoco.

Parametri di percorso:

Parametri di query:

Richiesta:

curl -X GET 'https://api.4geeks.io/v1/products/f9b77185-a62e-4da9-a056-3c7b812ca334/?test=false' \
     -u 'sk_test_51O62xYzAbcDef123:'

Risposta (200 OK):

{
  "id": "f9b77185-a62e-4da9-a056-3c7b812ca334",
  "name": "Premium Widget",
  "short_description": "Widget di alta qualità",
  "description": "Questo è un prodotto widget premium con funzionalità avanzate",
  "stock": 50,
  "price": "99.99",
  "currency": "USD",
  "total_price": "109.99",
  "is_physical": true,
  "bar_code": "123456789012",
  "sku": "PREMIUM-WIDGET-001",
  "recurrence": {
    "recurrence": "period",
    "duration_period": 3
  },
  "images": {
    "default": "https://storage.googleapis.com/bucket/image-default.jpg",
    "additional_images": [
      {"image": "https://storage.googleapis.com/bucket/image-1.jpg"},
      {"image": "https://storage.googleapis.com/bucket/image-2.jpg"}
    ]
  },
  "payment_link": false,
  "created_on": "2025-12-04T10:30:00Z",
  "test": false,
  "taxes": [
    {"id": 1, "name": "IVA", "value": 10.0}
  ]
}

Aggiornare un prodotto¶

Aggiorna un prodotto esistente con nuovi dettagli. È possibile aggiornare i singoli campi senza influenzare gli altri.

Parametri di percorso:

Parametri di query:

Campi del corpo della richiesta (tutti opzionali):

Flag di gestione immagini:

Richiesta:

curl -X PUT 'https://api.4geeks.io/v1/products/f9b77185-a62e-4da9-a056-3c7b812ca334/?test=false' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -F 'name=Updated Widget Name' \
     -F 'description=Updated description' \
     -F 'price=79.99' \
     -F 'stock=100' \
     -F 'default=-1'

Risposta (200 OK):

{
  "code": 200,
  "title": "Prodotto aggiornato",
  "content": "Il prodotto è stato aggiornato con successo.",
  "type": "success",
  "data": {
    "id": "f9b77185-a62e-4da9-a056-3c7b812ca334",
    "name": "Updated Widget Name",
    "description": "Updated description",
    "price": "79.99",
    "stock": 100,
    "total_price": "87.99"
  }
}

Eliminare un prodotto¶

Elimina definitivamente un prodotto e lo disattiva.

Parametri di percorso:

Parametri di query:

Richiesta:

curl -X DELETE 'https://api.4geeks.io/v1/products/f9b77185-a62e-4da9-a056-3c7b812ca334/?test=false' \
     -u 'sk_test_51O62xYzAbcDef123:'

Risposta (200 OK):

{
  "code": 200,
  "title": "Prodotto eliminato",
  "content": "Il prodotto è stato eliminato con successo.",
  "type": "success"
}

Gestione degli errori¶

L’API restituisce codici di stato HTTP standard per indicare il successo o il fallimento di una richiesta. Di seguito sono riportati gli errori comuni specifici per i prodotti:

400 Bad Request¶

Si verifica quando la richiesta è malformata o contiene dati non validi.

Scenari:

Esempio di risposta di errore:

{
  "code": 400,
  "title": "Formato prezzo non valido",
  "content": "Errore di validazione del prezzo: JPY richiede 0 posizioni decimali. Per favore regola il prezzo in base ai requisiti della valuta.",
  "type": "danger"
}

401 Unauthorized¶

Autenticazione fallita. La chiave API non è valida, è mancante o è formattata male.

Esempio:

{
  "detail": "Le credenziali di autenticazione non sono state fornite."
}

Soluzione: - Verifica di aver incluso il parametro -u 'sk_test_...: o l’header Authorization: Basic - Assicurati che la tua chiave API sia corretta e attiva - Testa con Postman utilizzando Basic Auth

404 Not Found¶

Il prodotto richiesto non esiste.

Esempio:

{
  "code": 404,
  "title": "Il prodotto non esiste",
  "content": "L'id 'f9b77185-a62e-4da9-a056-3c7b812ca334' non corrisponde ad alcun prodotto",
  "type": "danger"
}

Soluzione: - Verifica che l’ID del prodotto esista - Usa l’endpoint di elenco per trovare l’ID prodotto corretto - Assicurati che il prodotto appartenga al tuo account sviluppatore

406 Not Acceptable¶

La richiesta viola le regole aziendali o i vincoli di validazione.

Esempio:

{
  "code": 406,
  "title": "Registrazione del prodotto fallita",
  "content": "Impossibile registrare il prodotto, per favore controlla: Valori dei campi non validi",
  "type": "danger"
}

Note importanti¶

Migliori pratiche¶

1. Valida i prezzi attentamente - Assicurati che i prezzi corrispondano ai requisiti delle posizioni decimali della valuta
2. Usa nomi descrittivi - Aiuta i clienti a comprendere chiaramente i prodotti
3. Imposta scorte accurate - Mantieni aggiornati i conteggi dell’inventario
4. Aggiungi immagini - Le immagini dei prodotti aumentano i tassi di conversione
5. Usa gli SKU - Gli SKU univoci aiutano nella gestione dell’inventario
6. Applica le tasse correttamente - Includi tutti gli ID delle tasse applicabili
7. Testa prima della produzione - Usa la modalità test con le chiavi API di test per la validazione
8. Usa la ricorrenza con saggezza - Imposta la ricorrenza solo per i prodotti idonei all’abbonamento

Risoluzione dei problemi¶

Problema: “Errore di validazione del prezzo: JPY richiede 0 posizioni decimali”¶

Causa: Utilizzo di posizioni decimali non supportate dalla valuta
Soluzione: - JPY: Usa numeri interi (senza decimali) - USD/EUR: Usa 2 posizioni decimali (99.99) - KWD: Usa 3 posizioni decimali (99.999)

Problema: “Il duration_period può contenere solo i seguenti valori 1, 2, 3, 4, 6, 12”¶

Causa: Periodo di ricorrenza non valido fornito
Soluzione: - Usa solo: 1 (mensile), 2 (bimestrale), 3 (trimestrale), 4 (quadrimestrale), 6 (semestrale) o 12 (annuale)

Problema: “Il payday deve essere maggiore di 0 e minore o uguale a 28”¶

Causa: Giorno di fatturazione non valido fornito
Soluzione: - Il giorno di paga deve essere compreso tra 1 e 28 - I giorni 29-31 non sono supportati per garantire la coerenza mensile

Problema: “Il prodotto non esiste”¶

Causa: L’ID del prodotto non esiste o appartiene a un diverso account sviluppatore
Soluzione: - Verifica l’ID del prodotto utilizzando l’endpoint di elenco - Assicurati di utilizzare la chiave API corretta - Controlla che il prodotto non sia stato eliminato

Problema: “Lo stato specificato non è valido”¶

Causa: Tipo di prodotto o valore di filtro non valido
Soluzione: - Usa valori di tipo validi: “physical” o “digital” - Assicurati che i parametri del filtro siano formattati correttamente

• Hai ancora domande? Richiedi supporto..
• Check out the changelog.