# @godaddy/gd-commerce-server 中文文档

规范地址：https://npmcn.com/package/%40godaddy/gd-commerce-server/

版本：0\.4\.1
npm 元数据更新时间：2026-11-06T17:23:13.000Z
中文译文更新时间：2026-11-16T17:53:05.981Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40godaddy/gd-commerce-server
原文对照：https://npmcn.com/package/%40godaddy/gd-commerce-server/?lang=original
项目主页：https://github.com/godaddy/javascript#readme
源码仓库：https://github.com/godaddy/javascript

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：81.5 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：express ^5\.0\.0
- 首次发布：2026-09-28T17:41:23.922Z
- 最新版本发布：2026-11-06T17:23:12.609Z
- 近 30 天下载量：10515（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

GoDaddy Commerce 的意见快递服务器集成

## 安装

```sh
npm install @godaddy/gd-commerce-server
```

也可以使用：`pnpm add @godaddy/gd-commerce-server`、`yarn add @godaddy/gd-commerce-server`、`bun add @godaddy/gd-commerce-server`

## README

# @godaddy/gd-commerce-服务器

GoDaddy Commercial Catalog, 推车的透视快递路由器.

```ts
import express from 'express';
import { createCommerceRouter, createRuntimeCommerceConfiguration } from '@godaddy/gd-commerce-server';

const app = express();
app.use(express.json());
app.use('/api/commerce', createCommerceRouter({
  configuration: createRuntimeCommerceConfiguration(),
  checkoutReturnUrls: {
    returnUrls: ['https://shop.example.com/shop'],
    successUrls: ['https://shop.example.com/checkout/success'],
  },
}));
```

默认配置读取这些 **只使用服务器的环境变量** 根据每项请求:

-   `GODADDY_OAUTH_CLIENT_ID` 财务报告和审定财务报表 `GODADDY_OAUTH_CLIENT_SECRET`
-   `GODADDY_STORE_ID` 财务报告和审定财务报表 `GODADDY_CHANNEL_ID`
-   `GODADDY_CURRENCY_CODE`
-   可选 `GODADDY_CHECKOUT_CONFIGURATION`JSON 有布尔语 `enablePromotionCodes`, (中文(简体) ), `enableTaxCollection`,以及 `enableShipping` 字段。 当该变量缺失或变异时, 全部三处默认为虚假, 因此配置发现无法阻止退出创建 。 可选 `shipping` 接受检出 API 的 `originAddress` 或者说 `fulfillmentLocationId`; 省略它以使用存储配置.

