Vai al contenuto principale

[Acquisizione ordini - GCW] Guida di riferimento al payload dell'evento di postback

T
Scritto da Toby Dawson
Aggiornato oltre 3 settimane fa

Questa guida offre una panoramica completa di tutti i campi dati disponibili nel payload per i diversi eventi di attivazione postback in GelatoConnect. Capire questi payload è fondamentale per creare template efficaci che ti permettono di ottenere le informazioni di cui hai bisogno.

Introduzione

Quando viene attivato un evento di postback in GelatoConnect, un payload JSON con i dati specifici dell’evento viene inviato al tuo endpoint configurato o utilizzato nelle notifiche email. Questo documento spiega la struttura e il contenuto di questi payload per ogni tipo di evento, così puoi capire quali dati sono disponibili quando crei i tuoi template.

Indice dei contenuti

Stato del pacco aggiornato

Questo payload viene ricevuto quando lo stato di un pacco cambia all'interno del sistema.

{ "customer": { "id": "ea004496-8a31-42b7-b38a-77791152dbc7", "name": "Test Cliente", "referenceId": "test-customer" }, "order": { "id": "ceebe91a-42e1-41ae-afdf-64569384f9bc", "referenceId": "Ordine-di-test", "metadata": { "isRush": "Falso" } }, "package": { "id": "reference_package_id", "items": [ { "id": "1614240f-3d24-4d44-b632-b1bd91b1981c", "quantity": 1, "referenceId": "product_18_reference_id", "metadata": { "item-type": "prodotto", "sku": "product_18_reference_id" } } ], "status": "spedito", "peso": 9 }, "spedizione": { "fulfillmentLocation": { "country": "US", "stateProvince": "Wyoming" }, "method": { "id": "shipping_method_id", "name": "Nome metodo di spedizione" }, "tracking": { "code": "tracking_order_us", "url": "http://tracking.com/order_us" } }}

Dati fondamentali

  • customer: Contiene le informazioni del cliente, come ID, nome e ID di riferimento

  • order: informazioni di base sull’ordine e qualsiasi metadato personalizzato

  • package: dettagli sul pacco, come stato, peso e articoli

  • shipment: Dettagli di spedizione come luogo, metodo e informazioni di tracciamento

Ordine in ritardo

Ricevi questo payload quando gli ordini sono in ritardo rispetto alla data prevista di spedizione.

{ "currentDate": "29/11/2024 15:55:12", "customerId": "9290728b-8534-4227-a191-8036eed9f060", "orders": [ { "orderId": "0743ce64d7_test_order_6", "orderReferenceId": "G-231211113145", "expectedDispatchDate": "30/09/2024" }, { "orderId": "0743ce64d7_test_order_128", "orderReferenceId": "G-231211113145", "expectedDispatchDate": "13/11/2024" } ]}

Campi dati principali

  • currentDate: data e ora attuali del sistema al momento in cui è stato rilevato il ritardo

  • customerId: ID del cliente collegato agli ordini in ritardo

  • orders: elenco di ordini in ritardo, ognuno contiene:

    • orderId: ID ordine interno di GelatoConnect

    • orderReferenceId: il tuo ID di riferimento per l'ordine

    • expectedDispatchDate: La data di spedizione prevista che non è stata rispettata

Ordine annullato

Questo payload viene ricevuto quando un ordine viene annullato.

{ "created": "03/08/2018 07:26:52", "orderId": "a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9", "orderReferenceId": "J123X456", "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0", "fulfillmentStatus": "annullato", "channel": "api", "comment": "Ordine annullato con successo", "items": [ { "itemReferenceId": "123", "fulfillmentStatus": "annullato", "metadata": { "item-type": "prodotto", "sku": "123" } } ], "metadata": { "isRush": "Falso" }}

