# @craftgate/craftgate 中文文档

规范地址：https://npmcn.com/package/%40craftgate/craftgate/

版本：1\.0\.72
npm 元数据更新时间：2026-10-20T10:26:34.531Z
中文译文更新时间：2026-11-10T22:55:51.427Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：910 kB，1142 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2021-01-21T08:46:21.574Z
- 最新版本发布：2026-10-20T10:26:33.116Z
- 近 30 天下载量：26756（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：73（近 12 个月 8 个）

## 中文简介

手动Gate API JavaScript 客户端

## 安装

```sh
npm install @craftgate/craftgate
```

也可以使用：`pnpm add @craftgate/craftgate`、`yarn add @craftgate/craftgate`、`bun add @craftgate/craftgate`

## README

# 手动门节点.js 客户端

[![Build Status](https://github.com/craftgate/craftgate-node-client/actions/workflows/craftgate-build.yml/badge.svg?branch=master)](https://github.com/craftgate/craftgate-node-client/actions?query=branch%3Amaster) [![Version](https://img.shields.io/npm/v/@craftgate/craftgate.svg)](https://www.npmjs.com/package/@craftgate/craftgate) [![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/craftgate/craftgate-node-client)

这个repo包含了Craftgate API的Node.js客户端.

[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/craftgate/craftgate-node-client)

## 所需资源

-   节点.js v4.x+
    -   如果您计划使用这个库与更古老的节点版本( 如 v0. 10. x), 您只需要包含一个 `Promise` 诸如 [蓝鸟](https://github.com/petkaantonov/bluebird)

## 安装

```bash
$ npm install @craftgate/craftgate
```

## 使用量

要访问 Craftgate API, 您首先需要获得API 证书( 例如 API 密钥和密钥) 。 如果你还没有手工业门账户,你可以注册到 [https://craftgate.io (英语)](https://craftgate.io/)

一旦你获得了API的证书, 你可以开始使用手工业门 通过即时 `CraftgateClient` 带着你的证书.

```js
const Craftgate = require('@craftgate/craftgate');

const craftgate = new Craftgate.Client({
  apiKey: '<YOUR API KEY>',
  secretKey: '<YOUR SECRET KEY>'
});

...
```

默认情况下, Craftgate 客户端连接到 API 服务器 `https://api.craftgate.io`为测试目的,请使用沙盒 URL `https://sandbox-api.craftgate.io`。 。 。 .

```js
const Craftgate = require('@craftgate/craftgate');

const craftgate = new Craftgate.Client({
  apiKey: '<YOUR API KEY>',
  secretKey: '<YOUR SECRET KEY>',
  baseUrl: 'https://sandbox-api.craftgate.io'
});

...
```

### 批量进口与个人进口

项目的根导出( 例如 ) . `@craftgate/craftgate`)主要为通用JS型批量进口而设计,但项目也单独地输出其模块,因此也可以以ES6方式直接导入. 关于存在Babel或TypeScript等转接器的发展环境,我们建议采用这种方法.

牢记在使用直接进口时,必须单独地进口必要的模块. 所以这个代码:

```js
const Craftgate = require('@craftgate/craftgate');

const craftgate = new Craftgate.Client({...});

craftgate.payment().createPayment({
  ...,
  currency: Craftgate.Model.Currency.TRY,
  ...
})
...
```

变成这样:

```js
import CraftgateClient from '@craftgate/craftgate/CraftgateClient';
import Currency from '@craftgate/craftgate/model/Currency';

const craftgate = new CraftgateClient({...});

craftgate.payment().createPayment({
  ...,
  currency: Currency.TRY,
  ...
})
...
```

另外,由于我们使用默认导出,如果您希望直接以CommonJS时态导入这些模块(例如. `require()`),然后确保您正在访问 `default` 模块关键词.

```js
const CraftgateClient = require('@craftgate/craftgate/CraftgateClient'); // this won't work

...

const CraftgateClient = require('@craftgate/craftgate/CraftgateClient').default; // however, this will
```

## 实例

该项目包括一些几乎涵盖所有使用案例的例子。 参见 [页:1 `samples/` 文件夹](https://npmcn.com/package/%40craftgate/craftgate/samples) 需要更多信息.

除了展示不同的商业使用案例外,我们还增加了技术上不同的某些实例的变体,以反映技术堆栈的多样性。 这些例子见以下表 [样品/微分](https://npmcn.com/package/%40craftgate/craftgate/samples/misc) 文件夹,以及它们所代表的内容由下面列出的文件名后缀表示:

| 文件名后缀 | 说明 |
| --- | --- |
| `.es5.js` | ES5风格的JavaScript代码,并带有散装ConferenceJS导入(例如. `var` 变量关键词, `require()` 导入关键字, 内置 `function()` 块) |
| `.es6.js` | ES6风格的JavaScript代码有ES6导入(例如. `let/const` 变量关键词, `import` 进口关键词, lambda 表达式) |
| `.ts` | 类型脚本代码 |
| `.js` | 节点.js v6+(ES6-风格的JavaScript代码,有直接的CommonJS导入) (例如. `let/const` 变量关键词, `require()` 进口关键词, lambda 表达式) |

### 运行示例

如果您在您的开发机上克隆了此重播, 并且希望直接运行示例, 请确保使用 `npm i` 并使用 `npm run build`,然后替换 `apiKey` 财务报告和审定财务报表 `secretKey` 中包含您的沙盒证书。 一旦库建成,您就可以使用命令运行示例 `node <example path>` (例如:. `node samples/payment/RetrievePayment.js`) (中文(简体) ).

记住 `node` 解释器不能用于执行 TypeScript 文件,而 `ts-node` 能够。 这个解释器不与Node.js本身同船,所以你要么必须在全球安装在你的机器上,要么把它作为依赖物纳入你的工程. 这个存放处已经将它列为一个非常依赖的机构,并把它作为国家预防机制的任务加以揭露 `ts-node`,所以要运行 TypeScript 示例,你可以简单地执行命令 `npm run ts-node <example path>` (例如:. `npm run ts-node samples/misc/CreatePayment.ts`) (中文(简体) ).

### 信用卡支付使用案(ES5-Style)

让我们快速审查一个例子,我们用ES5型方法实施信用卡支付方案

> 关于涵盖几乎所有使用案例的更多实例,请检查 [实例 `samples/` 文件夹](https://npmcn.com/package/%40craftgate/craftgate/samples)

```js
var Craftgate = require('../dist');

var craftgate = new Craftgate.Client({
  apiKey: 'api-key',
  secretKey: 'secret-key',
  baseUrl: 'https://sandbox-api.craftgate.io'
});

var request = {
  price: 100.0,
  paidPrice: 100.0,
  walletPrice: 0.0,
  installment: 1,
  conversationId: '456d1297-908e-4bd6-a13b-4be31a6e47d5',
  currency: Craftgate.Model.Currency.TRY,
  paymentGroup: Craftgate.Model.PaymentGroup.ListingOrSubscription,
  card: {
    cardHolderName: 'Haluk Demir',
    cardNumber: '5258640000000001',
    expireYear: '2044',
    expireMonth: '07',
    cvc: '000'
  },
  items: [
    {
      name: 'Item 1',
      price: 30.0,
      externalId: '123d1297-839e-4bd6-a13b-4be31a6e12a8'
    },
    {
      name: 'Item 2',
      price: 50.0,
      externalId: '789d1297-839e-4bd6-a13b-4be31a6e13f7'
    },
    {
      name: 'Item 3',
      price: 20.0,
      externalId: '3a1d1297-839e-4bd6-a13b-4be31a6e18e6'
    }
  ]
};

craftgate.payment().createPayment(request)
  .then(function(result) {
    console.info('Payment successful', result);
  })
  .catch(function(err) {
    console.error('Payment failed', err);
  });
```

## 目 录

突变操作接受可选的一等分量键. 设定在请求对象上,客户端按 `x-idempotency-key` 页眉,所以一个请求可以安全地被重试(如超时后)而不进行两次操作——服务器在看到重复的密钥时返回第一个请求的结果.

每个请求类型包括: `BaseRequest`,带有 `headerOptions` 对象,所以在任何请求中都可以使用此密钥 :

```javascript
const { randomUUID } = require('crypto');

craftgate.payment().createPayment({
  price: 100.0,
  paidPrice: 100.0,
  currency: Craftgate.Model.Currency.Turkish_Lira,
  paymentGroup: Craftgate.Model.PaymentGroup.ListingOrSubscription,
  headerOptions: {idempotencyKey: randomUUID()},
  // ... other fields
});
```

在 URL 路径中存在参数的操作也会带一个请求对象,这样也可以携带一个密钥:

```javascript
craftgate.payment().expireCheckoutPayment({
  token: '456d1297-908e-4bd6-a13b-4be31a6e47d5',
  headerOptions: {idempotencyKey: randomUUID()}
});
```

> 每次不同的操作使用一新密钥,在重试该操作时再使用同一密钥.

> API 尊重在 `POST`, (中文(简体) ), `PATCH` 财务报告和审定财务报表 `DELETE` 只有这个 它被忽视了 `PUT` 端点,所以重试其中之一,不是去重复.

`headerOptions` 仅作为信头发送——它从未出现在请求正文、查询字符串或请求签名中。 您的请求对象没有被修改, 因此您可以再次通过同样的对象来重试 .

## 发展

为协助该项目,请参见我们的准则: [捐款](https://npmcn.com/package/%40craftgate/craftgate/CONTRIBUTING.md)通过参加这个项目,你同意遵守我们 [行为守则](https://npmcn.com/package/%40craftgate/craftgate/CODE_OF_CONDUCT.md)。 。 。 .

## 警卫

如果你发现安全漏洞 请检查一下我们 [安全政策](https://npmcn.com/package/%40craftgate/craftgate/SECURITY.md) 如何负责任地报告.

## 许可证

这个项目根据Apache许可证第2.0版获得许可 [自由主义](https://npmcn.com/package/%40craftgate/craftgate/LICENSE) 财务报告和审定财务报表 [通知](https://npmcn.com/package/%40craftgate/craftgate/NOTICE.md) 详细文件.

## 常见问题

### @craftgate/craftgate 是什么？

手动Gate API JavaScript 客户端

### 如何安装 @craftgate/craftgate？

在项目目录运行 npm install @craftgate/craftgate，或使用 pnpm add / yarn add / bun add。

### @craftgate/craftgate 支持 TypeScript 吗？

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

### @craftgate/craftgate 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @craftgate/craftgate 可以商用吗？

@craftgate/craftgate 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @craftgate/craftgate 的下载量有多少？

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

### @craftgate/craftgate 还在维护吗？

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