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

# Conectar instancia

> Inicia la conexión de WhatsApp y devuelve un QR code o pairing code

**Auth:** `TokenAccount` o `TokenInstance` • **Rate-limit:** `Global` (100/min) • **Idempotente:** parcial

## Descripción

Inicia la conexión vía whatsmeow. Sin parámetros, genera un **QR code**. Con `?number=...`, genera un **pairing code** (8 caracteres). Bloquea hasta recibir un código o error (timeout interno \~60s).

## Ejemplos

### QR code (uso por defecto)

Sin query params, el servidor genera el QR code para escanear en el teléfono. Devuelve la cadena ASCII y el PNG en base64 listo para renderizar.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/instance/connect/my-instance" \
    -H "token: $Token_Instance"
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/connect/my-instance", {
    method: "GET",
    headers: {
      "token": process.env.Token_Instance
    }
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.get(
      "https://ryzeapi.cloud/api/instance/connect/my-instance",
      headers={
          "token": os.environ["Token_Instance"]
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/instance/connect/my-instance", nil)
      req.Header.Set("token", os.Getenv("Token_Instance"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### Pairing code

Pasando `?number=5511999999999`, el servidor fuerza el login vía un pairing code de 8 caracteres en lugar de QR, útil cuando el usuario no tiene acceso a una cámara para escanear.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/instance/connect/my-instance?number=5511999999999" \
    -H "token: $Token_Instance"
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/connect/my-instance?number=5511999999999", {
    method: "GET",
    headers: {
      "token": process.env.Token_Instance
    }
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.get(
      "https://ryzeapi.cloud/api/instance/connect/my-instance?number=5511999999999",
      headers={
          "token": os.environ["Token_Instance"]
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/instance/connect/my-instance?number=5511999999999", nil)
      req.Header.Set("token", os.Getenv("Token_Instance"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### Con 7 días de historial

Solicita los últimos 7 días de mensajes en el primer pairing vía `?history=7`. La presencia del parámetro fuerza la sincronización aunque `disableHistorySync=true` esté en los settings de la instancia.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/instance/connect/my-instance?history=7" \
    -H "token: $Token_Instance"
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/connect/my-instance?history=7", {
    method: "GET",
    headers: {
      "token": process.env.Token_Instance
    }
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.get(
      "https://ryzeapi.cloud/api/instance/connect/my-instance?history=7",
      headers={
          "token": os.environ["Token_Instance"]
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/instance/connect/my-instance?history=7", nil)
      req.Header.Set("token", os.Getenv("Token_Instance"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

<Tip>
  **Pairing code**: no se necesita cámara. El usuario teclea los 8 caracteres en WhatsApp en **Dispositivos vinculados > Vincular un dispositivo > Vincular con número de teléfono**.
</Tip>

## Respuesta exitosa

<Tabs>
  <Tab title="QR code generado">
    ```json 200 OK theme={null}
    {
      "success": true,
      "message": "QR code generated",
      "qrCode": "1@abc...,xyz==,base64string",
      "qrCodeBase64": "data:image/png;base64,iVBORw0K...",
      "status": "qr"
    }
    ```

    * `qrCode`, cadena ASCII del QR (lo que WhatsApp espera). Puede renderizarse con cualquier librería QR.
    * `qrCodeBase64`, PNG renderizado por el servidor (base64). Listo para usar como `<img src="data:image/png;base64,...">`.
  </Tab>

  <Tab title="Pairing code generado">
    ```json 200 OK theme={null}
    {
      "success": true,
      "message": "Pairing code generated",
      "pairingCode": "ABCD-EFGH",
      "status": "qr"
    }
    ```

    `pairingCode` es lo que el usuario teclea en el teléfono.
  </Tab>
</Tabs>

## Parámetros de ruta

<ParamField path="instance" type="string" required>
  Nombre de la instancia a conectar.
</ParamField>

## Cabeceras

<ParamField header="token" type="string" required>
  TokenAccount o TokenInstance de la instancia en el path.
</ParamField>

## Parámetros de consulta

<ParamField query="number" type="string">
  Teléfono en formato internacional (p. ej., `5511999999999`). Si está rellenado, fuerza login vía **pairing code** en lugar de QR.
</ParamField>

<ParamField query="history" type="integer">
  Solicita los últimos **N días** de historial en el primer pairing (p. ej., `?history=5`). Requiere soporte del servidor de WhatsApp, no garantizado. La presencia del parámetro fuerza la sincronización aunque `disableHistorySync=true` esté en los settings.
</ParamField>

## Notas

<Note>
  **El QR expira**, WhatsApp emite un nuevo QR después de \~20s. Si el usuario tarda demasiado y necesitas otro intento, repite la llamada.
</Note>

<Warning>
  **Pairing code** no es reutilizable. Si el usuario lo escribe mal, repite la solicitud para generar uno nuevo.
</Warning>

<Tip>
  Después de llamar a `connect`, haz polling a [`GET /api/instance/list?instanceName=<name>`](/es/api/instance/list) para detectar cuando el estado pase a `connected`. Webhook/WebSocket notifican en tiempo real vía el evento `instance.state`.
</Tip>

## Errores

| HTTP | `error.message`                         | Cuándo                                                    |
| :--: | --------------------------------------- | --------------------------------------------------------- |
|  400 | `Instance name is required`             | Path vacío.                                               |
|  401 | `Invalid token`                         | Token faltante o inválido.                                |
|  404 | `Instance not found`                    | Nombre no existe.                                         |
|  429 | `Rate limit exceeded. Try again later.` | Más de 100 req/min.                                       |
|  500 | `Failed to generate QR code`            | Falla al generar QR/pairing (red, proxy, store corrupto). |

```json theme={null}
{
  "success": false,
  "error": {
    "message": "Instance not found"
  }
}
```

## Siguiente

<CardGroup cols={2}>
  <Card title="Reconectar sin QR" icon="rotate" href="/es/api/instance/reconnect">
    `POST /api/instance/reconnect/:instance`, reutiliza la sesión guardada.
  </Card>

  <Card title="Verificar estado" icon="list-check" href="/es/api/instance/list">
    `GET /api/instance/list?instanceName=<name>` muestra el estado actual.
  </Card>
</CardGroup>