> ## 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)
> Faça o onboarding de clientes do WhatsApp como um YCloud Tech Partner com um link hospedado ou botão do SDK, sem precisar se tornar um parceiro da Meta.
O Partner Direct Link (TP Lite) é uma opção de integração para YCloud Tech Partners. Você precisa que a YCloud habilite o recurso para a sua conta, mas não precisa se tornar um parceiro da Meta.
Crie um link de onboarding de curta duração no seu servidor. Seu cliente pode abri-lo diretamente ou por meio de um botão no seu site. Comece com o Direct Link para testar sua integração e depois use o botão do SDK se quiser que os clientes concluam o cadastro em um pop-up.
## Visão geral da integração
1. **Prepare sua conta.** Solicite à YCloud a habilitação do Partner Direct Link, crie uma chave de API e configure seu receptor de webhook.
2. **Configure seu ponto de entrada.** Abra o Partner Direct Link no painel e defina sua identidade visual, URL de redirecionamento ou origens do SDK.
3. **Crie um link.** Seu servidor solicita um link de onboarding para um cliente em seu sistema.
4. **Deixe o cliente se conectar.** Eles abrem a página hospedada ou o pop-up do SDK e concluem a autorização da Meta.
5. **Confirme o resultado.** Seu backend recebe o webhook e associa a WABA ao cliente.
## Antes de começar
1. Peça à YCloud para habilitar o Partner Direct Link para a sua conta. Se você ainda não for um Tech Partner, [candidate-se para se tornar um](https://www.ycloud.com/tech-partner).
2. Crie uma chave de API em **Desenvolvedores > Chave de API**.
3. Configure seu receptor em **Desenvolvedores > Webhooks** e assine `whatsapp.business_account.updated`.
Chame a API de criação de link a partir do seu servidor. Nunca insira sua chave de API no código do navegador ou de aplicativos móveis. Trate cada URL de onboarding como uma credencial temporária: mantenha-a fora de páginas públicas, ferramentas de analytics e logs públicos.
## Encontre o Partner Direct Link no painel
1. Abra o painel da YCloud para a conta em que o Partner Direct Link está habilitado.
2. Expanda **Desenvolvedores** na barra lateral esquerda.
3. Clique em **Partner Direct Link** para abrir a página de configuração.
A página contém **Configurações básicas** para sua identidade visual e **Integração** para criar um link, integrar o ponto de entrada e assinar webhooks. Use a **Pré-visualização da página hospedada** para ver a página voltada ao cliente.
## Configure sua identidade visual e ponto de entrada
Abra **Desenvolvedores > Partner Direct Link** no painel da YCloud. Preencha as **Configurações básicas**:
| Configuração | Requisito | Finalidade |
| - | - | - |
| **Nome de exibição** | Obrigatório | O nome do seu parceiro na página de cadastro hospedada. |
| **Logotipo do parceiro** | Opcional | Seu logotipo na página de cadastro hospedada. |
| **URL de redirecionamento (somente Direct Link)** | Opcional | Uma URL HTTPS completa para abrir após o cadastro bem-sucedido. Sem ela, os clientes veem uma página de sucesso com a sua marca. |
| **Origens permitidas do SDK (somente botão do SDK)** | Obrigatório para o botão do SDK | As origens das páginas que carregam o SDK, como `https://app.example.com`. |
Para origens do SDK, insira o esquema exato, o domínio e a porta opcional, sem um caminho. Adicione cada subdomínio ou porta separadamente; caracteres curinga não são suportados. Use HTTPS em produção. HTTP é permitido apenas para o desenvolvimento com `localhost`. O Direct Link funciona sem uma origem permitida do SDK; o botão do SDK não.
## Crie um link de onboarding no seu servidor
```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"
}'
```
| Campo | Obrigatório | Descrição |
| - | - | - |
| `partnerCustomerId` | Sim | Um ID de cliente estável do seu sistema. Evite informações confidenciais. A YCloud retorna este ID no webhook de vinculação bem-sucedida. |
| `onboardingType` | Sim | Escolha `WHATSAPP_BUSINESS_PLATFORM` para envio de mensagens via API, ou `WHATSAPP_BUSINESS_APP` para coexistência com o Business App, conforme descrito abaixo. |
| `locale` | Não | O idioma da página hospedada. O padrão é `en_US`. |
* [**WhatsApp Business Platform**](/pt/documentation/whatsapp-business-platform/overview) (`WHATSAPP_BUSINESS_PLATFORM`): Escolha este modo para conectar um número para troca de mensagens por meio de APIs e do seu software.
* [**Coexistência com o WhatsApp Business App**](/pt/documentation/whatsapp-business-platform/accounts-and-business-identity/whatsapp-business-app-coexistence) (`WHATSAPP_BUSINESS_APP`): Escolha este modo para um número qualificado do Business App existente quando o cliente desejar continuar usando o aplicativo e adicionar o envio de mensagens via API no mesmo número.
Os idiomas suportados são `en_US` (inglês), `zh_CN` (chinês simplificado), `es_ES` (espanhol), `pt_BR` (português do Brasil), `id_ID` (indonésio) e `ru_RU` (russo). Os valores diferenciam maiúsculas de minúsculas. Outros valores retornam HTTP 400.
Exemplo de resposta:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"onboardingUrl": "https://connect.ycloud.com/open/whatsapp/onboard#token=EXAMPLE_TOKEN",
"expiresAt": 1893456000000
}
```
`expiresAt` é o horário de expiração como um timestamp Unix em milissegundos. O tempo de vida padrão do link é de duas horas. Cada link conecta um cliente a uma WABA. Antes de concluir o cadastro, o cliente pode atualizar, tentar novamente ou abrir o link em outro navegador enquanto ele permanecer válido. Após a vinculação bem-sucedida, o link não pode vincular outra WABA. Crie um novo link quando o cliente precisar alterar ou adicionar uma WABA.
## Opção 1: Link direto
Adicione um botão de conexão ao seu aplicativo de cliente. Quando o cliente clicar nele, solicite um link de integração ao seu servidor e navegue até `onboardingUrl` ou abra-o em uma nova janela. Você também pode enviá-lo de forma privada ao cliente pretendido por meio de um canal individual seguro.
O cliente abre a página hospedada e clica em **Continue with Meta**. Ele usa uma conta do Facebook com permissão para gerenciar a empresa e seleciona ou cria a empresa, a WABA e o número de telefone na Meta. A YCloud conclui a vinculação e exibe o resultado.
Se você configurou uma URL de redirecionamento, o cadastro bem-sucedido redirecionará para lá com `status=connected` anexado como um parâmetro de consulta. Use isso para atualizar a página voltada ao cliente; use o webhook abaixo para confirmar a vinculação no seu back-end.
## Opção 2: Botão SDK
Adicione a origem da sua página a **Allowed SDK origins** e, em seguida, carregue o SDK. O código do seu navegador chama seu próprio back-end para obter o link. A rota `/api/ycloud/onboarding-link` abaixo é um exemplo de rota que você implementa no seu servidor.
```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
```
`onStatus(result)` relata o estado do cadastro:
| Campo | Significado |
| - | - |
| `state` | `CONNECTED` significa sucesso. Outros valores indicam um fluxo incompleto ou com falha, como `RETRYABLE_FAILED`. |
| `wabaId` | O ID da WABA, retornado apenas em caso de sucesso. |
| `phoneNumberId` | O ID do número de telefone da Meta, que pode ser retornado em caso de sucesso. |
| `errorCode` | Um código de erro que pode ser retornado em caso de falha. |
| `retryable` | Se o cliente pode tentar novamente na janela de cadastro atual. |
| `requestId` | Um ID de requisição da YCloud que você pode fornecer ao suporte durante a solução de problemas. |
`onError(error)` significa que o SDK não conseguiu abrir o cadastro. Seu `code` pode ser `POPUP_BLOCKED` ou `INVALID_ONBOARDING_URL`. `onClose(event)` é disparado somente quando o cliente fecha a janela antes de um resultado final, com `reason: "USER_CLOSED"`.
Esses retornos de chamada atualizam seu front-end. Use o webhook do lado do servidor como o resultado final da vinculação.
## Confirmar a vinculação com um webhook
A YCloud envia `whatsapp.business_account.updated` para o seu receptor de webhook configurado após a vinculação ser bem-sucedida. O trecho a seguir mostra os campos que sua integração utiliza:
```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"
}
}
```
Quando `updateEvent` for `PARTNER_ADDED`, processe a WABA como recém-adicionada. Corresponda `partnerCustomerId` ao seu cliente e salve o `id` da WABA. Um valor `paymentMethodAttached` de `true` significa que a vinculação de crédito foi bem-sucedida; `false` significa que ela não foi concluída.
Elimine entregas duplicadas usando o evento `id` e retorne HTTP 2xx após o recebimento bem-sucedido. Consulte [Webhooks](/pt/api-reference/guides/api-fundamentals/configure-webhooks) para a configuração do receptor.
## Solução de problemas do Partner Direct Link
| Sintoma | Ação |
| - | - |
| O cliente fecha a Meta ou interrompe o cadastro. | Clique em **Continue with Meta** novamente enquanto o link original permanecer válido. |
| A página informa um link expirado ou inválido. | Crie um novo link no seu servidor. |
| O SDK informa uma origem inválida. | Verifique se a origem exata da página está em **Allowed SDK origins**. |
| A criação do link retorna HTTP 429. | Aguarde o período especificado por `Retry-After` antes de tentar novamente. Evite criar links repetidamente. |
| O cadastro mostra sucesso, mas seu sistema não foi atualizado. | Verifique a configuração do seu webhook, a assinatura de eventos e os logs do receptor. Use o webhook como o resultado final. |
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.
A página contém **Configurações básicas** para sua identidade visual e **Integração** para criar um link, integrar o ponto de entrada e assinar webhooks. Use a **Pré-visualização da página hospedada** para ver a página voltada ao cliente.
## Configure sua identidade visual e ponto de entrada
Abra **Desenvolvedores > Partner Direct Link** no painel da YCloud. Preencha as **Configurações básicas**:
| Configuração | Requisito | Finalidade |
| - | - | - |
| **Nome de exibição** | Obrigatório | O nome do seu parceiro na página de cadastro hospedada. |
| **Logotipo do parceiro** | Opcional | Seu logotipo na página de cadastro hospedada. |
| **URL de redirecionamento (somente Direct Link)** | Opcional | Uma URL HTTPS completa para abrir após o cadastro bem-sucedido. Sem ela, os clientes veem uma página de sucesso com a sua marca. |
| **Origens permitidas do SDK (somente botão do SDK)** | Obrigatório para o botão do SDK | As origens das páginas que carregam o SDK, como `https://app.example.com`. |
Para origens do SDK, insira o esquema exato, o domínio e a porta opcional, sem um caminho. Adicione cada subdomínio ou porta separadamente; caracteres curinga não são suportados. Use HTTPS em produção. HTTP é permitido apenas para o desenvolvimento com `localhost`. O Direct Link funciona sem uma origem permitida do SDK; o botão do SDK não.
## Crie um link de onboarding no seu servidor
```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"
}'
```
| Campo | Obrigatório | Descrição |
| - | - | - |
| `partnerCustomerId` | Sim | Um ID de cliente estável do seu sistema. Evite informações confidenciais. A YCloud retorna este ID no webhook de vinculação bem-sucedida. |
| `onboardingType` | Sim | Escolha `WHATSAPP_BUSINESS_PLATFORM` para envio de mensagens via API, ou `WHATSAPP_BUSINESS_APP` para coexistência com o Business App, conforme descrito abaixo. |
| `locale` | Não | O idioma da página hospedada. O padrão é `en_US`. |
* [**WhatsApp Business Platform**](/pt/documentation/whatsapp-business-platform/overview) (`WHATSAPP_BUSINESS_PLATFORM`): Escolha este modo para conectar um número para troca de mensagens por meio de APIs e do seu software.
* [**Coexistência com o WhatsApp Business App**](/pt/documentation/whatsapp-business-platform/accounts-and-business-identity/whatsapp-business-app-coexistence) (`WHATSAPP_BUSINESS_APP`): Escolha este modo para um número qualificado do Business App existente quando o cliente desejar continuar usando o aplicativo e adicionar o envio de mensagens via API no mesmo número.
Os idiomas suportados são `en_US` (inglês), `zh_CN` (chinês simplificado), `es_ES` (espanhol), `pt_BR` (português do Brasil), `id_ID` (indonésio) e `ru_RU` (russo). Os valores diferenciam maiúsculas de minúsculas. Outros valores retornam HTTP 400.
Exemplo de resposta:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"onboardingUrl": "https://connect.ycloud.com/open/whatsapp/onboard#token=EXAMPLE_TOKEN",
"expiresAt": 1893456000000
}
```
`expiresAt` é o horário de expiração como um timestamp Unix em milissegundos. O tempo de vida padrão do link é de duas horas. Cada link conecta um cliente a uma WABA. Antes de concluir o cadastro, o cliente pode atualizar, tentar novamente ou abrir o link em outro navegador enquanto ele permanecer válido. Após a vinculação bem-sucedida, o link não pode vincular outra WABA. Crie um novo link quando o cliente precisar alterar ou adicionar uma WABA.
## Opção 1: Link direto
Adicione um botão de conexão ao seu aplicativo de cliente. Quando o cliente clicar nele, solicite um link de integração ao seu servidor e navegue até `onboardingUrl` ou abra-o em uma nova janela. Você também pode enviá-lo de forma privada ao cliente pretendido por meio de um canal individual seguro.
O cliente abre a página hospedada e clica em **Continue with Meta**. Ele usa uma conta do Facebook com permissão para gerenciar a empresa e seleciona ou cria a empresa, a WABA e o número de telefone na Meta. A YCloud conclui a vinculação e exibe o resultado.
Se você configurou uma URL de redirecionamento, o cadastro bem-sucedido redirecionará para lá com `status=connected` anexado como um parâmetro de consulta. Use isso para atualizar a página voltada ao cliente; use o webhook abaixo para confirmar a vinculação no seu back-end.
## Opção 2: Botão SDK
Adicione a origem da sua página a **Allowed SDK origins** e, em seguida, carregue o SDK. O código do seu navegador chama seu próprio back-end para obter o link. A rota `/api/ycloud/onboarding-link` abaixo é um exemplo de rota que você implementa no seu servidor.
```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
```
`onStatus(result)` relata o estado do cadastro:
| Campo | Significado |
| - | - |
| `state` | `CONNECTED` significa sucesso. Outros valores indicam um fluxo incompleto ou com falha, como `RETRYABLE_FAILED`. |
| `wabaId` | O ID da WABA, retornado apenas em caso de sucesso. |
| `phoneNumberId` | O ID do número de telefone da Meta, que pode ser retornado em caso de sucesso. |
| `errorCode` | Um código de erro que pode ser retornado em caso de falha. |
| `retryable` | Se o cliente pode tentar novamente na janela de cadastro atual. |
| `requestId` | Um ID de requisição da YCloud que você pode fornecer ao suporte durante a solução de problemas. |
`onError(error)` significa que o SDK não conseguiu abrir o cadastro. Seu `code` pode ser `POPUP_BLOCKED` ou `INVALID_ONBOARDING_URL`. `onClose(event)` é disparado somente quando o cliente fecha a janela antes de um resultado final, com `reason: "USER_CLOSED"`.
Esses retornos de chamada atualizam seu front-end. Use o webhook do lado do servidor como o resultado final da vinculação.
## Confirmar a vinculação com um webhook
A YCloud envia `whatsapp.business_account.updated` para o seu receptor de webhook configurado após a vinculação ser bem-sucedida. O trecho a seguir mostra os campos que sua integração utiliza:
```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"
}
}
```
Quando `updateEvent` for `PARTNER_ADDED`, processe a WABA como recém-adicionada. Corresponda `partnerCustomerId` ao seu cliente e salve o `id` da WABA. Um valor `paymentMethodAttached` de `true` significa que a vinculação de crédito foi bem-sucedida; `false` significa que ela não foi concluída.
Elimine entregas duplicadas usando o evento `id` e retorne HTTP 2xx após o recebimento bem-sucedido. Consulte [Webhooks](/pt/api-reference/guides/api-fundamentals/configure-webhooks) para a configuração do receptor.
## Solução de problemas do Partner Direct Link
| Sintoma | Ação |
| - | - |
| O cliente fecha a Meta ou interrompe o cadastro. | Clique em **Continue with Meta** novamente enquanto o link original permanecer válido. |
| A página informa um link expirado ou inválido. | Crie um novo link no seu servidor. |
| O SDK informa uma origem inválida. | Verifique se a origem exata da página está em **Allowed SDK origins**. |
| A criação do link retorna HTTP 429. | Aguarde o período especificado por `Retry-After` antes de tentar novamente. Evite criar links repetidamente. |
| O cadastro mostra sucesso, mas seu sistema não foi atualizado. | Verifique a configuração do seu webhook, a assinatura de eventos e os logs do receptor. Use o webhook como o resultado final. |
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.