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

# Gerenciando Instâncias

> Crie, conecte e gerencie instâncias WhatsApp ao longo de todo o seu ciclo de vida.

# Gerenciando Instâncias

Uma **instância** representa um único número WhatsApp conectado à Wappfy. Cada instância passa por um ciclo de vida: criar, conectar, escanear QR, usar, e eventualmente desconectar ou excluir.

## Tipos de Instância

A Wappfy suporta dois provedores:

| Tipo        | Descrição                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| `waha`      | API WhatsApp Web auto-hospedada via WAHA Plus. Suporte completo incluindo grupos, etiquetas e contatos. |
| `cloud_api` | API oficial WhatsApp Business Cloud da Meta. Requer uma conta Meta Business.                            |

## Valores de Status da Instância

Ao longo do seu ciclo de vida, uma instância transita pelos seguintes status:

| Status         | Descrição                                                               |
| -------------- | ----------------------------------------------------------------------- |
| `created`      | O registro da instância existe, mas ainda não foi iniciado.             |
| `starting`     | A instância está inicializando a sessão do WhatsApp.                    |
| `scan_qr`      | A instância está aguardando você escanear o QR code com seu celular.    |
| `connected`    | A sessão do WhatsApp está ativa e pronta para enviar/receber mensagens. |
| `disconnected` | A sessão foi interrompida ou perdeu a conexão. Pode ser reconectada.    |
| `failed`       | A instância encontrou um erro durante a inicialização ou conexão.       |

## Visão Geral do Ciclo de Vida

```mermaid theme={null}
graph LR
    A[created] --> B[starting]
    B --> C[scan_qr]
    C --> D[connected]
    D --> E[disconnected]
    E --> B
    B --> F[failed]
    F --> B
```

***

## Criar uma Instância

Crie uma nova instância WhatsApp vinculada à sua conta.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wappfy.io/api/instances \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Meu WhatsApp",
      "type": "waha"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.wappfy.io/api/instances", {
    method: "POST",
    headers: {
      "X-Api-Key": "SUA_CHAVE_API",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Meu WhatsApp",
      type: "waha",
    }),
  });

  const instance = await response.json();
  console.log(instance.data.id); // use este ID em todas as chamadas seguintes
  ```
</CodeGroup>

**Resposta:**

```json theme={null}
{
  "data": {
    "id": "inst_abc123",
    "name": "Meu WhatsApp",
    "type": "waha",
    "status": "created",
    "created_at": "2026-02-10T12:00:00Z"
  }
}
```

***

## Conectar uma Instância

Inicie a sessão do WhatsApp. A instância passará para o status `starting` e depois para `scan_qr`.

```bash theme={null}
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/connect \
  -H "X-Api-Key: SUA_CHAVE_API"
```

**Resposta:**

```json theme={null}
{
  "data": {
    "id": "inst_abc123",
    "status": "starting"
  }
}
```

***

## Obter o QR Code

Quando a instância atingir o status `scan_qr`, obtenha o QR code para escanear com seu celular.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.wappfy.io/api/instances/inst_abc123/qr \
    -H "X-Api-Key: SUA_CHAVE_API"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/qr",
    {
      headers: { "X-Api-Key": "SUA_CHAVE_API" },
    }
  );

  const { data } = await response.json();
  // data.qr contém a imagem do QR code em base64
  ```
</CodeGroup>

**Resposta:**

```json theme={null}
{
  "data": {
    "qr": "data:image/png;base64,iVBORw0KGgo..."
  }
}
```

<Note>
  O QR code expira após aproximadamente 60 segundos. Se expirar antes de você escaneá-lo, chame o endpoint novamente para obter um novo código.
</Note>

Abra a imagem do QR code e escaneie com **WhatsApp > Aparelhos Conectados > Conectar um Aparelho** no seu celular. Após o escaneamento, o status da instância mudará para `connected`.

***

## Verificar o Status da Instância

Consulte o endpoint de status para saber quando a instância está pronta.

```bash theme={null}
curl https://api.wappfy.io/api/instances/inst_abc123/status \
  -H "X-Api-Key: SUA_CHAVE_API"
```

**Resposta:**

```json theme={null}
{
  "data": {
    "id": "inst_abc123",
    "status": "connected",
    "phone_number": "5511999998888"
  }
}
```

