Se stai cercando di semplificare i tuoi flussi di lavoro in Shopify, l’app Mechanic è uno strumento indispensabile.
Consente agli sviluppatori di automatizzare attività, risparmiando tempo e semplificando operazioni. Mechanic mette a disposizione una intera library di task pre-compilati, ma spesso noi la utilizziamo per implementare logiche custom. Quando si integrano API esterne, è fondamentale strutturare correttamente i task per gestire richieste asincrone, garantire la rilevazione degli ambiti API e seguire le best practice per una maggiore affidabilità e mantenibilità.
In questo articolo, ti mostro come abbiamo costruito un task Mechanic che recupera gli ID dei punti di ritiro Poste Italiane da ShippyPro, una piattaforma avanzata di spedizioni e logistica—e li salva come metafield negli ordini Shopify.
Cosa fa questo task
Quando i clienti selezionano l'opzione ritiro locale su Shopify, l'ID del punto di ritiro non viene salvato automaticamente nei dettagli dell'ordine. Questo era un problema per uno dei nostri clienti, che aveva bisogno di integrare ShippyPro per gestire in modo più efficiente le consegne.
ShippyPro è una piattaforma premium che si integra con vari corrieri, fornendo strumenti per automatizzare le spedizioni, il tracciamento e la gestione dei punti di ritiro. Utilizzando una delle loro API premium, possiamo recuperare l'ID corretto del punto di ritiro per un ordine e salvarlo nei metafield di Shopify.
Anche se ShippyPro e Shopify offrono un'integrazione nativa, a causa della struttura ERP del nostro cliente, gli ordini vengono trasmessi da Shopify a ShippyPro tramite API, anziché attraverso l'integrazione standard. Questa soluzione personalizzata garantisce che gli ordini rispettino la logica aziendale dell'ERP, pur beneficiando delle funzionalità avanzate di ShippyPro.
Funzionamento del task Mechanic
Ecco a grandi linee come funziona il nostro task Mechanic:
-
Monitoraggio degli ordini: il task monitora i nuovi ordini Shopify con un metodo di spedizione specifico per il ritiro locale.
-
Chiamata API a ShippyPro: effettua una richiesta a ShippyPro per recuperare i punti di ritiro disponibili.
-
Salvataggio dell'ID del punto di ritiro: se un punto di ritiro corrisponde alla selezione del cliente, l'ID viene salvato nei metafield dell'ordine.
Lezioni apprese dall'implementazione
Durante la creazione di questo task, abbiamo imparato molto su come lavorare con API esterne tramite Mechanic, in particolare riguardo alla gestione delle risposte asincrone e la corretta rilevazione degli ambiti API. Vediamo alcune delle lezioni più importanti.
Gestire gli scope API in Mechanic: Il Ruolo delle Anteprime degli Eventi
Uno degli ostacoli principali nella creazione di task in Mechanic è garantire che l’attività abbia gli scope API corretti per eseguire determinate azioni. Shopify richiede che le app dichiarino questi ambiti al momento dell’installazione, e Mechanic li rileva analizzando il codice dell’attività prima dell’esecuzione.
Tuttavia, c'è una sfida quando la mutazione GraphQL (come metafieldsSet) viene eseguita solo in particolari condizioni. Se queste condizioni non vengono soddisfatte durante l'anteprima, Mechanic potrebbe non riconoscere che l’attività necessita di accesso in scrittura ai metafield. Questo può portare al fallimento del task durante l’esecuzione reale, poiché i permessi necessari non sono stati concessi al momento dell’installazione.
Per risolvere questo problema, abbiamo sfruttato il concetto di anteprime degli eventi. Durante la modalità anteprima, abbiamo fornito dei dati fittizi per assicurarsi che la mutazione metafieldsSet venisse eseguita anche in fase di test, facendo sì che Mechanic riconoscesse la necessità di accesso ai permessi write_orders prima dell’esecuzione effettiva.
Ecco il codice che abbiamo utilizzato:
{% if event.preview %}
{% action "shopify" %}
mutation {
metafieldsSet(
metafields: [
{
ownerId: "gid://shopify/Order/6483826147655",
namespace: "custom",
key: "dropoff_point_id",
type: "single_line_text_field",
value: "1234"
}
]
) {
metafields {
id
}
userErrors {
message
}
}
}
{% endaction %}
{% endif %}
In questo modo, siamo riusciti a garantire che gli ambiti API necessari venissero rilevati correttamente, evitando errori durante l'esecuzione del task e migliorando l'affidabilità dell'integrazione.
Come lavorare con API esterne e Mechanic
Poiché le operazioni in Mechanic sono eseguite in modo asincrono, i risultati delle chiamate API non sono immediatamente disponibili all'interno del task Liquid che le ha avviate. Per gestire questa situazione, Mechanic offre un approccio strutturato utilizzando l’event subscription mechanic/actions/perform, che consente di proseguire l’elaborazione in base ai risultati del task precedente.
Per garantire continuità tra i passaggi, usiamo il parametro meta per passare ulteriori informazioni dal primo evento al secondo, come l'order_id e l'indirizzo di spedizione, consentendo al secondo evento di mappare correttamente la risposta API all’ordine originale.
Il flusso è il seguente:
-
Primo evento (shopify/orders/create):
-
Alla creazione dell'ordine, con GraphQL recuperare le informazioni necessarie dall'ordine.
-
HTTP request all'API di ShippyPro, passando parametri extra con
meta
-
-
Secondo events (
mechanic/actions/perform):-
Ricevi la risposta dell'API ShippyPro
-
Fai le operazioni necessarie su questa risposta
-
GraphQL mutation usando la mutation metafieldsSet (e.g., update order metafields)
-
{% if event.topic == "shopify/orders/create" or event.topic == "mechanic/user/order" %}
{% capture query %}
{% comment %}
Build your query here
{% endcomment %}
{% endcapture %}
{% assign result = query | shopify %}
{% assign order = result.data.order %} {% assign shipping_address = order.shippingAddress %}
{% if shipping_address %}
{% assign shipping_method = order.shippingLines.edges[0].node.title %}
{% if shipping_method == shipping_point_method %}
{% capture parameters %}
{
"Method": "GetDropOffPoints",
"Params": {
"city": {{ shipping_address.city | json }},
"zip": {{ shipping_address.zip | json }},
"country": "IT",
"couriers": ["CourierName"]
}
}
{% endcapture %}
{% action "http" %}
{
"method": "GET",
"url": {{ endpoint | json }},
"headers": {
"Authorization": {{ ENCODED_API_TOKEN | json }},
"Content-Type": "application/json"
},
"body": {{ parameters | json }},
"meta": {
"order_id": {{ order.id | json }},
"order_shipping_address": {{ shipping_address.address1 | json }}
}
}
{% endaction %}
{% endif %}
{% endif %}
{% elsif event.topic == "mechanic/actions/perform" %}
{% if action.type == "http" %}
{% assign response = action.run.result.body %}
{% assign order_id = action.options.meta.order_id %}
{% assign order_address = action.options.meta.order_shipping_address %}
{% if matching_point_id %}
{% action "shopify" %}
mutation {
metafieldsSet(
metafields: [
{
ownerId: {{ order_id | json }},
namespace: "custom",
key: "dropoff_point_id",
type: "single_line_text_field",
value: {{ matching_point_id | json }}
}
]
) {
metafields {
id
}
userErrors {
message
}
}
}
{% endaction %}
{% endif %}
{% endif %}
Conclusione
Strutturare correttamente i task Mechanic che interagiscono con API esterne consente di creare automazioni potenti e affidabili. Con questa soluzione, gli ordini con ritiro locale vengono associati al punto di ritiro corretto tramite l'API di ShippyPro, migliorando l'efficienza logistica e garantendo un flusso di lavoro senza interruzioni.
Se vuoi saperne di più su come lavorare con Mechanic e le API esterne, dai un’occhiata alla documentazione ufficiale della app.
