@godaddy/gd-commerce-服务器
GoDaddy Commercial Catalog, 推车的透视快递路由器.
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_SECRETGODADDY_STORE_ID财务报告和审定财务报表GODADDY_CHANNEL_IDGODADDY_CURRENCY_CODE- 可选
GODADDY_CHECKOUT_CONFIGURATIONJSON 有布尔语enablePromotionCodes, (中文(简体) ),enableTaxCollection,以及enableShipping字段。 当该变量缺失或变异时, 全部三处默认为虚假, 因此配置发现无法阻止退出创建 。 可选shipping接受检出 API 的originAddress或者说fulfillmentLocationId; 省略它以使用存储配置.
见 退出配置 用于临时建设时间同步流动及其最终一致性限制.
API 来源默认为 https://api.godaddy.com。软件包不装入文件、提供商或指定应用程序属性。 东道国拥有这些关切和任何准备状态检查或复议,然后才援引商务.
主机配置
对于一个可替代的 API 源,通过一个明确的服务器控制选项. 它必须是没有证书、路径、查询或片段的HTTPS来源。 主办方负责信任接收OAuth证书的目的地. 请求机构从不选择API来源或归属.
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页:1POST /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_FAILED404 当命令API报告命令缺失时(404) NOT_FOUND)或命令属于另一个商店或频道. 没有这个代码的404,例如来自错误配置的API基础URL,是一个上游失败. Token 和其他商业故障,包括不同订单ID的响应,返回 502 和不可读配置返回 503(见 错误) (中文(简体) ). 主机必须认证呼叫者,并授权访问所请求的每个命令后,才能曝光这条路线.
连接状态
主机可以执行可选同步 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_* 变量.
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 错误代码
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,当一个主机有多个本套件副本时失败.