Marketplace Catalog Sync

• VTEX 마켓플레이스에 새로운 SKU를 푸시하고 제안(전송 → 대기 중 → 승인/거부) 라이프사이클을 처리하는 셀러 커넥터 구축.
• 마켓플레이스에 SKU가 이미 존재하는지(200 OK) 또는 새로운 제안이 필요한지(404 Not Found)를 감지하기 위한 변경 알림 플로우 구현.
• /notificator/{sellerId}/changenotification/{sellerSkuId}/price 및 /inventory 엔드포인트를 통한 가격 및 재고 변경 사항 동기화.
• 2.5초 이내에 응답해야 하는 셀러 측 주문 처리 시뮬레이션 엔드포인트(POST /pvt/orderForms/simulation) 구현.

• POST /api/catalog/pvt/product 또는 POST /api/catalog/pvt/stockkeepingunit 직접 쓰기와 같은 마켓플레이스 측 카탈로그 작업을 수행하는 경우 — 이는 셀러 커넥터 플로우가 아닙니다.
• 주문 이행 또는 인보이스 처리 로직이 필요한 경우 (대신 marketplace-fulfillment 스킬을 참조하세요).
• 카탈로그 알림 플로우와 분리된 독립적인 속도 제한 패턴이 필요한 경우 (대신 marketplace-rate-limiting 스킬을 참조하세요).

셀러 커넥터는 POST .../changenotification/{sellerId}/{sellerSkuId} 를 사용해야 합니다. 마켓플레이스 VTEX SKU ID를 요구하는 단일 세그먼트 방식인 changenotification/{skuId} 라우트가 아닙니다. 이 스킬은 두 라우트의 차이를 문서화하고, 공식 문서에서 두 라우트가 혼용되는 이유를 설명하며, 200(업데이트) 및 404(새 제안) 응답 경로 모두에 대한 구체적인 TypeScript 예제를 제공합니다.

새로운 SKU는 PUT https://api.vtex.com/{accountName}/suggestions/{sellerId}/{sellerSkuId}를 통한 제안/승인 워크플로우를 거쳐야 합니다. 외부 셀러의 경우 Catalog API 직접 쓰기가 금지되어 있으며, 이를 시도할 경우 403 Forbidden이 반환됩니다. 제안은 Pending 상태일 때만 수정할 수 있으며, 승인되거나 거부된 제안은 변경할 수 없습니다. 이로 인해 제안 업데이트 전에 반드시 상태 확인이 수행됩니다.

가격 및 재고 업데이트는 별도의 POST /notificator/{sellerId}/changenotification/{sellerSkuId}/price 및 .../inventory 엔드포인트를 통해 전송되며, 경로 세그먼트는 판매자의 SKU ID입니다(마켓플레이스 VTEX SKU ID가 아님). 이러한 알림 이후, 마켓플레이스는 판매자의 Fulfillment Simulation 엔드포인트를 호출하여 최신 데이터를 가져옵니다.

마켓플레이스는 가격 또는 재고 알림이 발생할 때마다 판매자의 POST /pvt/orderForms/simulation 엔드포인트를 호출합니다. VTEX는 응답을 최대 2.5초 동안 기다리며, 이 제한을 초과하면 해당 상품이 스토어프런트에서 품절 상태로 표시됩니다. 이 스킬은 엔드포인트가 50ms 이내에 응답할 수 있도록 캐시 우선 구현 패턴(인메모리 또는 Redis)을 제공합니다.

스로틀링 없이 대량 변경 알림 요청을 전송하면 429 응답이 발생하여 판매자의 전체 API 액세스가 차단됩니다. 이 스킬은 배치별 지연, retry-after 헤더 파싱, 429 오류에 대한 지수 백오프를 포함한 배치 처리 및 동시성 제어 알림 루프를 제공합니다.

카탈로그 시스템 경로(예: changenotification)는 스토어 호스트명({account}.vtexcommercestable.com.br)을 사용하고, SKU 제안 경로는 https://api.vtex.com/{accountName}을 사용합니다. 두 서비스 모두 동일한 X-VTEX-API-AppKey 및 X-VTEX-API-AppToken 헤더로 인증합니다. 이 스킬은 두 기본 URL을 모두 지원하는 타입이 지정된 SellerConnectorConfig와 Axios 클라이언트 팩토리를 제공합니다.

판매자가 처음으로 VTEX 마켓플레이스에 연결하여 전체 SKU 카탈로그를 등록해야 합니다. 통합은 각 SKU에 대해 changenotification/{sellerId}/{sellerSkuId}를 호출하며, 404 응답이 발생할 때마다 PUT SKU 제안이 트리거되어 각 SKU를 운영자 승인을 위한 마켓플레이스의 검토 대기 큐에 배치합니다.

판매자의 창고 시스템이 가격 또는 재고 변경 이벤트를 발생시킵니다. 커넥터는 /notificator/ 엔드포인트를 통해 가격 및 재고 알림을 일괄 전송하며, 미리 워밍된 캐시를 기반으로 하는 판매자의 주문 처리 시뮬레이션 엔드포인트는 2.5초 마감 시간 내에 마켓플레이스 폴링 요청에 응답합니다.

운영자는 전송되었지만 아직 검토되지 않은 제안의 제품 데이터를 업데이트해야 합니다. 통합은 먼저 GET /suggestions/{sellerId}/{sellerSkuId}를 호출하여 제안이 여전히 Pending 상태인지 확인한 다음, 수정된 데이터와 함께 PUT 요청을 실행합니다. 이미 승인되거나 거부된 제안은 경고와 함께 건너뜁니다.

제품 데이터 마이그레이션 후 수백 개의 SKU에 재알림이 필요합니다. 통합은 일괄 알림 패턴을 사용하여 — SKU를 5개 그룹으로 처리하고 배치 간 200ms 지연 및 429 오류 인식 재시도 로직을 적용하여 — 속도 제한 차단을 유발하지 않고 마켓플레이스에 재알림을 전송합니다.