Come effettuare un ordine utilizzando un prodotto personalizzato

Questa guida ti accompagnerà nel processo di effettuare un ordine utilizzando un prodotto cliente tramite l'API GelatoConnect. I prodotti cliente ti permettono di utilizzare le tue configurazioni di prodotto quando effettui ordini, semplificando il processo d'ordine e garantendo coerenza con le tue definizioni di prodotto interne.

Endpoint API

POST https://order.ie.live.gelato.tech/api/v4/orders

Struttura della richiesta

Gli elementi chiave per utilizzare un prodotto cliente nel tuo ordine sono i campi productName e productVariant all'interno dell'array items. Ecco un esempio di struttura della richiesta:

{
    "clientId": "your-client-id",
    "orderReferenceId": "your-order-reference",
    "customerReferenceId": "your-customer-reference",
    "orderType": "order",
    "currency": "USD",
    "retailCurrency": "USD",
    "retailShippingPriceInclVat": 5.99,
    "shippingAddress": {
        "country": "US",
        "firstName": "John",
        "lastName": "Doe",
        "addressLine1": "123 Main St",
        "city": "Anytown",
        "postCode": "12345",
        "state": "CA",
        "email": "[email protected]",
        "phone": "1234567890"
    },
    "items": [
        {
            "itemReferenceId": "your-item-reference",
            "productName": "sample for order intake",
            "productVariant": {
                "paper": "a1",
                "color": "front"
            },
            "files": [
                {
                    "type": "default",
                    "url": "https://example.com/your-file.pdf"
                }
            ],
            "quantity": 1,
            "retailPriceInclVat": 79.99
        }
    ]
}

Campi chiave per i prodotti del cliente

Quando usi un prodotto personalizzato, presta particolare attenzione a questi campi nell'array items:

productName: deve corrispondere al nome del tuo prodotto cliente come definito in GelatoConnect.
productVariant: questo oggetto contiene le opzioni specifiche per il tuo prodotto. Le chiavi e i valori devono corrispondere alle opzioni variante che hai configurato per il tuo prodotto cliente.

Nell'esempio sopra:

"productName": "sample for order intake",
"productVariant": {
    "paper": "a1",
    "color": "front"
}

Questa configurazione indica a GelatoConnect di utilizzare il prodotto cliente denominato "sample for order intake" con le opzioni di carta e colore specificate.

Note importanti

Quando usi un prodotto personalizzato, non è necessario fornire un productUid per l'articolo. I campi productName e productVariant vengono utilizzati invece per determinare la configurazione esatta del prodotto.
Assicurati che il productName corrisponda esattamente al nome del tuo prodotto cliente in GelatoConnect.
L'oggetto productVariant deve includere solo le opzioni che hai definito per il tuo prodotto cliente. L'inclusione di opzioni non definite genererà un errore.
La struttura della richiesta dell'ordine rimane uguale a quella di un ordine standard. Puoi includere più articoli, ciascuno utilizzando un prodotto personalizzato diverso se necessario.
Assicurati sempre che i file che fornisci corrispondano ai requisiti della configurazione del tuo prodotto cliente.

Risposta

Dopo aver effettuato un ordine con successo, riceverai una risposta che include i dettagli dell'ordine, tra cui un ID ordine, lo stato di realizzazione e altro ancora. Controlla sempre la risposta per assicurarti che il tuo ordine sia stato elaborato correttamente.

Risoluzione dei problemi

Se riscontri problemi quando effettui un ordine con un prodotto personalizzato, controlla quanto segue:

Verifica che il productName corrisponda esattamente al nome del tuo prodotto cliente.
Assicurati che tutte le opzioni productVariant richieste siano fornite e corrispondano alla configurazione del tuo Customer Product.
Verifica che i file forniti soddisfino i requisiti del tuo prodotto cliente.
Verifica che le tue credenziali API siano corrette e che tu abbia l'autorizzazione per utilizzare il prodotto cliente specificato.

[Order Intake - GCW] Effettuare un ordine utilizzando Customer Product