Campi dati principali

  • created: data e ora in cui è avvenuta la cancellazione

  • orderId: ID ordine interno di GelatoConnect

  • orderReferenceId: Il tuo ID di riferimento per l’ordine

  • customerReferenceId: ID di riferimento per il cliente

  • fulfillmentStatus: Stato attuale ("annullato")

  • comment: Informazioni sul motivo o sulle modalità di cancellazione dell'ordine

  • items: elenco degli articoli nell’ordine, ognuno con il proprio stato e le relative informazioni

  • metadata: metadati personalizzati a livello di ordine

Ordine consegnato

Questo payload viene ricevuto quando un ordine è stato consegnato al destinatario.

{ "created": "03/08/2018 07:26:52", "fulfillmentStatus": "consegnato", "orderReferenceId": "ASD4124123", "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0", "channel": "api", "comment": "", "items": [ { "itemReferenceId": "123", "fulfillmentStatus": "consegnato", "realizzazioni": [ { "trackingCode": "code123", "trackingUrl": "http://example.com/tracking?code=code123", "shipmentMethodName": "DHL Express Domestic BR", "shipmentMethodUid": "dhl_express_domestic_br", "fulfillmentCountry": "BR", "fulfillmentStateProvince": "SP", "deliveryDate": "05/08/2018 10:15", "recipientName": "John Doe", "recipientSignature": "signature_image_url" }, { "trackingCode": "code234", "trackingUrl": "http://example.com/tracking?code=code234", "shipmentMethodName": "DHL Express Domestic BR", "shipmentMethodUid": "dhl_express_domestic_br", "fulfillmentCountry": "BR", "fulfillmentStateProvince": "SP", "deliveryDate": "05/08/2018 10:30", "recipientName": "Jane Smith", "recipientSignature": "signature_image_url_2" } ], "metadata": { "item-type": "prodotto", "sku": "123" } } ], "metadata": { "isRush": "Falso" }}

Dati fondamentali

  • created: data e ora in cui è avvenuta la consegna

  • fulfillmentStatus: Stato attuale ("consegnato")

  • orderReferenceId: Il tuo ID di riferimento per l’ordine

  • items: elenco degli articoli nell’ordine, ognuno con:

    • fulfillments: informazioni dettagliate sulla consegna, tra cui:

      • trackingCode e trackingUrl: informazioni di tracciamento

      • shipmentMethodName: nome del corriere

      • deliveryDate: Quando l'articolo è stato consegnato

      • recipientName: Chi ha ricevuto il pacco

      • recipientSignature: URL di un'immagine della firma (se disponibile)

Ordine non riuscito

Questo payload viene ricevuto quando un ordine non supera la validazione o l'elaborazione.

{ "created": "03/08/2018 07:26:52", "orderId": "a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9", "orderReferenceId": "J123X456", "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0", "fulfillmentStatus": "non riuscita", "channel": "api", "comment": "Invio dell'ordine non riuscito", "items": [ { "itemReferenceId": 123, "fulfillmentStatus": "non riuscito", "metadata": { "item-type": "prodotto", "sku": "123" } } ], "metadata": { "isRush": "Falso" }}

Dati fondamentali

  • created: data e ora in cui si è verificato il problema

  • orderId: ID ordine interno di GelatoConnect

  • orderReferenceId: Il tuo ID di riferimento per l’ordine

  • fulfillmentStatus: stato attuale ("non riuscito")

  • comment: Informazioni sul motivo per cui l'ordine non è andato a buon fine

  • items: elenco degli articoli nell’ordine, ognuno con il proprio stato e metadati

Ordine in transito

Questo payload viene ricevuto quando un ordine è in viaggio verso il destinatario.

{ "created": "17/09/2018 10:26:52", "fulfillmentStatus": "in_transito", "orderReferenceId": "J123X456", "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0", "channel": "api", "comment": "Ordine in transito", "items": [ { "itemReferenceId": "123", "fulfillmentStatus": "in_transit", "realizzazioni": [ { "trackingCode": "code567", "trackingUrl": "http://example.com/tracking?code=code567", "shipmentMethodName": "DHL Express Domestic BR", "shipmentMethodUid": "dhl_express_domestic_br", "fulfillmentCountry": "BR", "fulfillmentStateProvince": "SP" } ] } ]}