见 [退出配置](https://npmcn.com/package/%40godaddy/gd-commerce-server/docs/checkout-configuration.md) 用于临时建设时间同步流动及其最终一致性限制.

API 来源默认为 `https://api.godaddy.com`。软件包不装入文件、提供商或指定应用程序属性。 东道国拥有这些关切和任何准备状态检查或复议,然后才援引商务.

## 主机配置

对于一个可替代的 API 源,通过一个明确的服务器控制选项. 它必须是没有证书、路径、查询或片段的HTTPS来源。 主办方负责信任接收OAuth证书的目的地. 请求机构从不选择API来源或归属.

```ts
const configuration = createRuntimeCommerceConfiguration({
  apiBaseUrl: process.env.COMMERCE_API_ORIGIN, // undefined uses production
  sourceApp: process.env.COMMERCE_SOURCE_APP,
  owner: process.env.COMMERCE_ORDER_OWNER,
});
```

`apiBaseUrl` 控制目录、顺序和 OAuth 请求; 退出使用相应的 `checkout.commerce.` 子域名。 没有其它环境的内置列表 . `sourceApp` 财务报告和审定财务报表 `owner` 是可选主机拥有的归属值: 退出同时使用, 而订单草稿使用 `owner`。您的商务整合所需的供应值; 包默认省略.

拥有自己配置服务的主机可以执行 `CommerceConfiguration` 直接说. `read()` 返回时 `clientId`, (中文(简体) ), `clientSecret`, (中文(简体) ), `storeId`, (中文(简体) ), `channelId`, (中文(简体) ), `currencyCode`, (中文(简体) ), `apiBaseUrl`和可选择的归属. `readCheckout()` 返回取出标记和可选的运入设置。 从一个一致的绑定状态返回已验证的即时使用设置 。 这两种功能都在服务器上运行;证书决不能到达浏览器代码.

## 路由器和辅助器

`createCommerceCatalogRouter(configuration)` 安装目录、公共配置和车道. `createGoDaddyPaymentsRouter(configuration, checkoutReturnUrls)` 安装检出和只读命令状态路由而不需要目录 UI. `createCommerceRouter({ configuration })` 默认同时安装或接受明显的特征标记.

HTTP 检出路由接受已有的 `draftOrderId` 或直接 `skuId`; 商业解决目录价格. 它拒绝 `lineItemData`。对于固定价格存款等非目录费用,计算服务器上的金额并拨打 `createCheckoutSession(params, configuration)` 直接说 从不向这个信任的助手转发浏览器提供的价格 。 服务器呼叫器也可以使用 `getOrderStatus(orderId, configuration)` 无需HTTP回转.

### 产品频道能见度

`GET /products` 财务报告和审定财务报表 `GET /products/:id` 使用服务器配置的频道,仅请求 `ACTIVE` 产品。 搜索,分类过滤器,以及明确的产品ID保留了该通道过滤器. 产品详细要求该频道无法提供的产品返回404。 浏览器查询参数不能选择不同的信道 。 当配置的频道活动并注册到商店时,为所有频道配置的产品仍然可用.

如果配置 `GODADDY_CHANNEL_ID` catalog API 返回一个空产品列表, 而产品细节请求返回 404 。 这些是来自 Catalog API 的成功空出结果,而不是配置错误 。 当预期目录为空时, 请确认频道是否活动并注册到 `GODADDY_STORE_ID`,然后检查产品状态和频道任务。 一个不见了 `GODADDY_CHANNEL_ID` 不同: 默认配置读取器以 503 拒绝它 `not_configured`。 。 。 .

Catalog API 解析活性存储通道 `/v1/commerce/channels` 评估频道过滤器时的结束点 。 这些查询目前没有被Catalog API缓存,因此频道过滤的目录请求可以添加上游调用和延迟.

这些检查控制产品浏览. `GET /skus/:id`,推车创建(`POST /cart`页:1`POST /cart/:id/items`转发 SKU ID 不检查其产品是否在配置的信道上可用 。 来自产品细节的404不能确定SKU的查询或推车书写会被拒绝. 需要对这些操作进行频道限制的主机在转发SKUID前必须执行;浏览过滤器不是授权边界.

## 检查返回目的地

配置 `checkoutReturnUrls` 在路由器上使用信任的部署设置。 两个列表都包含完整的绝对HTTPS URL;方案,出处,端口,路径,以及所配置的查询参数必须相匹配. 成功 URL 可能添加单个 `orderId` 查询参数。 额外的查询参数,片段,证书,相对URL,以及未列出的目的地被拒绝. 配置上面显示的单独的取消和成功目的地; 不从请求头或请求机构获取允许列表 .

如果没有此策略, HTTP 在创建会话前返回 503 。 无效的请求目的地返回 400 。 这适用于两个显示退出的路由器预设. 信任的流程中呼叫者 `createCheckoutSession()` 拥有返回的 URL,必须构建或验证其服务器侧.

从主机退票返回不是付款的证据。 订单状态路由使用支持已完成订单的已授权命令 REST API,并返回其付款状态(例如) `PAID` 或者说 `PENDING`; 导出 `ORDER_STATUS_UNKNOWN`, (中文(简体) ), `'unknown'`(如果缺席) 只显示为显出丰富, 并且不出示未经证实的付款。 必须批准服务器 OAuth 客户端 `commerce.order:read`。帮助者验证返回的订单 ID、存储和通道,并返回没有客户联系数据的有限摘要。 路由返回400 一个缺失,空白,加, `.`,或 `..` 命令 ID( 添加的ID 被拒绝, 不修饰) 或 API 命令 拒绝的其中一种错误 `VALIDATION_FAILED`404 当命令API报告命令缺失时(404) `NOT_FOUND`)或命令属于另一个商店或频道. 没有这个代码的404,例如来自错误配置的API基础URL,是一个上游失败. Token 和其他商业故障,包括不同订单ID的响应,返回 502 和不可读配置返回 503(见 [错误](https://npmcn.com/package/%40godaddy/gd-commerce-server/#readme-errors)) (中文(简体) ). 主机必须认证呼叫者,并授权访问所请求的每个命令后,才能曝光这条路线.

### 连接状态

主机可以执行可选同步 `CommerceConfiguration.readConnectionState()` 方法。 它的返回类型导出为 `CommerceConnectionState` (单位:千美元)`unbound | connecting | ready`) (中文(简体) ). 正在返回 `undefined` 保持现有行为。 状态未知或无法时抛出 读取。 默认环境配置不执行此方法, 所以缺少 证书从不计为 `unbound`。 。 。 .

`GET /config` 返回时 `{ state: 'unbound' }` 或者说 `{ state: 'connecting' }` 不读取存储 证书. `ready` 包括通常不透明 `cartScope` 财务报告和审定财务报表 `currencyCode` 之后 `read()` 成功 。 没有这种方法,成功的响应形状不变. 所有答复是 未选中; 状态不正确或无法配置返回503。 数据及取出路线, 和进程内检查和命令帮助者,拒绝除 `ready` 在此之前 上游电话.

主机拥有连接生命周期. 报告 `ready` 仅在商店连接之后 完成 。 。 配置丢失是一个错误, 绝不是 `unbound`在商店连接之后, 报告 `unbound` 只有在它被故意断开之后。 存储前端软件包拥有 此服务器从未创建样本 记录或模拟退出.

#### 商店连接前的站点

在商店连接之前显示店面样本产品的模板需要目录路径和 明确连接状态。 给 `COMMERCE_CONNECTION_STATE` 是主机拥有的设置,设置为 `unbound` 当网站 创建并创建到 `ready` 由主机的连接流。 从任何记录中读取联系; 永远不要得到联系 失踪的 `GODADDY_*` 变量.

```ts
import express from 'express';
import { createCommerceCatalogRouter, createRuntimeCommerceConfiguration } from '@godaddy/gd-commerce-server';

const runtime = createRuntimeCommerceConfiguration();
const configuration = {
  ...runtime,
  readConnectionState() {
    const state = process.env.COMMERCE_CONNECTION_STATE;
    if (state === 'unbound' || state === 'connecting' || state === 'ready') return state;
    throw new Error('COMMERCE_CONNECTION_STATE must be unbound, connecting, or ready.');
  },
};

const app = express();
app.use(express.json());
// Before static files and any single-page app or SSR fallback, which would answer /api/commerce with HTML.
app.use('/api/commerce', createCommerceCatalogRouter(configuration));
app.use(express.static('dist'));
```

`createCommerceCatalogRouter` 显示没有检出路径, 因此一个站点不需要检出 `checkoutReturnUrls`。 。 。 . `GET /api/commerce/config` 应返回 `{"state":"unbound"}` 作为JSON。 如果它返回应用程序的 HTML 页面,则 路由器没有被挂起,或者在它之前有一个倒回路线运行.

## 错误

每条路线都报告失败 躯体是 `{ "error": "<customer-facing message>", "code": "<code>", "requestId": "<id>" }` (顺序状态还包括: `success: false`) (中文(简体) ). 同样的ID传递给伐木工. 机构从不包含上游消息,配置细节,或证书.

| 状态 | `code` | 含义 |
| --- | --- | --- |
| 400个 | `invalid_request` | 缺少或无效输入 . |
| 404 (韩语) | `not_found` | 缺少订单或产品,或写给现有推车(`/cart/:id/...`缺少、已过期或已完成。 继续返回 `200 { "cart": null }`。用 Stale 或 完成的结账 `draftOrderId` 尚未区分,返回502. |
| 409个 | `scope_mismatch` | `X-Commerce-Scope` 不再匹配已配置的商店绑定 . |
| 502 (中文(简体) ) | `upstream_unauthorized` | 商务拒绝此服务器的 OAuth 客户端或请求范围( HTTP 401/403 或 OAuth 400 带有 `invalid_client`, (中文(简体) ), `invalid_grant`, (中文(简体) ), `unauthorized_client`,或 `invalid_scope`) (中文(简体) ). 它涉及服务器证书,而不是呼叫者,所以它从来没有被报道为401/403. |
| 502 (中文(简体) ) | `upstream_error` | 商业失败,退回出乎意料的反应,或者无法联系到. |
| 第503条 | `not_configured` | 配置缺失或无法读取, 主机会报告一个连接状态 `ready`,或者不配置退出返回 URL. |
| 500个 | `internal_error` | 此软件包中出乎意料的错误 . |

上游出错,没有特定的映射停留502;无效折扣代码等业务出错尚未区分出. 5xx 细节, 包括上游状态和 GraphQL 错误代码

```ts
createCommerceRouter({
  configuration,
  logger: { error: (message, context) => log.error(context, message) },
  // Use the host's request id when its edge sets one; unsafe or missing ids fall back to a UUID.
  getRequestId: (req) => req.get('x-request-id'),
});
```

`createCommerceCatalogRouter` 财务报告和审定财务报表 `createGoDaddyPaymentsRouter` 接受相同的建议 `{ logger, getRequestId }` 作为他们最后的论点。 日志默认为 `console.error`。处理中帮助将导出的文件丢出 `CommerceError` 子类 (`InvalidRequestError`, (中文(简体) ), `NotFoundError`, (中文(简体) ), `CommerceNotConfiguredError`, (中文(简体) ), `UpstreamError`),包括当一个主机配置在被读取时抛出. 检查 `error.code` (例如 `'not_found'`)而不是(a) `instanceof`,当一个主机有多个本套件副本时失败.

## 常见问题

### @godaddy/gd-commerce-server 是什么？

GoDaddy Commerce 的意见快递服务器集成

### 如何安装 @godaddy/gd-commerce-server？

在项目目录运行 npm install @godaddy/gd-commerce-server，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：express（^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @godaddy/gd-commerce-server 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @godaddy/gd-commerce-server 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @godaddy/gd-commerce-server 可以商用吗？

@godaddy/gd-commerce-server 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @godaddy/gd-commerce-server 的下载量有多少？

根据 npm 官方下载统计，@godaddy/gd-commerce-server 在 2026/10/17 – 2026/11/15 这 30 天内被下载 10,515 次，日均约 351 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @godaddy/gd-commerce-server 还在维护吗？

最新版本 0\.4\.1 发布于 2026/11/07（10 天前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/09/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

