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

# Partner Direct Link (TP Lite)

> 作为 YCloud 技术合作伙伴，无需成为 Meta 合作伙伴，即可通过托管链接或 SDK 按钮为 WhatsApp 客户办理入驻。

Partner Direct Link (TP Lite) 是面向 YCloud 技术合作伙伴的一种集成选项。您需要联系 YCloud 为您的账户启用该功能，但无需成为 Meta 合作伙伴。

在您的服务器上创建短期有效的入驻链接。您的客户可以直接打开该链接，也可以通过您网站上的按钮打开。建议先使用 Direct Link 测试集成，若希望客户在弹窗中完成注册，后续可改用 SDK 按钮。

## 集成概述

1. **准备账户。** 联系 YCloud 启用 Partner Direct Link、创建 API 密钥并配置您的 Webhook 接收端。
2. **配置入口点。** 在控制台中打开 Partner Direct Link，设置您的品牌信息、重定向 URL 或 SDK 来源。
3. **创建链接。** 您的服务器为您系统中的客户请求入驻链接。
4. **让客户进行连接。** 客户打开托管页面或 SDK 弹窗并完成 Meta 授权。
5. **确认结果。** 您的后端接收 Webhook 并将 WABA 与客户关联。

## 开始之前

1. 联系 YCloud 为您的账户启用 Partner Direct Link。如果您还不是技术合作伙伴，请[申请成为合作伙伴](https://www.ycloud.com/tech-partner)。
2. 在 **开发者 > API 密钥**中创建 API 密钥。
3. 在 **开发者 > Webhooks** 中配置接收端并订阅 `whatsapp.business_account.updated`。

<Warning>
  从您的服务器调用链接创建 API。切勿将 API 密钥放入浏览器或移动应用代码中。请将每个入驻 URL 视为临时凭证：避免将其暴露在公开页面、分析工具及公开日志中。
</Warning>

## 在控制台中查找 Partner Direct Link

1. 打开已启用 Partner Direct Link 的账户对应的 YCloud 控制台。
2. 展开左侧边栏中的 **开发者** 。
3. 点击 **Partner Direct Link** 打开配置页面。

<Frame caption="Open Developers > Partner Direct Link to configure your branding and entry point. This example shows the settings before configuration.">
  <img src="https://mintcdn.com/lchnan/vUKSC8TUE8OdyQKj/product-assets/partners-2026-09-28/partner-direct-link-settings.png?fit=max&auto=format&n=vUKSC8TUE8OdyQKj&q=85&s=93ba5518df8a7af5c2364f8e41e8defe" alt="带有基础设置和托管注册预览的 Partner Direct Link 页面" width="3024" height="1656" data-path="product-assets/partners-2026-09-28/partner-direct-link-settings.png" />
</Frame>

该页面包含用于配置品牌信息的 **基础设置** ，以及用于创建链接、集成入口点和订阅 Webhook 的 **集成** 。使用 **托管页面预览** 可查看面向客户的页面。

## 配置您的品牌信息与入口点

在 YCloud 控制台中打开 **开发者 > Partner Direct Link** 。完成 **基础设置**：

| 设置 | 要求 | 用途 |
| - | - | - |
| **显示名称** | 必填 | 托管注册页面上显示的合作伙伴名称。 |
| **合作伙伴 Logo** | 可选 | 托管注册页面上显示的您的 Logo。 |
| **重定向 URL（仅限 Direct Link）** | 可选 | 注册成功后打开的完整 HTTPS URL。如果不提供，客户将看到带有您品牌信息的成功页面。 |
| **允许的 SDK 来源（仅限 SDK 按钮）** | SDK 按钮必填 | 加载 SDK 的页面来源，例如 `https://app.example.com`。 |

对于 SDK 来源，请输入精确的协议、域名和可选端口，不要包含路径。每个子域名或端口需单独添加；不支持通配符。生产环境中请使用 HTTPS。HTTP 仅允许用于 `localhost` 开发。Direct Link 无需配置允许的 SDK 来源即可工作；SDK 按钮则必须配置。

## 在您的服务器上创建入驻链接

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST 'https://api.ycloud.com/v2/partner/embeddedSignup/links' \
  -H 'X-API-Key: YOUR_YCLOUD_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "partnerCustomerId": "customer_001",
    "onboardingType": "WHATSAPP_BUSINESS_PLATFORM",
    "locale": "en_US"
  }'
