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

# Starter Guide

> Fluxo completo com o SDK Python: autenticar, criar instância, assinar, parear, configurar eventos e enviar mensagens

Este guia mostra o caminho recomendado para sair do zero até uma instância conectada enviando mensagens pela VZaps.

## 1. Instale e crie o cliente

```bash theme={null}
pip install vzaps
```

```python theme={null}
from vzaps import VZapsClient

with VZapsClient(
    client_token="seu-client-token",
    client_secret="seu-client-secret",
) as client:
    ...
```

## 2. Valide autenticação

```python theme={null}
jwt = client.auth.get_access_token()
print(jwt[:16])
```

Na maioria dos fluxos, você não precisa chamar `get_access_token()`. Os recursos do SDK fazem isso automaticamente.

## 3. Liste instâncias existentes

```python theme={null}
instances = client.instances.list(
    page=1,
    size=20,
    search="atendimento",
)

print(instances)
```

## 4. Crie uma instância

```python theme={null}
created = client.instances.create(
    name="Atendimento Comercial",
    webhook="https://example.com/webhooks/vzaps",
    events_subscribe=["Message", "ReadReceipt", "Connected", "Disconnected"],
)

print(created)
```

Guarde da resposta:

* `id`: identificador da instância.
* `token`: token da instância. Use como `instance_token` nas chamadas de instância.

## 5. Assine a instância

```python theme={null}
subscription = client.instances.subscribe(
    "VZ...",
    {},
    instance_token="instance-token",
)

print(subscription)
```

Se um cancelamento está agendado e você quer reativar a assinatura:

```python theme={null}
resumed = client.instances.resume_subscription(
    "VZ...",
    instance_token="instance-token",
)
```

## 6. Pareie o WhatsApp

Verifique o status:

```python theme={null}
status = client.sessions.status("VZ...", instance_token="instance-token")
print(status)
```

Obtenha o QR code:

```python theme={null}
qr = client.sessions.qr("VZ...", instance_token="instance-token")
print(qr)
```

Obtenha o código de pareamento por telefone:

```python theme={null}
pair_code = client.sessions.pair_code(
    "VZ...",
    "5511999999999",
    instance_token="instance-token",
)
print(pair_code)
```

## 7. Configure o webhook

Veja [Webhooks](/pt-BR/sdk/python/webhooks) para configuração completa, logs e exemplos.

```python theme={null}
client.webhooks.set(
    instance_id="VZ...",
    instance_token="instance-token",
    webhook_url="https://example.com/webhooks/vzaps",
    events=["Message", "ReadReceipt", "Connected", "Disconnected"],
)
```

## 8. Assine o realtime

Veja [Realtime](/pt-BR/sdk/python/realtime) para detalhes de assinatura, ack e reconexão.

```python theme={null}
import asyncio

from vzaps import AsyncVZapsClient

async def main():
    async with AsyncVZapsClient(
        client_token="seu-client-token",
        client_secret="seu-client-secret",
    ) as client:
        async with client.events.subscribe(
            instance_id="VZ...",
            instance_token="instance-token",
            events=["Message", "Connected", "Disconnected"],
            reconnect=True,
        ) as subscription:

            @subscription.on("Message")
            async def on_message(event):
                print(event.id)
                print(event.data)

            @subscription.on_error
            async def on_error(error):
                print(error)

            await subscription.wait_closed()

asyncio.run(main())
```

## 9. Envie a primeira mensagem

```python theme={null}
client.messages.send_text(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    message="Olá! Esta mensagem foi enviada com a VZaps.",
)
```

## 10. Envie mídia

Imagem:

```python theme={null}
client.messages.send_image(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    image="https://example.com/imagem.jpg",
    caption="Imagem enviada com a VZaps",
)
```

Documento:

```python theme={null}
client.messages.send_document(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    document="https://example.com/contrato.pdf",
    file_name="contrato.pdf",
    caption="Aqui está o contrato",
)
```

Veja [Mensagens](/pt-BR/sdk/python/messages) para todos os tipos de envio e payloads.

## 11. Verifique filas

Veja [Filas](/pt-BR/sdk/python/queues) para listar, remover e limpar filas.

## 12. Trate erros

```python theme={null}
from vzaps.errors import VZapsAuthenticationError, VZapsError, VZapsTimeoutError

try:
    client.messages.send_text(
        instance_id="VZ...",
        instance_token="instance-token",
        phone="5511999999999",
        message="Olá",
    )
except VZapsAuthenticationError:
    print("Credenciais inválidas")
except VZapsTimeoutError:
    print("Requisição expirou")
except VZapsError as error:
    print(error.status, error.message, error.details)
    raise
```