# 굿즈 API 및 연동 계약 | MerchandAise

- slug: developers-api-integrations
- locale: ko
- localeResolved: ko
- canonical: https://www.merchandaise.com/ko/developers/api-integrations

어시스턴트 도구, 커뮤니티 임베드, 공급업체 운영 및 엔터프라이즈 ID를 위한 MerchandAise 계약을 명확한 공개 및 보호 액세스 경계와 함께 살펴보세요.

## 단일 진실 공급원(Single Source of Truth) 유지
연동은 MerchandAise 워크플로우를 확장해야 하며, 이를 포크(fork)해서는 안 됩니다. 웹사이트, 임베드, 공급업체, 엔터프라이즈 및 향후 추가될 어시스턴트 영역은 모두 동일한 버전의 디자인, 커머스 의도, 견적, 승인 및 주문 상태를 읽고 업데이트해야 합니다.
MerchandAise가 구매자 거래를 처리하는 경우, 계약 판매자 및 주문 처리 대행사(Merchant of Record)는 MerchandAise 브랜드 하의 Hutter Products GmbH입니다. 공급업체의 신원 및 연락처 정보는 공개가 의무화된 경우를 제외하고 비공개로 유지되며, 대량 생산 전에는 여전히 디지털 시안 및 실제 생산 샘플 승인이 필요합니다.

