Tutorial de extensão do método de envio

Vá para pipedream.com e inscreva-se ou faça logon.

Clique em Novo fluxo de trabalho (ou Adicionar fluxo de trabalho).

Para o acionador, selecione HTTP / Webhook.

Na configuração do acionador, defina a Resposta HTTP como Retornar uma resposta personalizada do fluxo de trabalho. Isso permite que a etapa Código envie a resposta JSON fictícia.

Pipedream exibe uma URL de ponto de extremidade HTTP exclusiva, como https://123456.m.pipedream.net.

Copie esta URL e use-a como a URL de Serviço ao configurar a extensão no Administrador do Commerce.

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

Clique no ícone + para adicionar uma etapa.

Escolha Executar código Node.js (Etapa de código).

Substituir o código padrão pela seguinte 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 },
   });
},
});

Clique em Implantar.

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

Navegue até as configurações de MCP no seu agente de codificação. Por exemplo, no Cursor, vá para Cursor > Settings > Cursor Settings > Tools & MCP. Verifique se o conjunto de ferramentas commerce-extensibility está habilitado sem erros. Se você vir erros, desligue e ligue o conjunto de ferramentas.

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

Se você tiver alguma documentação adicionada ao contexto do cursor, desative-a. Navegue até Cursor > Configurações > Configurações do cursor > Indexação e documentos e exclua toda a documentação listada.

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

Conceda ao agente acesso à especificação da API de taxas simuladas para que ele possa implementar o cliente corretamente. Caso ainda não o tenha feito, baixe o arquivo de especificação da API de taxas de modelagem, abra-o e adicione o arquivo .md ao seu projeto (por exemplo, docs/mock-rates-api-spec.md) e, em seguida, faça referência a esse arquivo no seu prompt.

Gere a extensão do método de envio:

• Na janela de chat do agente, selecione o modo Plano, se disponível. Isso impede que o agente continue sem um plano.
• Digite o seguinte 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"}

Responda às perguntas do agente com precisão para ajudá-lo a gerar o melhor código. Se o agente perguntar qual kit ou modelo usar, direcione-o para o kit inicial de check-out com o domínio de envio e a extensão SDK da interface do administrador para que o webhook de envio e a tela de configuração do comerciante sejam implementados.

O agente pode criar um arquivo requirements.md (ou equivalente) que sirva como a fonte da verdade para a implementação.

Revise o arquivo requirements.md (ou equivalente) e verifique o plano. Se tudo estiver correto, instrua o agente a migrar para o planejamento de arquitetura (ou Fase 2). Confirme que:

• Uma ação shipping-methods (ou equivalente) lida com o webhook do Commerce e chama a API de taxas externas.
• Uma ação shipping-config (ou equivalente) é compatível com o GET (configuração de leitura, chave de API mascarada) e SET (salvar URL do serviço, chave de API, endereço do warehouse), com a configuração armazenada com segurança, por exemplo, em Estado de Tempo de Execução.
• A interface do Administrador inclui uma guia Envio de Mock (ou semelhante) com campos para URL de Serviço, chave de API (senha/mascarada) e endereço do warehouse.

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

Revise o plano de arquitetura quando o agente fornecê-lo.

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

Instrua o agente a prosseguir com a geração de código. O agente deve adicionar uma transportadora mock à configuração de transportadoras, permitindo que a Commerce aceite os métodos retornados e use o método de webhook plugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_rates (tipo de webhook after, obrigatório Optional).

O agente gera o código necessário e fornece um resumo detalhado com as próximas etapas (incluindo instalação de dependências, registro da operadora simulada, configuração do webhook do Commerce e implantação).

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

Depois de verificar o código gerado, implante a extensão usando o seguinte prompt:

Deploy the app.

O agente executa uma avaliação de prontidão de pré-implantação (por exemplo, verificar .env para COMMERCE_WEBHOOKS_PUBLIC_KEY, COMMERCE_BASE_URL e variáveis OAuth/IMS se a interface do usuário do administrador ou a API do Commerce for usada).

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

Quando estiver confiante nos resultados da avaliação, instrua o agente a prosseguir com a implantação. O agente usa o kit de ferramentas MCP para verificar, compilar e implantar automaticamente.

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

Registrar a operadora simulada no Commerce (executar uma vez após a implantação):

npm run create-shipping-carriers

Verifique se o .env tem COMMERCE_BASE_URL e uma credencial OAuth/IMS válida, para que o script possa registrar a operadora.

Configurar o webhook de envio em Commerce Admin:

• Vá para Lojas > Configurações > Configuração > Adobe Services > Webhooks do Commerce.

• Adicionar um webhook:

  • Método do Webhook: plugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_rates
  • Tipo de Webhook: after
  • URL: a URL de ação da Web de métodos de envio implantada (da saída de implantação ou do Adobe Developer Console).
  • Obrigatório: Opcional - Permite que o check-out ainda funcione se a API externa não retornar taxas.

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

Configurar a extensão Admin UI SDK:

• Em Commerce Admin, vá para Lojas > Configurações > Configuração.
• Abra o Adobe Services > Admin UI SDK.
• Defina Habilitar SDK da Interface do Administrador como Sim e clique em Salvar Configuração se ela ainda não estiver habilitada.
• Clique em Configurar extensões, escolha o espaço de trabalho no qual seu aplicativo está implantado e clique em Aplicar. Você também pode selecionar a opção Personalizado e inserir o nome do espaço de trabalho.
• Selecione o aplicativo App Builder na lista e salve. Se o aplicativo não for exibido, clique em Atualizar registros e tente novamente.

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

Configurar o método de envio simulado na interface do Administrador do Adobe Commerce:

• Abra Aplicativos e selecione seu aplicativo.

• Abra a guia Envio Simulado (ou equivalente).

• Insira os seguintes detalhes:

  • URL do Serviço: a URL do fluxo de trabalho Pipedream copiada (por exemplo, https://123456.m.pipedream.net).
  • Chave de API: qualquer valor não vazio para o modelo, por exemplo tutorial-key.
  • Endereço do depósito (origem da remessa): nome, telefone, rua, cidade, estado, CEP, país.

• Clique em Salvar. A configuração é armazenada no Estado de tempo de execução e é usada pela ação de métodos de envio.

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

Verificar no check-out: Adicione um produto ao carrinho, vá para o check-out e insira um endereço para remessa. Você deve ver as opções de envio de modelo, por exemplo Padrão de modelo e Expresso de modelo.

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