<Tip>
  Em vez de fazer polling, configure um [webhook](/pt-BR/guides/webhooks) para os eventos `instance.connected` e `instance.qr` para ser notificado em tempo real.
</Tip>

***

## Listar Todas as Instâncias

Recupere todas as instâncias da sua conta.

```bash theme={null}
curl https://api.wappfy.io/api/instances \
  -H "X-Api-Key: SUA_CHAVE_API"
```

**Resposta:**

```json theme={null}
{
  "data": [
    {
      "id": "inst_abc123",
      "name": "Meu WhatsApp",
      "type": "waha",
      "status": "connected"
    },
    {
      "id": "inst_def456",
      "name": "Linha de Suporte",
      "type": "waha",
      "status": "disconnected"
    }
  ]
}
```

***

## Desconectar uma Instância

Pare a sessão do WhatsApp sem excluir a instância. Você pode reconectar depois.

```bash theme={null}
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/disconnect \
  -H "X-Api-Key: SUA_CHAVE_API"
```

***

## Reiniciar uma Instância

Reinicie a sessão do WhatsApp. Isso é útil quando a instância está em estado `failed` ou se comportando de forma inesperada.

```bash theme={null}
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/restart \
  -H "X-Api-Key: SUA_CHAVE_API"
```

<Note>
  Reiniciar preserva a sessão vinculada do WhatsApp. Você não precisará escanear o QR code novamente.
</Note>

***

## Fazer Logout de uma Instância

Faça logout do WhatsApp completamente. Isso desvincula o telefone da sessão. Você precisará escanear o QR code novamente para reconectar.

```bash theme={null}
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/logout \
  -H "X-Api-Key: SUA_CHAVE_API"
```

<Warning>
  O logout remove completamente o vínculo com o WhatsApp. Diferentemente da desconexão, você **precisa** escanear um novo QR code para usar esta instância novamente.
</Warning>

***

## Excluir uma Instância

Exclua permanentemente uma instância e todos os seus dados associados.

```bash theme={null}
curl -X DELETE https://api.wappfy.io/api/instances/inst_abc123 \
  -H "X-Api-Key: SUA_CHAVE_API"
```

<Warning>
  Esta ação é irreversível. Todas as mensagens, webhooks e configurações associadas a esta instância serão permanentemente excluídas.
</Warning>

***

## Exemplo Completo do Ciclo de Vida

Aqui está um exemplo completo que cria uma instância, conecta e obtém o QR code:

```bash theme={null}
# 1. Criar a instância
INSTANCE=$(curl -s -X POST https://api.wappfy.io/api/instances \
  -H "X-Api-Key: SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{"name": "Produção", "type": "waha"}')

INSTANCE_ID=$(echo $INSTANCE | jq -r '.data.id')
echo "Instância criada: $INSTANCE_ID"

# 2. Conectar a instância
curl -s -X POST "https://api.wappfy.io/api/instances/$INSTANCE_ID/connect" \
  -H "X-Api-Key: SUA_CHAVE_API"

# 3. Aguardar e obter o QR code
sleep 3
QR=$(curl -s "https://api.wappfy.io/api/instances/$INSTANCE_ID/qr" \
  -H "X-Api-Key: SUA_CHAVE_API")

echo $QR | jq -r '.data.qr' > qr-code.png
echo "QR code salvo em qr-code.png — escaneie com seu celular"

# 4. Aguardar o status de conexão
while true; do
  STATUS=$(curl -s "https://api.wappfy.io/api/instances/$INSTANCE_ID/status" \
    -H "X-Api-Key: SUA_CHAVE_API" | jq -r '.data.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "connected" ]; then
    echo "Instância conectada e pronta!"
    break
  fi
  sleep 2
done
```

***

## Tratamento de Erros

| Código de Status | Descrição                                                                   |
| ---------------- | --------------------------------------------------------------------------- |
| `404`            | Instância não encontrada ou não pertence à sua conta.                       |
| `409`            | A instância já está no estado solicitado (ex: já conectada).                |
| `422`            | Corpo da requisição inválido (ex: `name` ausente ou `type` inválido).       |
| `429`            | Limite de requisições excedido. Veja [Limites de Requisição](/rate-limits). |