```

| 字段 | 必填 | 描述 |
| - | - | - |
| `partnerCustomerId` | 是 | 您系统中固定的客户 ID。请避免包含敏感信息。YCloud 会在绑定成功的 Webhook 中返回此 ID。 |
| `onboardingType` | 是 | 如下所述，基于 API 的消息收发选择 `WHATSAPP_BUSINESS_PLATFORM`，Business App 共存模式选择 `WHATSAPP_BUSINESS_APP`。 |
| `locale` | 否 | 托管页面的语言。默认为 `en_US`。 |

* [**WhatsApp Business Platform**](/zh/documentation/whatsapp-business-platform/overview)（`WHATSAPP_BUSINESS_PLATFORM`）：选择此模式以连接号码，通过 API 和您的软件进行消息收发。
* [**WhatsApp Business App 共存**](/zh/documentation/whatsapp-business-platform/accounts-and-business-identity/whatsapp-business-app-coexistence)（`WHATSAPP_BUSINESS_APP`）：当客户希望继续使用现有符合条件的 Business App 号码并在同一号码上增加 API 消息收发时，请选择此模式。

支持的语言区域包括 `en_US`（英语）、`zh_CN`（简体中文）、`es_ES`（西班牙语）、`pt_BR`（巴西葡萄牙语）、`id_ID`（印度尼西亚语）和 `ru_RU`（俄语）。取值区分大小写。其他值将返回 HTTP 400。

响应示例：

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "onboardingUrl": "https://connect.ycloud.com/open/whatsapp/onboard#token=EXAMPLE_TOKEN",
  "expiresAt": 1893456000000
}
```

`expiresAt` 为 Unix 毫秒时间戳格式的过期时间。默认链接有效期为两小时。每个链接将一位客户连接到一个 WABA。在完成注册之前，只要链接仍然有效，客户就可以刷新、重试或在另一个浏览器中打开该链接。绑定成功后，该链接不能再绑定其他 WABA。当客户需要更改或添加 WABA 时，请创建新链接。

## 方式 1：直接链接

在您的客户应用程序中添加连接按钮。当客户点击该按钮时，从您的服务器请求接入链接并跳转至 `onboardingUrl` 或在新窗口中打开。您也可以通过安全的一对一渠道私下将其发送给目标客户。

客户打开托管页面并点击 **Continue with Meta**。他们使用拥有管理其业务权限的 Facebook 账户，并在 Meta 中选择或创建其业务、WABA 和电话号码。YCloud 将完成绑定并显示结果。

<Frame caption="Direct Link integration and the hosted page preview. This example has no generated onboarding link.">
  <img src="https://mintcdn.com/lchnan/vUKSC8TUE8OdyQKj/product-assets/partners-2026-09-28/partner-direct-link-entry-point.png?fit=max&auto=format&n=vUKSC8TUE8OdyQKj&q=85&s=43d4aa490a7745834b3473c68d6d0fb4" alt="包含接入 URL 占位符和客户注册页面预览的 Direct Link 集成" width="3024" height="1656" data-path="product-assets/partners-2026-09-28/partner-direct-link-entry-point.png" />
</Frame>

如果您配置了重定向 URL，注册成功后将重定向到该地址，并附带 `status=connected` 查询参数。使用此参数更新面向客户的页面；使用下方的 Webhook 在您的后端确认绑定。

## 方式 2：SDK 按钮

将您页面的源（origin）添加到 **Allowed SDK origins**，然后加载 SDK。您的浏览器代码将调用您自己的后端来获取链接。下方的 `/api/ycloud/onboarding-link` 路由是您在服务器上实现的示例路由。

