배송 방법 확장 튜토리얼

pipedream.com​(으)로 이동하여 등록하거나 로그인합니다.

새 워크플로(또는 워크플로 추가)를 클릭합니다.

트리거를 사용하려면 HTTP/Webhook​을(를) 선택하십시오.

트리거 구성에서 HTTP 응답​을(를) 워크플로에서 사용자 지정 응답을 반환(으)로 설정합니다. 이렇게 하면 코드 단계에서 모의 JSON 응답을 보낼 수 있습니다.

Pipedream은 과(와) 같은 고유한 HTTP 끝점 URLhttps://123456.m.pipedream.net을(를) 표시합니다.

이 URL을 복사하여 Commerce 관리에서 확장을 구성할 때 서비스 URL(으)로 사용합니다.

HTTP/Webhook 트리거와 끝점 URL이 표시되는 {width="600" modal="regular"}

단계를 추가하려면 + 아이콘을 클릭하십시오.

Node.js 코드 실행​을 선택합니다(코드 단계).

기본 코드를 다음 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 },
   });
},
});

배포​를 클릭합니다.

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

코딩 에이전트의 MCP 설정으로 이동합니다. 예를 들어 커서에서 Cursor > Settings > Cursor Settings > Tools & MCP(으)로 이동합니다. commerce-extensibility 도구 집합이 오류 없이 사용하도록 설정되어 있는지 확인하십시오. 오류가 표시되면 도구 세트를 끄고 켜십시오.

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

커서 컨텍스트에 추가된 설명서가 있는 경우 비활성화합니다. 커서 > 설정 > 커서 설정 > 색인화 및 문서​(으)로 이동하여 나열된 문서를 삭제합니다.

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

클라이언트를 올바르게 구현할 수 있도록 에이전트에게 모의 비율 API 사양에 대한 액세스 권한을 부여합니다. 아직 다운로드하지 않았다면 mock rate API 사양 파일을(를) 다운로드하여 연 다음 .md 파일을 프로젝트에 추가한 다음(예: docs/mock-rates-api-spec.md) 프롬프트에서 해당 파일을 참조하십시오.

운송 방법 확장을 생성합니다.

• 가능한 경우 에이전트의 채팅 창에서 플랜 모드를 선택하십시오. 이렇게 되면 에이전트가 계획 없이 진행할 수 없습니다.
• 다음 프롬프트를 입력합니다.

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

에이전트의 질문에 정확하게 답변하여 최상의 코드를 생성할 수 있도록 도와줍니다. 에이전트에서 사용할 키트 또는 템플릿을 묻는 경우 배송 도메인과 관리자 UI SDK 확장 기능이 있는 체크아웃 스타터 키트로 보내면 배송 웹후크와 판매자 구성 화면이 모두 구현됩니다.

에이전트는 구현을 위한 신뢰할 수 있는 원본 역할을 하는 requirements.md(또는 이에 상응하는) 파일을 만들 수 있습니다.

requirements.md(또는 이에 상응하는) 파일을 검토하고 계획을 확인합니다. 모든 것이 올바르게 보이는 경우 에이전트에게 아키텍처 계획(또는 단계 2)으로 이동하도록 지시합니다. 다음을 확인합니다.

• shipping-methods 작업(또는 이와 동등한 작업)은 Commerce 웹후크를 처리하고 외부 속도 API를 호출합니다.
• shipping-config(또는 이와 동등한 작업)은 런타임 상태와 같이 구성이 안전하게 저장된 GET(읽기 구성, API 키 마스크) 및 SET(저장 서비스 URL, API 키, 웨어하우스 주소)를 지원합니다.
• 관리 UI에는 서비스 URL, API 키(암호/마스크) 및 웨어하우스 주소 필드가 있는 모의 배송(또는 이와 유사한) 탭이 있습니다.

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

에이전트가 제공할 때 아키텍처 계획을 검토합니다.

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

