Tutorial de extensión de métodos de envío

Vaya a pipedream.com y regístrese o inicie sesión.

Haga clic en Nuevo flujo de trabajo (o Agregar flujo de trabajo).

Para el déclencheur, seleccione HTTP / Webhook.

En la configuración de déclencheur, establezca Respuesta HTTP en Devolver una respuesta personalizada de su flujo de trabajo. Esto permite que el paso Código envíe la respuesta JSON de prueba.

Pipedream muestra una dirección URL de extremo HTTP única, como https://123456.m.pipedream.net.

Copie esta dirección URL y utilícela como la URL de servicio al configurar la extensión en el administrador de Commerce.

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

Haga clic en el icono + para agregar un paso.

Elija Ejecutar código de Node.js (Paso de código).

Reemplazar el código predeterminado con el siguiente 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 },
   });
},
});

Haga clic en Implementar.

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

Vaya a la configuración de MCP del agente de codificación. Por ejemplo, en Cursor, vaya a Cursor > Settings > Cursor Settings > Tools & MCP. Compruebe que el conjunto de herramientas commerce-extensibility esté habilitado sin errores. Si hay errores, active o desactive el conjunto de herramientas.

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

Si se ha añadido documentación al contexto del cursor, desactívela. Vaya a Cursor > Configuración > Configuración del cursor > Indexación y documentos y elimine cualquier documentación enumerada.

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

Proporcione al agente acceso a la especificación de API de tasas de prueba, para que pueda implementar el cliente correctamente. Si aún no lo ha hecho, descargue el archivo de especificación de API de tasas de prueba, ábralo y agregue el archivo .md a su proyecto (por ejemplo, docs/mock-rates-api-spec.md) y, a continuación, haga referencia a ese archivo en su solicitud.

Generar la extensión del método de envío:

• En la ventana de chat del agente, seleccione el modo Plan, si está disponible. Esto evita que el agente continúe sin un plan.
• Introduzca la siguiente solicitud:

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"}

Responda las preguntas del agente con precisión para ayudarle a generar el mejor código. Si el agente pregunta qué kit o plantilla usar, diríjalo al kit de inicio de cierre de compra con el dominio de envío y la extensión SDK de la IU de administración para que se implementen tanto el webhook de envío como la pantalla de configuración del comerciante.

El agente puede crear un archivo de requirements.md (o equivalente) que sirva como fuente fiable para la implementación.

Revise el archivo requirements.md (o equivalente) y compruebe el plan. Si todo parece correcto, indique al agente que pase a la planificación de la arquitectura (o Fase 2). Confirme que:

• Una acción shipping-methods (o equivalente) administra el webhook de Commerce y llama a la API de tarifas externas.
• Una acción shipping-config (o equivalente) es compatible con GET (leer configuración, clave de API enmascarada) y SET (guardar URL del servicio, clave de API, dirección de almacén), con una configuración almacenada de forma segura, por ejemplo, en el estado de tiempo de ejecución.
• La IU de administración incluye una ficha Envío ficticio (o similar) con campos para la URL del servicio, la clave de API (contraseña/enmascarada) y la dirección del almacén.

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

Revise el plan de arquitectura cuando el agente se lo proporcione.

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

Indique al agente que continúe con la generación de código. El agente debe agregar un transportista mock a la configuración de los transportistas de envío para permitir que Commerce acepte los métodos devueltos y utilice el método de gancho web plugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_rates (tipo de gancho web after, obligatorio Opcional).

El agente genera el código necesario y proporciona un resumen detallado de los pasos siguientes (incluyendo la instalación de dependencias, el registro del operador de prueba, la configuración del webhook de Commerce y el despliegue).

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

Después de verificar el código generado, implemente la extensión mediante el siguiente mensaje:

Deploy the app.

El agente realiza una evaluación de la preparación previa al despliegue (por ejemplo, comprobando .env para las variables COMMERCE_WEBHOOKS_PUBLIC_KEY, COMMERCE_BASE_URL y OAuth/IMS si se utiliza la IU de administración o la API de Commerce).

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

Cuando confíe en los resultados de la evaluación, indique al agente que continúe con el despliegue. El agente utiliza el kit de herramientas de MCP para verificar, crear e implementar automáticamente.

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

Registrar el operador ficticio en Commerce (ejecutar una vez después de la implementación):

npm run create-shipping-carriers

Asegúrese de que .env tenga COMMERCE_BASE_URL y credenciales de OAuth/IMS válidas para que el script pueda registrar al operador.

Configurar el webhook de envío en Commerce Admin:

• Vaya a Tiendas > Configuración > Configuración > Servicios de Adobe > Webhooks de Commerce.

• Añadir un webhook:

  • Método webhook: plugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_rates
  • Tipo de webhook: después de
  • URL: la URL de acción web shipping-methods implementada (desde la salida de implementación o Adobe Developer Console).
  • Obligatorio: Opcional: esto permite que el cierre de compra siga funcionando si la API externa no devuelve tasas.

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

Configurar la extensión Admin UI SDK:

• En Commerce Admin, vaya a Tiendas > Configuración > Configuración.
• Abra Servicios de Adobe > IU de administración de SDK.
• Establezca Habilitar la IU de administración de SDK en Sí y haga clic en Guardar configuración si aún no está habilitada.
• Haga clic en Configurar extensiones, elija el área de trabajo en la que se ha implementado la aplicación y, a continuación, haga clic en Aplicar. También puede seleccionar la opción Personalizado e introducir el nombre del área de trabajo.
• Seleccione su aplicación App Builder en la lista y guárdela. Si la aplicación no aparece, haga clic en Actualizar registros e inténtelo de nuevo.

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

Configurar el método de envío simulado en la IU del administrador de Adobe Commerce:

• Abra Aplicaciones y seleccione su aplicación.

• Abra la ficha Envío ficticio (o equivalente).

• Introduzca la siguiente información:

  • URL del servicio: la URL del flujo de trabajo de Pipedream que copió (por ejemplo: https://123456.m.pipedream.net).
  • Clave de API: cualquier valor no vacío para el simulacro, por ejemplo tutorial-key.
  • Dirección de origen del almacén: nombre, teléfono, calle, ciudad, estado, código postal, país.

• Haga clic en Guardar. La configuración se almacena en el estado de tiempo de ejecución y la utiliza la acción shipping-methods.

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

Verificar al finalizar la compra: Agrega un producto al carro de compras, ve al cierre de compra e ingresa una dirección de envío. Debería ver las opciones de envío ficticias, por ejemplo Mock Standard y Mock Express.

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