```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
<script src="https://connect.ycloud.com/open/sdk/v1.js"></script>
<button id="yc-onboarding" type="button">Continue with Meta</button>
<p id="yc-status" role="status"></p>

<script>
  const status = document.getElementById('yc-status');
  document.getElementById('yc-onboarding').addEventListener('click', async function () {
    try {
      const response = await fetch('/api/ycloud/onboarding-link', { method: 'POST' });
      if (!response.ok) throw new Error('Link creation failed');
      const { onboardingUrl } = await response.json();
      YCloudOnboarding.open({
        onboardingUrl,
        onStatus: function (result) {
          status.textContent = result.state === 'CONNECTED'
            ? 'WhatsApp connected. Confirming with your server.'
            : 'Signup is not complete. Follow the instructions in the signup window.';
        },
        onError: function (error) {
          status.textContent = error.code === 'POPUP_BLOCKED'
            ? 'Allow popups for this site, then try again.'
            : 'Unable to open signup. Request a new link.';
        },
        onClose: function () {
          status.textContent = 'Signup window closed before a final result.';
        }
      });
    } catch {
      status.textContent = 'Unable to create a signup link. Please try again.';
    }
  });
</script>
```

`onStatus(result)` 报告注册状态：

| 字段 | 含义 |
| - | - |
| `state` | `CONNECTED` 表示成功。其他值表示流程未完成或失败，例如 `RETRYABLE_FAILED`。 |
| `wabaId` | WABA ID，仅在成功时返回。 |
| `phoneNumberId` | Meta 电话号码 ID，成功时可能会返回。 |
| `errorCode` | 失败时可能返回的错误代码。 |
| `retryable` | 客户是否可以在当前注册窗口中重试。 |
| `requestId` | YCloud 请求 ID，排查问题时可提供给技术支持。 |

`onError(error)` 表示 SDK 无法打开注册页面。其 `code` 可以是 `POPUP_BLOCKED` 或 `INVALID_ONBOARDING_URL`。`onClose(event)` 仅在客户在获得最终结果前关闭窗口时触发，伴随 `reason: "USER_CLOSED"`。

这些回调用于更新您的前端。请使用服务端 Webhook 作为最终绑定结果。

## 通过 Webhook 确认绑定

<Frame caption="Subscribe to whatsapp.business_account.updated in Developers > Webhooks to receive the binding result.">
  <img src="https://mintcdn.com/lchnan/vUKSC8TUE8OdyQKj/product-assets/partners-2026-09-28/partner-direct-link-webhook.svg?fit=max&auto=format&n=vUKSC8TUE8OdyQKj&q=85&s=2655b86ea299e041f3bfd050d689c71e" alt="展示 whatsapp.business_account.updated Webhook 事件的 Partner Direct Link 集成步骤" width="3024" height="1656" data-path="product-assets/partners-2026-09-28/partner-direct-link-webhook.svg" />
</Frame>

绑定成功后，YCloud 会向您配置的 Webhook 接收端发送 `whatsapp.business_account.updated`。以下代码摘录展示了您集成所需的字段：

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "EXAMPLE_EVENT_ID",
  "type": "whatsapp.business_account.updated",
  "whatsappBusinessAccount": {
    "id": "EXAMPLE_WABA_ID",
    "updateEvent": "PARTNER_ADDED",
    "paymentMethodAttached": true,
    "partnerCustomerId": "customer_001"
  }
}
```

当 `updateEvent` 为 `PARTNER_ADDED` 时，将该 WABA 作为新增处理。将 `partnerCustomerId` 与您的客户进行匹配，并保存 WABA `id`。`paymentMethodAttached` 值为 `true` 表示额度附加成功；`false` 表示尚未完成。

使用事件 `id` 进行消息去重，并在成功接收后返回 HTTP 2xx。有关接收端设置，请参阅 [Webhooks](/zh/api-reference/guides/api-fundamentals/configure-webhooks)。

## Partner Direct Link 问题排查

| 现象 | 操作 |
| - | - |
| 客户关闭 Meta 或中断注册流程。 | 在原始链接仍然有效的情况下，再次点击 **Continue with Meta** 。 |
| 页面提示链接已过期或无效。 | 在您的服务器上创建新链接。 |
| SDK 提示源（origin）无效。 | 检查页面源是否完全匹配并包含在 **Allowed SDK origins** 中。 |
| 创建链接返回 HTTP 429。 | 等待 `Retry-After` 指定的时间段后再重试。避免频繁重复创建链接。 |
| 注册显示成功但您的系统未更新。 | 检查您的 Webhook 配置、事件订阅和接收端日志。请以 Webhook 作为最终结果。 |


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