# 定制商品 API 与集成契约 | MerchandAise

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

探索适用于辅助工具、社区内嵌、供应商业务及企业身份的 MerchandAise 契约，明确公开与受保护的访问边界。

## 保持单一真实数据源
集成应当扩展 MerchandAise 工作流，而非分叉它。网站、内嵌组件、供应商、企业以及未来的助手端，都必须读取并更新相同的版本化设计、商业意图、报价、审批及订单状态。
在 MerchandAise 处理买家交易的同时，Hutter Products GmbH 作为签约卖方和 MerchandAise 品牌旗下的官方商户（Merchant of Record）。除法规要求披露外，供应商的身份与联系方式将保持保密，且生产仍须通过数码样稿与实物样品的审批。

## API 与集成界面
- **助手工具 API 文档:** 探索用于设计会话及集成评审的当前助手与工具端点。此公开参考文档不赋予匿名报价或下单权限。 Human guide: 打开助手工具文档 (/zh/developers/api-integrations). Machine-readable contract: 助手工具 OpenAPI JSON (/api/docs/openapi.json). Access: public. 助手与工具 APIs 的公开参考。生产环境访问及涉及订单的操作仍需获得相应授权。 Canonical page: /developers/api-integrations. Canonical section: /developers/api-integrations#api-docs.
- **社区内嵌 API:** 将本地化的俱乐部、社区或店面体验连接到由 MerchandAise 运营的设计与商业交接流程，无需重建底层工作流。 Human guide: 查看社区集成指南 (/zh/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: 查看供应商集成指南 (/zh/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.
- **企业身份 API:** 为获批的公司商品项目及规范化上线规划 SSO、SCIM 配置以及符合审计要求的身份流。 Human guide: 查看企业集成指南 (/zh/developers/api-integrations#enterprise-integrations). Machine-readable contract: 企业身份 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 文件是一个规划参考，而非匿名生产访问的承诺。我们在正式上线前会审核环境、凭证、故障处理和运营权责。
- **访问与环境:** 确认契约版本、获批的工作区、认证作用域、沙箱、生产凭证以及回调目标地址。
- **故障与恢复:** 在发布前明确重试、幂等性、超时、面向客户的错误提示、可观测性、支持归属以及回滚方案。
- **端到端证据:** 在预发环境中验证预期的旅程，从入口和状态变更，一直到报价、审批、交接及恢复行为。

## 常见问题
- **我应该从哪个集成界面开始？:** 从人员和状态流转开始。面向买家的俱乐部或社区旅程使用社区内嵌，获批的供给侧工作流使用供应商业务，SSO 与 SCIM 使用企业身份，而助手工具仅用于获得明确授权的、由 AI 主导的流程。
- **公开契约是否意味着公开的生产访问权限？:** 不是。公开的 OpenAPI 契约用于发现、架构评审和客户端生成。生产凭证、写操作、供应商工作流、企业身份和助手执行仍可能需要获批的工作区和具有作用域的授权。
- **集成是否可以暴露供应商或绕过审批？:** 不可以。除法律法规要求披露外，供应商身份与联系方式保持保密；MerchandAise 拥有买家关系；且涉及订单的操作必须保留已配置的审批和真实样品关卡。

## 带上您的工作流来找我们，无需准备完整的架构。
告诉我们谁将使用此集成、他们需要读取或更改哪些状态，以及体验将落地何处。我们将与您一同规划契约、访问模型及最安全的上线路径。
- **规划集成:** /zh/contact?intent=api-integration-review
- **探索 AI 代理与 MCP:** /zh/developers/ai-agents-mcp