Dati fondamentali

  • created: data e ora in cui lo stato dell'ordine è passato a "in transito"

  • fulfillmentStatus: stato attuale ("in_transit")

  • orderReferenceId: il tuo ID di riferimento per l’ordine

  • items: elenco degli articoli nell’ordine, ognuno contiene:

    • realizzazioni: informazioni sulla spedizione, tra cui:

      • trackingCode e trackingUrl: informazioni di tracciamento

      • shipmentMethodName: Nome del corriere

      • fulfillmentCountry e fulfillmentStateProvince: informazioni sull'origine

Ordine pronto

Questo payload viene ricevuto quando un ordine è stato stampato o prodotto, ma non è ancora stato spedito.

{ "created": "03/08/2018 07:26:52", "orderId": "a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9", "orderReferenceId": "J123X456", "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0", "fulfillmentStatus": "stampato", "channel": "api", "comment": "Ordine stampato con successo", "items": [ { "itemReferenceId": "123", "fulfillmentStatus": "stampato", "metadata": { "item-type": "prodotto", "sku": "123" } } ], "metadata": { "isRush": "Falso" }}

Dati fondamentali

  • created: data e ora in cui l’ordine è stato realizzato

  • orderId: ID ordine interno di GelatoConnect

  • orderReferenceId: Il tuo ID di riferimento per l'ordine

  • fulfillmentStatus: Stato attuale ("stampato")

  • comment: Informazioni sulla realizzazione

  • items: elenco degli articoli nell’ordine, ognuno con il proprio stato e metadati

Ordine ricevuto

Questo payload viene ricevuto quando un ordine è stato ricevuto e validato con successo nel sistema.

{ "created": "03/08/2018 07:26:52", "orderId": "a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9", "orderReferenceId": "ASD4124123", "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0", "fulfillmentStatus": "completato", "channel": "api", "comment": "Ordine completato con successo", "items": [ { "itemReferenceId": "123", "fulfillmentStatus": "completato", "metadata": { "item-type": "prodotto", "sku": "123" } } ], "metadata": { "isRush": "Falso" }}

Dati fondamentali

  • created: data e ora in cui l’ordine è stato ricevuto

  • orderId: ID ordine interno di GelatoConnect

  • orderReferenceId: Il tuo ID di riferimento per l’ordine

  • fulfillmentStatus: stato attuale ("passato")

  • comment: Informazioni sulla validazione

  • items: elenco degli articoli nell’ordine, ognuno con il proprio stato e le sue informazioni

Ordine restituito

Ricevi questo payload quando un ordine viene restituito al mittente.

{ "created": "03/08/2018 07:26:52", "fulfillmentStatus": "reso", "orderReferenceId": "ASD4124123", "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0", "channel": "api", "comment": "Reso dell'ordine completato con successo", "items": [ { "itemReferenceId": "123", "fulfillmentStatus": "reso", "realizzazioni": [ { "trackingCode": "code123", "trackingUrl": "http://example.com/tracking?code=code123", "shipmentMethodName": "DHL Express Domestic BR", "shipmentMethodUid": "dhl_express_domestic_br", "fulfillmentCountry": "BR", "fulfillmentStateProvince": "SP" }, { "trackingCode": "code234", "trackingUrl": "http://example.com/tracking?code=code234", "shipmentMethodName": "DHL Express Domestic BR", "shipmentMethodUid": "dhl_express_domestic_br", "fulfillmentCountry": "BR", "fulfillmentStateProvince": "SP" } ], "metadata": { "item-type": "prodotto", "sku": "123" } } ], "metadata": { "isRush": "Falso" }}

