> ## 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)
> Подключайте клиентов WhatsApp в качестве Tech Partner YCloud с помощью размещенной ссылки или кнопки SDK без необходимости становиться партнером Meta.
Partner Direct Link (TP Lite) — это вариант интеграции для Tech Partner YCloud. Вам потребуется запросить активацию функции в YCloud для вашего аккаунта, однако становиться партнером Meta не требуется.
Создайте временную ссылку для онбординга на своем сервере. Клиент может открыть ее напрямую или с помощью кнопки на вашем сайте. Начните с Direct Link для тестирования интеграции, а затем используйте кнопку SDK, если хотите, чтобы клиенты проходили регистрацию во всплывающем окне.
## Обзор интеграции
1. **Подготовьте свой аккаунт.** Запросите у YCloud включение Partner Direct Link, создайте API-ключ и настройте обработчик Webhook.
2. **Настройте точку входа.** Откройте Partner Direct Link в панели управления и настройте брендинг, URL перенаправления или разрешенные источники SDK (origins).
3. **Создайте ссылку.** Ваш сервер запрашивает ссылку для онбординга клиента в вашей системе.
4. **Предоставьте клиенту возможность подключиться.** Клиент открывает размещенную страницу или всплывающее окно SDK и проходит авторизацию в Meta.
5. **Подтвердите результат.** Ваш бэкенд получает Webhook и связывает WABA с клиентом.
## Перед началом работы
1. Обратитесь в YCloud для включения Partner Direct Link для вашего аккаунта. Если вы еще не являетесь Tech Partner, [подайте заявку на участие в программе](https://www.ycloud.com/tech-partner).
2. Создайте API-ключ в разделе **Разработчикам > API-ключи**.
3. Настройте свой обработчик в разделе **Разработчикам > Webhook** и подпишитесь на `whatsapp.business_account.updated`.
Вызывайте API создания ссылок со своего сервера. Никогда не размещайте API-ключ в коде для браузера или мобильного приложения. Относитесь к каждому URL онбординга как к временным учетным данным: не публикуйте их на открытых страницах, в аналитике и общедоступных логах.
## Поиск Partner Direct Link в панели управления
1. Откройте панель управления YCloud для аккаунта, в котором включен Partner Direct Link.
2. Разверните раздел **Разработчикам** в левом боковом меню.
3. Нажмите **Partner Direct Link** , чтобы открыть страницу конфигурации.
Страница содержит **Основные настройки** для вашего брендинга и **Интеграцию** для создания ссылки, интеграции точки входа и подписки на Webhook. Используйте **Предпросмотр размещенной страницы** , чтобы увидеть интерфейс со стороны клиента.
## Настройка брендинга и точки входа
Перейдите в **Разработчикам > Partner Direct Link** в панели управления YCloud. Заполните **Основные настройки**:
| Параметр | Обязательность | Назначение |
| - | - | - |
| **Отображаемое имя** | Обязательно | Название вашей компании-партнера на размещенной странице регистрации. |
| **Логотип партнера** | Необязательно | Ваш логотип на размещенной странице регистрации. |
| **URL перенаправления (только для Direct Link)** | Необязательно | Полный URL-адрес по протоколу HTTPS для перехода после успешной регистрации. Если его не указать, клиенты увидят страницу успешного завершения с элементами вашего брендинга. |
| **Разрешенные источники SDK (только для кнопки SDK)** | Обязательно для кнопки SDK | Источники (origins) страниц, загружающих SDK, например `https://app.example.com`. |
Для источников SDK укажите точную схему, домен и (при необходимости) порт без пути. Добавляйте каждый поддомен или порт отдельно; подстановочные знаки (wildcards) не поддерживаются. В рабочей среде используйте 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` | Да | Постоянный идентификатор клиента из вашей системы. Избегайте конфиденциальной информации. YCloud возвращает этот идентификатор в Webhook об успешной привязке. |
| `onboardingType` | Да | Выберите `WHATSAPP_BUSINESS_PLATFORM` для отправки сообщений через API или `WHATSAPP_BUSINESS_APP` для совместного использования с Business App, как описано ниже. |
| `locale` | Нет | Язык размещенной страницы. По умолчанию используется `en_US`. |
* [**WhatsApp Business Platform**](/ru/documentation/whatsapp-business-platform/overview) (`WHATSAPP_BUSINESS_PLATFORM`): выберите этот режим для подключения номера и отправки сообщений через API и ваше программное обеспечение.
* [**Совместное использование с WhatsApp Business App**](/ru/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 timestamp в миллисекундах. Срок действия ссылки по умолчанию составляет два часа. Каждая ссылка подключает одного клиента к одному WABA. До завершения регистрации клиент может обновить страницу, повторить попытку или открыть ссылку в другом браузере, пока она остается действительной. После успешной привязки ссылку нельзя использовать для привязки другого WABA. Создайте новую ссылку, если клиенту необходимо изменить или добавить WABA.
## Вариант 1: Direct Link
Добавьте кнопку подключения в клиентское приложение. Когда клиент нажимает её, запросите ссылку для подключения у своего сервера и выполните переход на `onboardingUrl` или откройте её в новом окне. Вы также можете отправить её лично клиенту по безопасному каналу связи один на один.
Клиент открывает размещенную страницу и нажимает **Продолжить с Meta**. Он использует аккаунт Facebook с разрешением на управление своей компанией и выбирает или создает свою компанию, WABA и номер телефона в Meta. YCloud выполняет привязку и отображает результат.
Если вы настроили URL перенаправления, после успешной регистрации происходит перенаправление на него с добавлением `status=connected` в качестве query-параметра. Используйте это для обновления страницы на стороне клиента; используйте вебхук ниже, чтобы подтвердить привязку в вашем бэкенде.
## Вариант 2: Кнопка SDK
Добавьте origin вашей страницы в **Allowed SDK origins**, затем загрузите SDK. Код в браузере обращается к вашему бэкенду для получения ссылки. Маршрут `/api/ycloud/onboarding-link` ниже — это пример маршрута, который вы реализуете на своем сервере.
```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
```
`onStatus(result)` сообщает о статусе регистрации:
| Поле | Значение |
| - | - |
| `state` | `CONNECTED` означает успешное завершение. Другие значения указывают на незавершенный процесс или сбой, например `RETRYABLE_FAILED`. |
| `wabaId` | Идентификатор WABA, возвращается только при успешном завершении. |
| `phoneNumberId` | Идентификатор номера телефона Meta, который может возвращаться при успехе. |
| `errorCode` | Код ошибки, который может возвращаться в случае сбоя. |
| `retryable` | Может ли клиент повторить попытку в текущем окне регистрации. |
| `requestId` | Идентификатор запроса YCloud, который вы можете предоставить службе поддержки при устранении неполадок. |
`onError(error)` означает, что SDK не удалось открыть регистрацию. Его `code` может быть `POPUP_BLOCKED` или `INVALID_ONBOARDING_URL`. `onClose(event)` срабатывает только тогда, когда клиент закрывает окно до получения окончательного результата, с `reason: "USER_CLOSED"`.
Эти колбэки обновляют ваш фронтенд. Используйте серверный Webhook как окончательный результат привязки.
## Подтверждение привязки с помощью вебхука
YCloud отправляет `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](/ru/api-reference/guides/api-fundamentals/configure-webhooks) для настройки приемника.
## Устранение неполадок Partner Direct Link
| Признак | Действие |
| - | - |
| Клиент закрывает окно Meta или прерывает регистрацию. | Нажмите **Продолжить с Meta** еще раз, пока исходная ссылка остается действительной. |
| На странице сообщается об истекшей или недействительной ссылке. | Создайте новую ссылку на своем сервере. |
| SDK сообщает о недопустимом источнике (origin). | Убедитесь, что точный origin страницы указан в **Allowed SDK origins**. |
| Создание ссылки возвращает HTTP 429. | Подождите период, указанный в `Retry-After`, перед повторной попыткой. Избегайте многократного создания ссылок. |
| Регистрация завершилась успешно, но данные в вашей системе не обновились. | Проверьте настройки вебхука, подписку на события и логи приемника. Используйте вебхук в качестве окончательного результата. |
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.
Страница содержит **Основные настройки** для вашего брендинга и **Интеграцию** для создания ссылки, интеграции точки входа и подписки на Webhook. Используйте **Предпросмотр размещенной страницы** , чтобы увидеть интерфейс со стороны клиента.
## Настройка брендинга и точки входа
Перейдите в **Разработчикам > Partner Direct Link** в панели управления YCloud. Заполните **Основные настройки**:
| Параметр | Обязательность | Назначение |
| - | - | - |
| **Отображаемое имя** | Обязательно | Название вашей компании-партнера на размещенной странице регистрации. |
| **Логотип партнера** | Необязательно | Ваш логотип на размещенной странице регистрации. |
| **URL перенаправления (только для Direct Link)** | Необязательно | Полный URL-адрес по протоколу HTTPS для перехода после успешной регистрации. Если его не указать, клиенты увидят страницу успешного завершения с элементами вашего брендинга. |
| **Разрешенные источники SDK (только для кнопки SDK)** | Обязательно для кнопки SDK | Источники (origins) страниц, загружающих SDK, например `https://app.example.com`. |
Для источников SDK укажите точную схему, домен и (при необходимости) порт без пути. Добавляйте каждый поддомен или порт отдельно; подстановочные знаки (wildcards) не поддерживаются. В рабочей среде используйте 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` | Да | Постоянный идентификатор клиента из вашей системы. Избегайте конфиденциальной информации. YCloud возвращает этот идентификатор в Webhook об успешной привязке. |
| `onboardingType` | Да | Выберите `WHATSAPP_BUSINESS_PLATFORM` для отправки сообщений через API или `WHATSAPP_BUSINESS_APP` для совместного использования с Business App, как описано ниже. |
| `locale` | Нет | Язык размещенной страницы. По умолчанию используется `en_US`. |
* [**WhatsApp Business Platform**](/ru/documentation/whatsapp-business-platform/overview) (`WHATSAPP_BUSINESS_PLATFORM`): выберите этот режим для подключения номера и отправки сообщений через API и ваше программное обеспечение.
* [**Совместное использование с WhatsApp Business App**](/ru/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 timestamp в миллисекундах. Срок действия ссылки по умолчанию составляет два часа. Каждая ссылка подключает одного клиента к одному WABA. До завершения регистрации клиент может обновить страницу, повторить попытку или открыть ссылку в другом браузере, пока она остается действительной. После успешной привязки ссылку нельзя использовать для привязки другого WABA. Создайте новую ссылку, если клиенту необходимо изменить или добавить WABA.
## Вариант 1: Direct Link
Добавьте кнопку подключения в клиентское приложение. Когда клиент нажимает её, запросите ссылку для подключения у своего сервера и выполните переход на `onboardingUrl` или откройте её в новом окне. Вы также можете отправить её лично клиенту по безопасному каналу связи один на один.
Клиент открывает размещенную страницу и нажимает **Продолжить с Meta**. Он использует аккаунт Facebook с разрешением на управление своей компанией и выбирает или создает свою компанию, WABA и номер телефона в Meta. YCloud выполняет привязку и отображает результат.
Если вы настроили URL перенаправления, после успешной регистрации происходит перенаправление на него с добавлением `status=connected` в качестве query-параметра. Используйте это для обновления страницы на стороне клиента; используйте вебхук ниже, чтобы подтвердить привязку в вашем бэкенде.
## Вариант 2: Кнопка SDK
Добавьте origin вашей страницы в **Allowed SDK origins**, затем загрузите SDK. Код в браузере обращается к вашему бэкенду для получения ссылки. Маршрут `/api/ycloud/onboarding-link` ниже — это пример маршрута, который вы реализуете на своем сервере.
```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
```
`onStatus(result)` сообщает о статусе регистрации:
| Поле | Значение |
| - | - |
| `state` | `CONNECTED` означает успешное завершение. Другие значения указывают на незавершенный процесс или сбой, например `RETRYABLE_FAILED`. |
| `wabaId` | Идентификатор WABA, возвращается только при успешном завершении. |
| `phoneNumberId` | Идентификатор номера телефона Meta, который может возвращаться при успехе. |
| `errorCode` | Код ошибки, который может возвращаться в случае сбоя. |
| `retryable` | Может ли клиент повторить попытку в текущем окне регистрации. |
| `requestId` | Идентификатор запроса YCloud, который вы можете предоставить службе поддержки при устранении неполадок. |
`onError(error)` означает, что SDK не удалось открыть регистрацию. Его `code` может быть `POPUP_BLOCKED` или `INVALID_ONBOARDING_URL`. `onClose(event)` срабатывает только тогда, когда клиент закрывает окно до получения окончательного результата, с `reason: "USER_CLOSED"`.
Эти колбэки обновляют ваш фронтенд. Используйте серверный Webhook как окончательный результат привязки.
## Подтверждение привязки с помощью вебхука
YCloud отправляет `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](/ru/api-reference/guides/api-fundamentals/configure-webhooks) для настройки приемника.
## Устранение неполадок Partner Direct Link
| Признак | Действие |
| - | - |
| Клиент закрывает окно Meta или прерывает регистрацию. | Нажмите **Продолжить с Meta** еще раз, пока исходная ссылка остается действительной. |
| На странице сообщается об истекшей или недействительной ссылке. | Создайте новую ссылку на своем сервере. |
| SDK сообщает о недопустимом источнике (origin). | Убедитесь, что точный origin страницы указан в **Allowed SDK origins**. |
| Создание ссылки возвращает HTTP 429. | Подождите период, указанный в `Retry-After`, перед повторной попыткой. Избегайте многократного создания ссылок. |
| Регистрация завершилась успешно, но данные в вашей системе не обновились. | Проверьте настройки вебхука, подписку на события и логи приемника. Используйте вебхук в качестве окончательного результата. |
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.