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

# POST /v1/numbers/remote-pairing — Link de Pareamento Hospedado

> Gere um link de pareamento hospedado que seu cliente final abre para conectar o número de WhatsApp dele — com envio opcional via WhatsApp, marca white-label e Meta Embedded Signup.

# Pareamento remoto — link de pareamento hospedado

Para plataformas SaaS que gerenciam números para clientes finais, o Pareamento Remoto permite gerar um **link de pareamento** em vez de exibir o QR code você mesmo. Seu cliente abre o link, escaneia o QR (ou executa o Meta Embedded Signup), e o número conecta à sua conta.

<Frame caption="Uma sessão de pareamento remoto — envie o link hospedado ao seu cliente; quando ele escanear o QR, o webhook number.connected dispara.">
  <img src="https://mintcdn.com/iaxp/138U4hguUF9MOdMn/images/dashboard/remote-pairing-link.png?fit=max&auto=format&n=138U4hguUF9MOdMn&q=85&s=23cb6f2114246955e9a12503cc0a8818" alt="Modal Pairing Link com o link de conexão hospedado e a opção de envio via WhatsApp" width="1920" height="914" data-path="images/dashboard/remote-pairing-link.png" />
</Frame>

## POST /v1/numbers/remote-pairing

Mesmo corpo de `POST /v1/numbers`, mais opções específicas de pareamento:

```bash theme={null}
curl -X POST "https://pilotstatus.com.br/v1/numbers/remote-pairing" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_token_here" \
  -d '{
    "name": "Customer João",
    "number": "+5511999999999",
    "linkToApiKey": true,
    "sendViaWhatsApp": false
  }'
```

Resposta `201`:

```json theme={null}
{
  "instance": { "id": "wa_abc", "instanceName": "PS-tenant-xxx", "number": "5511999999999", "name": "Customer João", "state": "CLOSE" },
  "remotePairingUrl": "https://pilotstatus.com.br/connect/abc123-def456-...",
  "maskedNumber": "+551199****9999",
  "messageSent": false
}
```

Diferenças em relação a `POST /v1/numbers`:

* A instância é criada no estado `CLOSE` (desconectada) — **nenhum QR code** é retornado.
* `remotePairingUrl` é o link público para enviar ao cliente final.
* Quando o cliente final abre a URL e conecta, o webhook `number.connected` dispara normalmente.

## Envio automático via WhatsApp

Com `sendViaWhatsApp: true`, o Pilot Status tenta enviar uma mensagem de template para o número de destino contendo o link de pareamento. Requer um template chamado `pilot_status_remote_pairing` (categoria OTP) criado no painel. Se o envio falhar, a instância e a URL ainda são criadas, mas `messageSent` retorna `false` com um `messageError`.

## Marca por link (white-label)

O corpo também aceita um objeto opcional `branding` para sobrescrever o logo/cores/título da página de conexão para **apenas este link** (registrado no token). Ele sobrepõe a marca salva do tenant. Veja [Marca da página de conexão](/pt-BR/api/branding).

## Números Meta: `metaFlow`

Para números da **API oficial Meta Cloud** o link de pareamento pode executar fluxos Meta em vez do pareamento por QR:

* `metaFlow: "embedded"` — a página hospedada executa o **Meta Embedded Signup** para que seu cliente conecte a própria WABA sem sair do link.
* `metaFlow: "credentials"` — a página hospedada coleta as credenciais da WABA existente do cliente.

<Note>
  O pareamento remoto com `metaFlow` é a opção **hospedada**. Se você já possui as credenciais da WABA no servidor, use `POST /v1/numbers/meta` (BYO-WABA direto) em vez disso — sem link e sem interação do cliente final.
</Note>

## Endpoints públicos por token (sem autenticação)

A página de pareamento usa estes endpoints baseados em token — você também pode chamá-los para construir sua própria UI de conexão:

| Método | Endpoint                             | Retorna                                                       |
| ------ | ------------------------------------ | ------------------------------------------------------------- |
| `GET`  | `/v1/remote-pairing/{token}`         | `{ valid, name, maskedNumber, state, branding }`              |
| `POST` | `/v1/remote-pairing/{token}/connect` | `{ qrcodeBase64, pairingCode }`                               |
| `GET`  | `/v1/remote-pairing/{token}/status`  | `{ state, isFullyConnected }`                                 |
| `GET`  | `/v1/connect/{token}/branding`       | `{ branding }` (também usado pelo fluxo Meta Embedded Signup) |

Observações:

* O token expira após **24 horas** ou mediante **conexão bem-sucedida** (uso único).
* `POST .../connect` só funciona quando o estado não é `OPEN`.
* O mesmo estado de conexão exibido no painel e nos webhooks (`number.created`, `number.connected`) se aplica.