코드 생성을 진행하도록 에이전트에 지시합니다. 에이전트는 Commerce에서 반환된 메서드를 수락하고 웹후크 메서드 (웹후크 유형​후plugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_rates, 필수 선택 사항)를 사용할 수 있도록 하는 mock 캐리어를 배송 회사 구성에 추가해야 합니다.

에이전트는 필요한 코드를 생성하고 다음 단계(종속성 설치, 모의 통신사 등록, Commerce 웹후크 구성 및 배포 등)와 함께 자세한 요약을 제공합니다.

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

생성된 코드를 확인한 후 다음 프롬프트를 사용하여 확장을 배포합니다.

Deploy the app.

에이전트는 배포 전 준비 상태 평가를 수행합니다(예: 관리 UI 또는 Commerce API가 사용되는 경우 .env, COMMERCE_WEBHOOKS_PUBLIC_KEY 및 OAuth/IMS 변수에 대한 COMMERCE_BASE_URL 확인).

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

평가 결과가 확실하면 에이전트에게 배포를 진행하도록 지시합니다. 에이전트는 MCP 툴킷을 사용하여 자동으로 확인, 빌드 및 배포합니다.

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

Commerce에서 모의 통신사를 등록(배포 후 한 번 실행):

npm run create-shipping-carriers

스크립트가 통신사를 등록할 수 있도록 .env에 COMMERCE_BASE_URL과(와) 유효한 OAuth/IMS 자격 증명이 있는지 확인하십시오.

Commerce Admin에서 배송 웹후크 구성:

• 스토어 > 설정 > 구성 > Adobe 서비스 > Commerce 웹후크​로 이동합니다.

• 웹후크 추가:

  • Webhook 메서드: plugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_rates
  • Webhook 유형: 이후
  • URL: 배포된 배송 방법 웹 작업 URL(배포 출력 또는 Adobe Developer Console)입니다.
  • 필수: 선택 사항 - 외부 API에서 요금을 반환하지 않는 경우 체크아웃이 계속 작동합니다.

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

Admin UI SDK 확장 구성:

• Commerce Admin에서 스토어 > 설정 > 구성(으)로 이동합니다.
• Adobe 서비스 > 관리자 UI SDK​을 엽니다.
• 관리 UI SDK 사용​을(를) 예(으)로 설정하고 아직 활성화되지 않은 경우 구성 저장​을(를) 클릭합니다.
• 확장 구성​을 클릭하고 앱을 배포할 작업 영역을 선택한 다음 적용​을 클릭합니다. 사용자 지정 옵션을 선택하고 작업 영역 이름을 입력할 수도 있습니다.
• 목록에서 App Builder 앱을 선택하고 저장합니다. 앱이 나타나지 않으면 등록 새로 고침​을 클릭하고 다시 시도하십시오.

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

Adobe Commerce 관리 UI에서 모의 배송 방법을 구성합니다.

• 앱​을 열고 앱을 선택하세요.

• 모의 배송 탭을 엽니다(또는 이에 해당).

• 다음 세부 정보를 입력합니다.

  • 복사한 Pipedream 워크플로 URL을 서비스 URL:(예: https://123456.m.pipedream.net).
  • API 키: 모음에 대해 비어 있지 않은 모든 값(예: tutorial-key).
  • 웨어하우스(배송처) 주소: 이름, 전화, 거리, 도시, 주, 우편 번호, 국가.

• 저장​을 클릭합니다. 구성은 런타임 상태로 저장되며 전달 방법 작업에 사용됩니다.

서비스 URL, API 키 및 웨어하우스 주소가 있는 {width="600" modal="regular"}

체크아웃 시 확인: 장바구니에 제품을 추가하고 체크아웃으로 이동하여 배송 주소를 입력하십시오. 모의 배송 옵션이 표시됩니다(예: Mock Standard 및 Mock Express).

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