## API 및 연동 영역
- **어시스턴트 도구 API 문서:** 디자인 세션 및 연동 검토를 위한 현재 어시스턴트 및 도구 엔드포인트를 살펴보세요. 이 공개 참조 문서는 견적을 내거나 주문을 넣을 수 있는 익명 권한을 부여하지 않습니다. Human guide: 어시스턴트 도구 문서 열기 (/ko/developers/api-integrations). Machine-readable contract: 어시스턴트 도구 OpenAPI JSON (/api/docs/openapi.json). Access: public. 어시스턴트 및 도구 API용 공개 참조 문서입니다. 프로덕션 액세스 및 주문에 영향을 미치는 작업에는 여전히 적절한 권한 부여가 필요합니다. Canonical page: /developers/api-integrations. Canonical section: /developers/api-integrations#api-docs.
- **커뮤니티 임베드 API:** 기본 워크플로우를 재구축할 필요 없이, 현지화된 클럽, 커뮤니티 또는 스토어프런트 경험을 MerchandAise 소유의 디자인 및 커머스 핸드오프에 연결하세요. Human guide: 커뮤니티 연동 가이드 검토 (/ko/developers/api-integrations#community-integrations). Machine-readable contract: 커뮤니티 OpenAPI JSON (/api/v1/community/public/openapi/v1). Access: public. 스토어프런트 임베드, 커뮤니티 탐색 및 로케일 인식 핸드오프를 위한 공개 버전 관리 계약입니다. Canonical page: /developers/api-integrations. Canonical section: /developers/api-integrations#community-integrations.
- **공급업체 API:** 공급업체 관계 및 액세스 모델이 검증된 후, 승인된 공급업체를 온보딩, 카탈로그, 견적 및 주문 처리 작업에 연결하세요. Human guide: 공급업체 연동 가이드 검토 (/ko/developers/api-integrations#supplier-integrations). Machine-readable contract: 공급업체 OpenAPI JSON (/api/v1/supplier/openapi/v1). Access: public. 계획 및 클라이언트 생성을 위한 공개 계약입니다. 실제 공급업체 운영 액세스 권한은 여전히 제한되어 있습니다. Canonical page: /developers/api-integrations. Canonical section: /developers/api-integrations#supplier-integrations.
- **엔터프라이즈 ID API:** 승인된 기업 굿즈 프로그램 및 통제된 배포를 위해 SSO, SCIM 프로비저닝 및 감사 준비가 완료된 ID 흐름을 계획하세요. Human guide: 엔터프라이즈 연동 가이드 검토 (/ko/developers/api-integrations#enterprise-integrations). Machine-readable contract: 엔터프라이즈 ID OpenAPI JSON (/api/v1/enterprise/identity/openapi/v1). Access: protected. 승인된 엔터프라이즈 워크스페이스를 위한 보호된 계약입니다. 이 엔드포인트를 사용하기 전에 액세스를 요청하세요. Canonical page: /developers/api-integrations. Canonical section: /developers/api-integrations#enterprise-integrations.

## 코드 작성 전에 계약 먼저 선택하기
- **Step 1: 사용자 여정 매핑:** 임베디드 스토어프런트의 구매자, 승인된 공급업체, 엔터프라이즈 사용자 또는 명시적 권한을 가지고 작동하는 어시스턴트 등 누가 어디서 워크플로우에 진입할지 결정하세요.
- **Step 2: 액세스 경계 확인:** 평가 및 클라이언트 생성을 위해 공개 계약을 사용한 다음, 구현 전에 자격 증명, 범위, 환경, 콜백 및 보호된 엔드포인트를 확인하세요.
- **Step 3: 상태 연속성 검증:** 재시도 및 롤백 경로를 포함하여 디자인, 견적, 승인, 오류 및 주문 핸드오프가 연동 전반에서 최신 버전으로 유지되는지 테스트하세요.

## 모든 연동에서 반드시 유지해야 하는 사항
- **단일 버전 상태:** 디자인, 커머스 의도, 공급업체 기반 견적, 승인 및 주문 상태가 연결되어 유지됩니다. 오래된 변경 사항은 시각적인 재견적 또는 검토 상태를 트리거해야 합니다.
- **상업 및 공급업체 개인정보 보호:** MerchandAise는 구매자를 대면하는 판매자 및 지원 소유자로 유지됩니다. 공급업체의 신원, 연락처 및 내부 데이터는 공개 연동을 통해 노출되지 않습니다.
- **생산 전 승인:** 제품 고유의 3D 뷰와 디지털 시안이 의사 결정을 지원하지만, 대량 생산 전에 필수적인 실제 생산 샘플을 대체할 수는 없습니다.

## 프로덕션 트래픽 시작 전
게시된 OpenAPI 파일은 계획을 위한 영역일 뿐, 익명의 프로덕션 액세스를 보장하지 않습니다. 서비스 개시 전에 환경, 자격 증명, 실패 처리 및 운영 소유권을 검토합니다.
- **액세스 및 환경:** 계약 버전, 승인된 워크스페이스, 인증 범위, 샌드박스, 프로덕션 자격 증명 및 콜백 대상을 확인하세요.
- **실패 및 복구:** 출시 전에 재시도, 멱등성, 타임아웃, 고객에게 표시되는 오류, 관찰 가능성, 지원 소유권 및 롤백을 정의하세요.
- **엔드투엔드 검증:** 진입 및 상태 변경부터 견적, 승인, 핸드오프 및 복구 동작에 이르기까지 스테이징 환경에서 의도한 여정을 검증하세요.

## FAQ
- **어떤 연동 영역부터 시작해야 하나요?:** 대상 사용자와 상태 전환부터 시작하세요. 구매자 대면 클럽 또는 커뮤니티 여정에는 커뮤니티 임베드를, 승인된 공급측 워크플로우에는 공급업체 운영을, SSO 및 SCIM에는 엔터프라이즈 ID를 사용하고, 명시적으로 권한이 부여된 AI 기반 흐름에만 어시스턴트 도구를 사용하세요.
- **공개 계약이 공개 프로덕션 액세스를 의미하나요?:** 아닙니다. 공개 OpenAPI 계약은 탐색, 아키텍처 검토 및 클라이언트 생성을 지원합니다. 프로덕션 자격 증명, 쓰기 작업, 공급업체 워크플로우, 엔터프라이즈 ID 및 어시스턴트 실행에는 여전히 승인된 워크스페이스와 범위가 지정된 권한 부여가 필요할 수 있습니다.
- **연동을 통해 공급업체를 노출하거나 승인 단계를 우회할 수 있나요?:** 아닙니다. 공급업체의 신원 및 연락처 정보는 공개가 의무화된 경우를 제외하고 비공개로 유지되며, MerchandAise가 구매자 관계를 소유합니다. 또한 주문에 영향을 미치는 작업은 구성된 승인 및 실제 샘플 확인 단계를 반드시 거쳐야 합니다.

## 완성된 아키텍처가 아닌, 워크플로우를 먼저 제안해 주세요.
누가 연동을 사용할지, 어떤 상태를 읽거나 변경해야 하는지, 그리고 해당 경험이 어디에 위치할지 알려주세요. 당사가 귀사와 함께 계약, 액세스 모델 및 가장 안전한 배포 경로를 설계해 드립니다.
- **연동 계획하기:** /ko/contact?intent=api-integration-review
- **AI 에이전트 및 MCP 알아보기:** /ko/developers/ai-agents-mcp