billing-integration

Credyt 集成

优先使用官方 SDK（TypeScript 使用 @credyt/api-client，Python 使用 credyt-api），而不是手动编写 HTTP 调用——它们会为你处理身份验证、重试和字段映射。如果这两个 SDK 都不适合你的技术栈（例如使用 TypeScript 或 Python 以外的语言），下文也介绍了直接调用 HTTP 的方式。如果你来到这里时还没有先运行 billing-setup，请停下并让用户先运行该技能，再继续操作。

帮助用户将 Credyt 接入其应用代码。此技能会配合用户的实际代码库使用——读取现有代码，并在合适的位置添加 Credyt 集成。

完整集成指南见 docs.credyt.ai/ai-integration.md。下方各部分均链接到对应的文档页面，其中包含 HTTP、TypeScript 和 Python 示例——如果需要了解任何集成领域的更多详情，请查阅这些文档。

字段命名： Credyt API 的所有字段均使用 snake_case。TypeScript SDK 会自动将其映射为 camelCase。Python SDK 保留 snake_case。链接文档中的代码示例展示了这三种形式。

先了解代码库

编写任何代码之前，先了解用户当前的项目：

“我先查看一下你的项目，了解你使用的技术栈，以及账单功能应当接入的位置。”

检查以下内容：

• 语言和框架（Node/Express、Next.js、Python/FastAPI 等）
• 身份验证设置（用户如何注册和登录）
• 代码中产生计费活动的位置
• 现有的环境变量使用方式

选择集成方式

根据上下文确定合适的方式——只有确实无法判断时才询问用户。

自动检测（按顺序）：

1. 已知 AI 平台——Lovable、Bolt、Replit 和 V0 默认都使用 TypeScript。如果在其中一个平台上运行，请使用 TypeScript SDK。
2. 现有技术栈——检查上文扫描的代码库。package.json → TypeScript/Node.js SDK。requirements.txt 或 pyproject.toml → Python SDK。
3. 不明确 → 询问：“你使用的是 TypeScript/Node.js、Python，还是其他语言？” 并优先向用户介绍前两种语言对应的 SDK 选项。

确定后，说明建议方案，并在编写任何代码前让用户选择是否改用其他方案：

“根据你的技术栈，我会使用 TypeScript SDK（@credyt/api-client）。如果你更想使用 Python 或直接调用 HTTP，请告诉我。”

SDK 包：

• TypeScript/Node.js → @credyt/api-client（npm install @credyt/api-client）
• Python → credyt-api（pip install credyt-api）
• 其他语言或偏好原始 HTTP → 使用 X-CREDYT-API-KEY 标头直接调用 API

包含这三种方式示例的完整 SDK 参考见 docs.credyt.ai/sdk。

集成领域

逐一介绍每个领域。并非每个用户都需要全部内容——询问用户需要哪些。

1. API 密钥设置

Credyt API 密钥必须安全地存储在服务器端——切勿放在浏览器中运行的代码里。

将 CREDYT_API_KEY 添加到环境变量中，与其他密钥一并保存，然后初始化一次客户端，并在各个请求之间重复使用。

TypeScript：

import { CredytApiClient } from "@credyt/api-client";
const client = new CredytApiClient({ key: process.env.CREDYT_API_KEY! });

Python：

from corehttp.credentials import ServiceKeyCredential
from credytapi import CredytApiClient

client = CredytApiClient(
    credential=ServiceKeyCredential(key=os.getenv("CREDYT_API_KEY")),
)

直接调用 HTTP： 在每个请求中附加 X-CREDYT-API-KEY: <key>。创建一个辅助函数或配置好的 HTTP 客户端实例，以便自动设置此标头。

2. 创建客户 — 文档

当新用户在其应用中注册时，创建对应的 Credyt 客户。找到注册/Signup 处理程序，并在账户成功创建后添加客户创建逻辑。

要点：

• 使用 external_id 将 Credyt 客户关联到其应用中的用户 ID
• 创建时为客户订阅相关产品
• 将 Credyt 客户 ID 与用户记录一起存储在其数据库中
• 处理客户已存在的情况（409/422 — 改为通过 external_id 查询）

SDK 方法： client.customers.create(...)

定期固定费用 — 待处理订阅

如果产品使用定期固定费用（例如每月 $20），客户必须先付款，订阅才能激活。在这种情况下，API 会返回 pending 状态，而不会立即激活订阅。

在订阅上设置 return_url、failure_url 和 redirect_to，让 Credyt 知道付款后应将客户发送到哪里：

• return_url — 成功付款后发送客户的地址（例如 https://yourapp.com/account）
• failure_url — 付款失败时发送客户的地址（例如 https://yourapp.com/callbacks/payment-failed）
• redirect_to — 设置为 "return_url"，这样客户会返回您的网站，而不是停留在 Credyt 账单门户中（这是默认值，但请显式设置）