Campi dati principali

  • created: data e ora in cui il reso è stato gestito

  • fulfillmentStatus: Stato attuale ("reso")

  • orderReferenceId: Il tuo ID di riferimento per l'ordine

  • items: elenco degli articoli nell'ordine, ognuno contiene:

    • realizzazioni: restituisci le informazioni sulla spedizione di ritorno, tra cui:

      • trackingCode e trackingUrl: informazioni di tracciamento

      • shipmentMethodName: Nome del corriere

      • fulfillmentCountry e fulfillmentStateProvince: informazioni sull'origine

Ordine spedito

Questo payload viene ricevuto quando un ordine è stato spedito al destinatario.

{ "created": "03/08/2018 07:26:52", "fulfillmentStatus": "spedito", "orderReferenceId": "ASD4124123", "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0", "channel": "api", "comment": "Ordine spedito con successo", "items": [ { "itemReferenceId": "123", "fulfillmentStatus": "spedito", "realizzazioni": [ { "trackingCode": "code123", "trackingUrl": "http://example.com/tracking?code=code123", "shipmentMethodName": "DHL Express Domestic BR", "shipmentMethodUid": "dhl_express_domestic_br", "fulfillmentCountry": "BR", "fulfillmentStateProvince": "SP" }, { "trackingCode": "code234", "trackingUrl": "http://example.com/tracking?code=code234", "shipmentMethodName": "DHL Express Domestic BR", "shipmentMethodUid": "dhl_express_domestic_br", "fulfillmentCountry": "BR", "fulfillmentStateProvince": "SP" } ], "metadata": { "item-type": "prodotto", "sku": "123" } } ], "metadata": { "isRush": "Falso" }}

Campi dati principali

  • created: data e ora in cui l’ordine è stato spedito

  • fulfillmentStatus: Stato attuale ("spedito")

  • orderReferenceId: Il tuo ID di riferimento per l'ordine

  • items: elenco degli articoli nell'ordine, ognuno contiene:

    • realizzazioni: informazioni sulla spedizione, tra cui:

      • trackingCode e trackingUrl: informazioni di tracciamento

      • shipmentMethodName: Nome del corriere

      • fulfillmentCountry e fulfillmentStateProvince: informazioni sull'origine

Lavorare con i metadati

Molti dei payload degli eventi includono metadati sia a livello di ordine che di articolo. Questi metadati contengono coppie chiave-valore personalizzate che puoi definire quando invii gli ordini e che vengono poi incluse negli eventi di postback.

Esempi di utilizzo dei metadati:

  1. Metadati a livello di ordine: metadata.isRush con valore "False"

  2. Metadati a livello di articolo: items[0].metadata.item-type con valore "product"

  3. Metadati a livello di articolo: items[0].metadata.sku con valore "123"

Questi metadati possono essere usati per aggiungere informazioni extra che non fanno parte dei campi standard, come ad esempio flag di priorità, SKU, categorie o qualsiasi altro dato utile per la realizzazione e la gestione degli ordini.

Come usare questi payload nei template

Quando crei modelli per i postback, puoi richiamare qualsiasi campo in questi payload usando il linguaggio di template Jinja2. Ad esempio:

  • Per accedere all'ID di riferimento dell'ordine: ####{{ orderReferenceId }}

  • Per accedere a un codice di tracciamento: ####{{ items[0].fulfillments[0].trackingCode }}

  • Per accedere ai metadati personalizzati: ####{{ metadata.isRush }}

Per saperne di più su come creare template, dai un'occhiata a Creare template per la ricezione degli ordini e a Esempi di Template Mapper.

Per saperne di più su come configurare i postback, dai un'occhiata a Come configurare i postback.

Articoli correlati
[Gestione degli ordini - GCW] Come impostare i postback?
[Acquisizione ordini - GCW] Documentazione API per la gestione degli ordini
[Acquisizione ordini - GCW] esempi di Template Mapper
[Gestione degli ordini - GCW] lavorare con gli endpoint API degli ordini
[Gestione degli ordini - GCW] Creare template per la gestione degli ordini
Hai ricevuto la risposta alla tua domanda?