> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rekomi

> 在您的 Dodo Payments 商店上运行联盟计划。只需粘贴一个 API key 即可连接两者，Rekomi 会跟踪销售并向您的联盟伙伴付款。

## 简介

[Rekomi](https://rekomi.com) 是一个 affiliate tracking and management platform，原生集成 Dodo Payments。Affiliate 分享链接后，Rekomi 会记录点击。当访客购买时，Dodo Payments 会将销售信息发送给 Rekomi，由 Rekomi 将销售归因给正确的 affiliate。Rekomi 会计算 commission，并代表你向 affiliates 付款，覆盖 150 多个国家/地区，且包含税务表单。

要进行连接，你只需将一个具有 write access 的 Dodo Payments API key 粘贴到 Rekomi 中。Rekomi 会验证该 key，在你的 Dodo Payments 账户中创建 webhook endpoint，并获取该 endpoint 的 signing secret。你无需填写 webhook 表单，也无需将任何内容粘贴回 Dodo Payments。

> [!NOTE]
>
> 当被推荐的客户完成一次性付款、开始付费订阅或支付续费时，Rekomi 会将销售归因给 affiliate。发生退款和争议时，commission 会自动追回。

## 工作原理

Dodo Payments 在自己的域名上托管 checkout，因此联盟推荐信息会作为 checkout metadata 进入销售记录：

1. 访客点击 affiliate 链接并进入你的网站，Rekomi script 会将推荐信息存储在其浏览器中。
2. 在 checkout 时，你会将该推荐信息作为 `rekomi_ref` metadata 添加到 payment 中。
3. Dodo Payments 处理 payment，并向 Rekomi 创建的 endpoint 发送带签名的 `payment.succeeded` webhook。
4. Rekomi 将推荐信息与 affiliate 匹配，按未含税销售金额计算 commission，并记录该信息。

Subscription renewals 也会以相同方式到达，因此 recurring commissions 无需额外操作。Refunds 和 disputes 也会通过同一 endpoint 到达。

## 前提条件

在设置此集成之前，你需要：

1. 一个处于 live mode 的 [Dodo Payments 账户](https://app.dodopayments.com)
2. 一个 [Rekomi 账户](https://app.rekomi.com/sign-up)
3. 一个已启用 **write access** 的 Dodo Payments API key，因为 read-only keys 无法创建 webhooks

## 开始使用

**1. Create an API Key with Write Access**

> [!WARNING]
>
> 为该 key 启用 write access。Read-only key 可以通过验证，但无法创建 webhook endpoint，因此连接会在中途失败。

在 Dodo Payments dashboard 中，前往 **Developer → API Keys**，然后点击 **Add API Key**。将 key 命名为 `Rekomi`，并保持勾选 **Enable write access**。详情请参阅 [Authentication](/api-reference/introduction#authentication)。

**2. Paste the Key into Rekomi**

在 Rekomi 中打开 **Setup → Connect payment processor**，选择 Dodo Payments，然后粘贴 key。Rekomi 会验证该 key，在你的账户中创建 webhook endpoint，并获取该 endpoint 的 signing secret。

![Rekomi 的 Dodo Payments 设置页面，其中包含单个 API key 字段和连接按钮](https://mintcdn.com/dodopayments/ic2bWXoH5_Rw-GN5/images/integrations/rekomi/connect.png?fit=max\&auto=format\&n=ic2bWXoH5_Rw-GN5\&q=85\&s=2271768fc16cecec3196c8006e0c73ab)

> [!NOTE]
>
> 连接后，Rekomi 仅使用该 key 管理 webhook endpoint 并定期执行 health checks。你的销售数据会通过带签名的 webhook 到达，而不是通过 API 到达。

**3. Install the Rekomi Script**

将 Rekomi tracking script 添加到你的 marketing site，以捕获 affiliate clicks。Rekomi 会在 **Setup → Install** 下显示你的 snippet，并自动填入 program ID。

```html theme={null}
<script
  async
  src="https://api.rekomi.com/api/v1/r/loader.js"
  data-program-id="YOUR_PROGRAM_ID"
></script>
```

**4. Pass the Referral into Checkout**

将捕获的推荐信息作为 `rekomi_ref` metadata 添加到每个 payment 中。[Implementation Guide](#implementation-guide) 介绍了每种 checkout 类型的操作方式。

**5. Done**

Sales、renewals、refunds 和 disputes 现在会自动为 affiliate credit 和 claw back commissions，Rekomi 会向你的 affiliates 付款。

## 实现指南

### 通过 API 使用 Checkout Sessions

在 frontend 中，使用 `window.Rekomi.getReferral()` 读取推荐信息，并在 checkout request 中将其发送到 backend。在 backend 中，将其设置到 `metadata`：

```typescript Node.js theme={null}
import DodoPayments from 'dodopayments';

// Reads DODO_PAYMENTS_API_KEY from the environment and defaults to live mode.
const client = new DodoPayments();

export async function createCheckout(productId: string, rekomiRef?: string) {
  const session = await client.checkoutSessions.create({
    product_cart: [{ product_id: productId, quantity: 1 }],
    customer: {
      email: 'customer@example.com',
      name: 'John Doe',
    },
    return_url: 'https://yoursite.com/success',
    metadata: {
      ...(rekomiRef ? { rekomi_ref: rekomiRef } : {}),
    },
  });

  return session.checkout_url;
}
```

相同的 `metadata.rekomi_ref` field 也适用于 subscription products，因此首次收费和每次续费都会将销售归因给同一个 affiliate。

### Payments API

> [!NOTE]
>
> 下面的示例使用 `POST /payments`，该方式已被标记为 **deprecated**。它仍适用于现有集成。新集成应使用 [Checkout Sessions](/developer-resources/checkout-session)（`POST /checkouts`），并以相同方式使用 `metadata`。

```typescript Node.js theme={null}
import DodoPayments from 'dodopayments';

// Reads DODO_PAYMENTS_API_KEY from the environment and defaults to live mode.
const client = new DodoPayments();

export async function createPayment(productId: string, rekomiRef?: string) {
  const payment = await client.payments.create({
    billing: {
      city: 'New York',
      country: 'US',
      state: 'NY',
      street: '123 Main St',
      zipcode: '10001',
    },
    customer: {
      email: 'customer@example.com',
      name: 'John Doe',
    },
    product_cart: [{ product_id: productId, quantity: 1 }],
    payment_link: true,
    metadata: {
      ...(rekomiRef ? { rekomi_ref: rekomiRef } : {}),
    },
  });

  return payment;
}
```

### 静态 Payment Links

将推荐信息作为扁平的 `metadata_rekomi_ref` query parameter 添加到链接中，而不是使用括号形式：

```javascript theme={null}
const ref = window.Rekomi?.getReferral?.();
let url = 'https://checkout.dodopayments.com/buy/YOUR_PRODUCT_ID';
if (ref) url += `?metadata_rekomi_ref=${encodeURIComponent(ref)}`;
// use url as the href on your Buy button
```

Dodo Payments 会将 `metadata_*` query parameters 添加到 payment 的 metadata 中，Rekomi 会从中读取这些参数。

## 跟踪内容

Rekomi 对每种 sale event 的处理方式如下：

| Event | What happens |
| - | - |
| One-time payment | 在未含税销售金额上计入 commission |
| Subscription renewal | Recurring commission，每次收费都会作为独立的 payment event 到达 |
| Refund | 自动追回 commission，最多追回已计入的金额 |
| Dispute | dispute 开始后立即追回 commission |

> [!TIP]
>
> Rekomi 按未含税销售金额计算 commissions。Dodo Payments 是 Merchant of Record 并负责收取税费，因此 affiliates 的收益来自销售本身，而不是买方所在国家/地区加收的税费。

## 重要说明

* Rekomi 会仅使用所需的 events 注册 webhook endpoint。请勿在 Dodo Payments dashboard 中编辑该 endpoint 的 event list：如果移除 events，Rekomi 的 health checks 会将该连接标记为异常。
* Free trial 在试用结束前不会创建 payment，因此在首次收费前不会产生 commission。[Paid trial](/features/subscription#paid-trials) 会预先收取试用金额。
* 在 Rekomi 中断开连接会从你的 Dodo Payments 账户中删除 webhook endpoint。

## 其他资源

> **[Rekomi's Dodo Payments Guide](https://rekomi.com/docs/brands/install/dodo)**
>
> Rekomi 文档中的完整设置指南、故障排除和安全详情。

> **[Affiliates Feature Guide](/features/affiliates)**
>
> Dodo Payments 的所有 affiliate integration 选项。

> [!NOTE]
>
> 如需集成帮助，请通过 [support@rekomi.com](mailto:support@rekomi.com) 联系 Rekomi support，或通过 [support@dodopayments.com](mailto:support@dodopayments.com) 联系 Dodo Payments support。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.