Passa al contenuto principale

Introduzione alle Commerce APIs

Le Commerce APIs di webround.com sono progettate per gestire la logica core degli e-commerce: dai cataloghi prodotti e inventario fino alla gestione del carrello e all'elaborazione degli ordini.

Tutte le Commerce APIs sono vincolate allo store-id e richiedono un'autenticazione di livello amministrativo o cliente a seconda del contesto.

Localizzazione e Traduzioni​

Per ogni entità che supporta più lingue (come Prodotti, Tag o Attributi), utilizziamo un oggetto dedicato chiamato translations. Questo ti permette di gestire contenuti localizzati in modo efficiente con una singola richiesta.

Per inviare le traduzioni, includi l'oggetto translations nel corpo della richiesta. Ogni chiave di questo oggetto deve essere un codice locale ISO valido (es. en, it, es), contenente i campi specifici per quella lingua.

I dati nella lingua di default devono essere forniti fuori dal campo translations, usando le chiavi di interesse. Ad esempio, supponiamo di modificare le versioni di un prodotto in inglese e spagnolo, usando la lingua italiana come default.

Esempio: Traduzione di un Prodotto​

{

    "name": "Nome del prodotto",
    "seoDescription": "Articolo di alta qualità",
    "translations": {
        "en": {
            "name": "Product Name",
            "seoDescription": "High quality item"
        },
        "es": {
            "name": "Nombre del producto",
            "seoDescription": "Articulo de alta calidad"
        }
    }
}

Collegamento Entità: Logica "Delete and Replace"​

Tutti gli endpoint dedicati alla sincronizzazione o alla sostituzione dei collegamenti tra entità (come collegare Asset e Tag ai Prodotti) seguono una rigida logica "Delete and Replace".

Ciò significa che l'array di ID che invii diventa la nuova fonte di verità. Il sistema non aggiunge dati in append; sovrascrive lo stato esistente.

Comportamenti Importanti:​

  • Resettare le Associazioni: Per rimuovere tutti i collegamenti esistenti (es. rimuovere tutti i tag da un prodotto), invia un array vuoto [].
  • Selezione Singola: Se invii un array con un solo ID ["uuid-1"], persisterà solo quel collegamento specifico. Qualsiasi altro collegamento precedentemente esistente verrà eliminato.
  • Estendere la Selezione: Se desideri aggiungere un nuovo collegamento mantenendo quelli esistenti, devi inviare l'intera lista di ID (quelli attuali + il nuovo).

Attenzione: Recupera sempre lo stato attuale dei collegamenti prima di eseguire una sincronizzazione se intendi preservare le associazioni esistenti.

Flusso di Gestione degli Asset​

È importante comprendere la distinzione tra l'archiviazione di un asset e il suo collegamento alle entità commerce:

  • Caricamento e Archiviazione: Per caricare fisicamente un file (immagine, video) su webround.com, devi utilizzare le Core APIs. Es: Carica un'immagine.
  • Collegamento: Una volta completato il caricamento e ottenuto un ID Asset valido, potrai utilizzare le Commerce APIs per creare un collegamento tra quell'Asset e un Prodotto o una Variante.

Un endpoint delle Commerce API non accetterà mai un file binario; gestisce solo la relazione tra un ID Asset esistente e i tuoi prodotti.

Principi Fondamentali​

  1. Header di scoping: Ogni richiesta deve includere gli header necessari (store-id) e i token di autenticazione.
  2. Consistenza: Utilizza gli endpoint Bulk per operazioni ad alto volume per ridurre al minimo il sovraccarico di rete.
  3. Integrità dei Dati: La validazione è applicata rigorosamente tramite schemi di validazione. Assicurati che i tuoi payload corrispondano ai DTO documentati per evitare errori 400 Bad Request.