当响应状态为 pending 时：

• 检查 required_actions 数组，找到 type: "payment" 的操作，并提取其 redirect_url
• 将客户重定向到该 URL — Credyt 会处理付款表单，并自动将客户转到您的 return_url 或 failure_url
• 暂时不要激活用户账户 — 在数据库中将其保存为待处理状态，直到确认付款
• 如果客户完成付款前重定向链接过期，请通过其 Credyt ID 获取客户，以取得刷新后的链接

客户付款后，Credyt 会触发 subscription.activated webhook。在后端监听此事件，并据此激活用户账户。

促销或捆绑注册赠金

如果用户的套餐包含促销赠金（例如“注册即获 $10 免费额度”）或捆绑赠金（例如注册时赠送 1,000 次免费 API 调用），有两种方式可以发放：

1. 创建客户后单次调整 — 注册后直接向客户的钱包添加额度。适用于简单的一次性促销额度。参见 docs.credyt.ai/advanced-topics/adjustments-charges-gifts。
2. 权益 — 将促销额度配置为产品定义的一部分，使其在每次新订阅时自动生效。适用于标准套餐中包含的额度。参见 docs.credyt.ai/features/product-catalog/entitlements。

询问用户是否要包含注册赠金；如果要，询问哪种方式适合他们的使用场景。

3. 使用事件跟踪 — 文档

找到代码中发生可计费活动的位置，并在每次活动后添加事件提交。每个事件需要包含：

• 唯一 ID（UUID），以确保同一事件不会被重复计费
• 与产品配置相匹配的正确 event_type
• 事件发生的时间戳（occurred_at）
• 定价所需的所有数据字段（用量字段、维度）

SDK 方法： client.events.sendUsage(...)（TS）或 client.events.send_usage(...)（Python）。

对于基于用量的产品，事件数据必须包含用量字段（例如 total_tokens: 1500）。 对于基于维度的产品，请包含维度值（例如 model: "gpt-4"）。

4. 成本跟踪 — 文档

如果用户已在 /credyt:billing-setup 中设置供应商，请将成本数据添加到使用事件中。每个事件都可以包含一个 costs 数组，其中包含供应商 ID、成本金额和货币。

通常会在计费操作完成后、得知成本时添加这些数据（例如，收到包含 token 数量的 AI API 响应后）。

“即使你还没有向用户收费，将成本关联到每个事件也能让 Credyt 计算单位经济效益，帮助你根据真实数据制定定价决策。”

5. 余额检查 — 文档

在执行高成本操作前，检查客户的钱包余额。如果余额不足，则阻止操作并提示用户充值。

SDK 方法： client.wallets.customerWalletOps.getCustomerWallet(customerId) 用于获取完整钱包，或使用 client.wallets.customerWalletOps.getAccount(customerId, "accountName:ASSET") 检查特定账户余额。

找到发起计费操作的位置（API 路由、按钮处理程序等），并在操作运行前添加余额检查。如果余额过低，请返回清晰的提示信息。

估算即将执行的操作的成本，并与可用余额进行比较。

6. 账单门户 / 充值界面 — 文档

通过 Credyt 的账单门户帮助用户充值。这是处理付款最简单的方式：Credyt 托管页面、处理 Stripe 付款，并将用户重定向回其应用。

在应用的设置页或账户页中添加“账单”或“充值”链接/按钮。用户点击后，后端会创建账单门户会话，并将用户重定向到相应 URL。

SDK 方法： client.billingPortal.createPortalSession(...)

要点：

• 门户会话会在 10 分钟后过期
• 设置 return_url，指定用户完成操作后要跳转到的位置
• 设置 failure_url，用于处理付款失败

7. 余额显示 — 文档

在应用界面中显示用户的当前余额。从钱包端点获取余额，并显示可用金额。

SDK 方法： client.wallets.customerWalletOps.getCustomerWallet(customerId)。

确定在应用中的哪个位置显示余额——侧边栏、页眉或账户页——然后将其添加到该位置。

实施方法

不要一次性输出所有代码。逐项完成：

1. 从 API 密钥设置和创建客户开始——这是基础
2. 然后添加使用事件跟踪——这是计费集成的核心
3. 添加余额检查，以限制高成本操作
4. 添加账单门户和余额显示，完成面向用户的部分
5. 最后添加成本跟踪（如适用）

每完成一项后，都建议用户进行测试：

“试着在应用中创建一个新账户，并检查 Credyt 控制面板——你应该会看到一个新客户。然后我们再继续处理使用情况跟踪。”

参考资料

如需详细代码示例、错误处理模式和高级主题（混合计费、退款、自动充值），请引导用户查阅：

• SDK 参考（TypeScript 和 Python）：docs.credyt.ai/sdk
• 完整集成指南：docs.credyt.ai/ai-integration.md
• API 参考：docs.credyt.ai
• 示例：github.com/credyt/learn