# @useairfoil/producer-stripe 中文文档

规范地址：https://npmcn.com/package/%40useairfoil/producer-stripe/

版本：0\.0\.3
npm 元数据更新时间：2026-11-02T18:47:30.723Z
中文译文更新时间：2026-11-02T19:35:39.548Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：448 kB，46 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2026-08-13T16:59:09.968Z
- 最新版本发布：2026-11-02T18:47:28.914Z
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

此连接器同步Stripe客户、产品、价格、订阅、发票、收费和退款。它会回填每个资源，获取实时事件 `POST /webhooks/stripe`，并且每5分钟轮询Stripe Events API以恢复错过的webhook。

## 安装

```sh
npm install @useairfoil/producer-stripe
```

也可以使用：`pnpm add @useairfoil/producer-stripe`、`yarn add @useairfoil/producer-stripe`、`bun add @useairfoil/producer-stripe`

## README

# 条纹生产商

此连接器同步Stripe客户、产品、价格、订阅、 发票、费用和退款。它会回填每个资源，获取实时事件 `POST /webhooks/stripe`，并且每5分钟轮询一次Stripe Events API 恢复错过的webhook。

## 配置

| 变量 | 要求 | 默认的 |
| --- | --- | --- |
| `STRIPE_API_KEY` | 是 | 无 |
| `STRIPE_WEBHOOK_SECRET` | 是 | 无 |
| `STRIPE_RATE_LIMIT_PER_SECOND` | 否 | `20` |

速率限制由所有资源共享。条带限制每个帐户的请求； 因此，如果其他服务大量使用同一帐户，则降低它。

## 设置

创建一个 [受限API密钥](https://docs.stripe.com/keys/restricted-api-keys) 在仪表板中： **API密钥→创建密钥→构建自己的密钥 集成→自定义权限**． 集 **读** 就这七个许可和 其余的都不留下；

-   客户
-   产品
-   价格
-   订阅
-   发票
-   收费和退款
-   事件

使用该键作为 `STRIPE_API_KEY`。沙盒键读取沙盒数据和live Key读取实时数据，因此为每个键运行一个连接器。

为创建一个webhook端点 `/webhooks/stripe` 并使用其签名密钥为 `STRIPE_WEBHOOK_SECRET`。端点可以使用任何API版本。订阅：

-   `customer.created`， `customer.updated`， `customer.deleted`
-   `product.created`， `product.updated`， `product.deleted`
-   `price.created`， `price.updated`， `price.deleted`
-   `customer.subscription.created`， `.updated`， `.deleted`， `.paused`， `.resumed`， `.pending_update_applied`， `.pending_update_expired`
-   `invoice.created`， `.updated`， `.deleted`， `.finalized`， `.finalization_failed`， `.paid`， `.payment_succeeded`， `.payment_failed`， `.payment_action_required`， `.voided`， `.marked_uncollectible`， `.overpaid`
-   `charge.succeeded`， `.failed`， `.pending`， `.captured`， `.expired`， `.refunded`， `.updated`
-   `refund.created`， `refund.updated`， `refund.failed`， `charge.refund.updated`

连接器确认其他事件，但不存储它们。

## API版本

连接器引脚Stripe API版本 `2026-09-30.endive` 与 `Stripe-Version` 头。

## 数据

-   行是从API获取的，而不是从事件有效负载中获取的。行 Version是响应到达的时间。
-   删除的客户、产品、价格和发票草稿都标有 `_deleted`。取消的订阅将保持为一行 `status = canceled`.
-   客户、发票和收费包含客户数据：姓名、电子邮件、电话 号码，地址，以及卡的有效期，有效期和指纹。治疗这些 表作为客户数据。
-   在没有付款的情况下，Stripe会在受限钥匙上留下信用卡指纹 方法访问，所以 `payment_method_details.card.fingerprint` 可以是空的。
-   发票行项目尚未同步。
-   不支持测试时钟。测试时钟对象可以通过事件到达 但被排除在回填之外。用 `test_clock`.

## 限制

Stripe将事件保存30天。如果连接器落后29天， 所有资源的变化都停止了，它们需要一个新的回填。

一个Events API轮询涵盖所有资源。一篇文章最多可读20页。如果更多的 赛事正在等待，下一轮比赛马上开始。

轮询每个月大约使用9,000次读取，另外对每个更改的对象进行一次读取。 Stripe允许每个事务平均读取500次，其中至少有10,000次a 月，所以非常安静的帐户可以过去和节流。

## 演示数据

`pnpm demo --size 128MiB` 在没有条带键的情况下写入合成的条带数据。看到 连接器套件README中的标志和它需要的变量。

每个客户都有指向的订阅、发票、收费和退款 彼此之间有固定的8种产品目录和24种价格。 `products` 和 `prices` 不要随尺寸而变大。

## 地方发展

```bash
cd connectors/producer-stripe
pnpm sandbox
```

使用Stripe CLI转发测试webhook。 `stripe listen --print-secret` 打印要用作的签名秘密 `STRIPE_WEBHOOK_SECRET`。最近CLI 版本需要事件来转发，所以从Setup传递列表：

```bash
stripe listen --forward-to localhost:8080/webhooks/stripe \
  --events customer.created,customer.updated,invoice.paid,charge.refunded
stripe trigger customer.updated
```

要录录像机，放一个沙箱钥匙进去 `.env`、删除 `test/__cassettes__/api.vcr.test.cassette`，然后跑 `pnpm test:ci`。检查 新卡带提交前的客户详细信息。

承载运行从 `AIRFOIL_CONFIG_PATH`。它还需要 Connector Kit README中的Wings和PostgreSQL变量。

```bash
cd connectors/producer-stripe
pnpm start
```

## 常见问题

### @useairfoil/producer-stripe 是什么？

此连接器同步Stripe客户、产品、价格、订阅、发票、收费和退款。它会回填每个资源，获取实时事件 POST /webhooks/stripe，并且每5分钟轮询Stripe Events API以恢复错过的webhook。

### 如何安装 @useairfoil/producer-stripe？

在项目目录运行 npm install @useairfoil/producer-stripe，或使用 pnpm add / yarn add / bun add。

### @useairfoil/producer-stripe 支持 TypeScript 吗？

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

### @useairfoil/producer-stripe 支持 ESM 还是 CommonJS？

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

### @useairfoil/producer-stripe 可以商用吗？

@useairfoil/producer-stripe 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @useairfoil/producer-stripe 还在维护吗？

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