Esercitazione sull’estensione del metodo di spedizione

Vai a pipedream.com e accedi.

Fai clic su Nuovo flusso di lavoro (o Aggiungi flusso di lavoro).

Per il trigger, selezionare HTTP / Webhook.

Nella configurazione del trigger, imposta Risposta HTTP su Restituire una risposta personalizzata dal flusso di lavoro. Questo consente al passaggio Codice di inviare la risposta JSON fittizia.

Pipedream visualizza un URL endpoint HTTP univoco, ad esempio https://123456.m.pipedream.net.

Copia questo URL e utilizzalo come URL servizio durante la configurazione dell'estensione in Amministrazione Commerce.

{width="600" modal="regular"}

Fai clic sull'icona + per aggiungere un passaggio.

Scegli Esegui codice Node.js (passaggio codice).

Sostituisci il codice predefinito con il seguente JavaScript.

export default defineComponent({
async run({ steps, $ }) {
   const event = steps.trigger.event;
   const body = event.body ?? {};
   const headers = event.headers ?? {};
   const apiKey = headers["api-key"] ?? body.api_key ?? "";

   if (!apiKey || String(apiKey).trim() === "") {
      await $.respond({
      immediate: true,
      status: 401,
      headers: { "Content-Type": "application/json" },
      body: { error: "Missing or invalid API-Key header" },
      });
      return;
   }

   const shipment = body.shipment;
   if (!shipment || typeof shipment !== "object") {
      await $.respond({
      immediate: true,
      status: 400,
      headers: { "Content-Type": "application/json" },
      body: { error: "Missing or invalid shipment" },
      });
      return;
   }

   const rates = [
      {
      service_code: "mock_standard",
      service_name: "Mock Standard",
      carrier_friendly_name: "Mock Carrier",
      shipping_amount: { amount: 5.99 },
      shipment_cost: 5.99,
      cost: 5.99,
      },
      {
      service_code: "mock_express",
      service_name: "Mock Express",
      carrier_friendly_name: "Mock Carrier",
      shipping_amount: { amount: 12.99 },
      shipment_cost: 12.99,
      cost: 12.99,
      },
   ];

   await $.respond({
      immediate: true,
      status: 200,
      headers: { "Content-Type": "application/json" },
      body: { rates },
   });
},
});

Fare clic su Distribuisci.

{width="600" modal="regular"}

Passa alle impostazioni MCP nell’agente di codifica. Ad esempio, in Cursore, vai a Cursor > Settings > Cursor Settings > Tools & MCP. Verificare che il set di strumenti commerce-extensibility sia abilitato senza errori. Se vengono visualizzati degli errori, disattiva e attiva la serie di strumenti.

{width="600" modal="regular"}

Se hai aggiunto della documentazione al contesto del cursore, disattivala. Passa a Cursore > Impostazioni > Impostazioni cursore > Indicizzazione e documenti ed elimina la documentazione elencata.

{width="600" modal="regular"}

Concedi all’agente l’accesso alle specifiche API delle tariffe fittizie in modo che possa implementare correttamente il client. Se non lo hai già fatto, scarica il file delle specifiche API delle tariffe fittizie, aprilo e aggiungi il file .md al progetto (ad esempio docs/mock-rates-api-spec.md), quindi fai riferimento a tale file nel prompt.

Genera l'estensione del metodo di spedizione:

• Dalla finestra di chat dell'agente, selezionare la modalità Piano, se disponibile. Questo impedisce all'agente di procedere senza un piano.
• Immetti il seguente prompt:

Build an Adobe Commerce extension that adds a shipping method at checkout. The rates come from an external mock shipping rates service: the merchant configures the service's URL and API key in Admin, and at checkout the extension asks that service for rates and shows the returned options to the customer.

External service (mock shipping rates API):
- The service endpoint URL is configurable by the merchant (for example https://123456.m.pipedream.net).
- The API is specified in ./docs/mock-rates-api-spec.md.

The merchant must be able to configure the following in the Adobe Commerce Admin UI. Use the Adobe Commerce Admin UI SDK (or equivalent App Builder extensibility options for the Admin) to add a configuration screen where the merchant can set:
- The service URL (where the extension sends rate requests).
- An API key the service expects (any non-empty value for the mock). The API key is sensitive data: it must be stored securely and must never appear in logs, error messages, or in the UI in full (e.g. mask in the UI).
- The warehouse (ship-from) address: name, phone, street, city, state, postal code, country. This is the origin used when requesting rates.

{width="600" modal="regular"}

Rispondi alle domande dell'agente esattamente per aiutarlo a generare il codice migliore. Se l'agente richiede quale kit o modello utilizzare, indirizzarlo al kit di avvio per l'estrazione con il dominio di spedizione e l'estensione SDK dell'interfaccia utente amministratore in modo che sia il webhook di spedizione che la schermata di configurazione del commerciante siano implementati.

L'agente può creare un file requirements.md (o equivalente) che funge da fonte di verità per l'implementazione.

Esaminare il file requirements.md (o equivalente) e verificare il piano. Se tutto sembra corretto, indicare all'agente di passare alla pianificazione dell'architettura (o Fase 2). Conferma che:

• Un'azione shipping-methods (o equivalente) gestisce il webhook Commerce e chiama l'API delle tariffe esterne.
• Un'azione shipping-config (o equivalente) supporta GET (read config, API key masked) e SET (save service URL, API key, warehouse address), con la configurazione archiviata in modo sicuro, ad esempio nello stato di runtime.
• L'interfaccia utente amministratore include una scheda Spedizione fittizia (o simile) con campi per URL servizio, chiave API (password/mascherata) e indirizzo warehouse.

{width="600" modal="regular"}

Rivedi il piano dell’architettura quando l’agente lo fornisce.

{width="600" modal="regular"}

Indica all'agente di procedere con la generazione del codice. L'agente deve aggiungere un gestore fittizio alla configurazione dei gestori di spedizione che consenta a Commerce di accettare i metodi restituiti e utilizzare il metodo webhook plugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_rates (tipo webhook dopo, richiesto facoltativo).

L’agente genera il codice necessario e fornisce un riepilogo dettagliato dei passaggi successivi (tra cui l’installazione delle dipendenze, la registrazione del vettore fittizio, la configurazione del webhook di Commerce e la distribuzione).

{width="600" modal="regular"} {width="600" modal="regular"}

Dopo aver verificato il codice generato, distribuisci l’estensione utilizzando il seguente prompt:

Deploy the app.

L'agente esegue una valutazione di fattibilità pre-distribuzione (ad esempio, controllando .env per COMMERCE_WEBHOOKS_PUBLIC_KEY, COMMERCE_BASE_URL e variabili OAuth/IMS se viene utilizzata l'interfaccia utente di amministrazione o l'API Commerce).

{width="600" modal="regular"}

Quando sei sicuro dei risultati della valutazione, indica all’agente di procedere con la distribuzione. L’agente utilizza il toolkit MCP per verificare, generare e distribuire automaticamente.

{width="600" modal="regular"}

Registra il vettore fittizio in Commerce (eseguito una volta dopo la distribuzione):

npm run create-shipping-carriers

Verificare che .env disponga di COMMERCE_BASE_URL e di credenziali OAuth/IMS valide, in modo che lo script possa registrare il gestore.

Configura il webhook di spedizione in Commerce Admin:

• Vai a Archivi > Impostazioni > Configurazione > Servizi Adobe > Webhook Commerce.

• Aggiungi un webhook:

  • Metodo webhook: plugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_rates
  • Tipo webhook: dopo
  • URL: l'URL dell'azione Web shipping-methods distribuito (dall'output di distribuzione o da Adobe Developer Console).
  • Obbligatorio: Facoltativo - Questo consente il funzionamento dell'estrazione se l'API esterna non restituisce tariffe.

{width="600" modal="regular"}

Configura l'estensione Admin UI SDK:

• In Commerce Admin, vai a Archivi > Impostazioni > Configurazione.
• Apri Adobe Services > Interfaccia utente amministratore SDK.
• Imposta Abilita SDK dell'interfaccia utente amministratore su Sì e fai clic su Salva configurazione se non è già abilitata.
• Fai clic su Configura estensioni, scegli l'area di lavoro a cui è distribuita l'app, quindi fai clic su Applica. È inoltre possibile selezionare l'opzione Personalizzato e immettere il nome dell'area di lavoro.
• Seleziona l'app App Builder nell'elenco e salva. Se l'app non viene visualizzata, fare clic su Aggiorna registrazioni e riprovare.

{width="600" modal="regular"}

Configurare il metodo di spedizione fittizio nell'interfaccia utente di amministrazione di Adobe Commerce:

• Apri App e seleziona la tua app.

• Apri la scheda Spedizione fittizia (o equivalente).

• Immetti i seguenti dettagli:

  • URL servizio: l'URL del flusso di lavoro Pipedream copiato, ad esempio https://123456.m.pipedream.net.
  • Chiave API: qualsiasi valore non vuoto per il modello, ad esempio tutorial-key.
  • Indirizzo del magazzino (origine spedizione): nome, telefono, via, città, stato, codice postale, paese.

• Fai clic su Salva. La configurazione viene archiviata nello stato Runtime e utilizzata dall'azione metodi di spedizione.

{width="600" modal="regular"}

Verifica al momento dell'estrazione: Aggiungere un prodotto al carrello, passare all'estrazione e immettere un indirizzo di spedizione. Dovresti visualizzare le opzioni di spedizione fittizie, ad esempio Mock Standard e Mock Express.

{width="600" modal="regular"}