> ## 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.

# Instâncias e billing

> Criar, listar, atualizar instâncias e fluxo de billing no SDK

Use estes recursos para autenticação da conta, ciclo de vida da instância e billing.

Para sessão WhatsApp, veja [Sessão](/pt-BR/sdk/python/session). Para chats, veja [Chats](/pt-BR/sdk/python/chats). Para envio de mensagens, veja [Mensagens](/pt-BR/sdk/python/messages).

Campos comuns em chamadas de instância:

| Campo            | Tipo     | Obrigatório | Descrição           |
| ---------------- | -------- | ----------- | ------------------- |
| `instance_id`    | `string` | Sim         | ID da instância.    |
| `instance_token` | `string` | Sim         | Token da instância. |

## Auth

### `client.auth.get_access_token()`

Obtém um JWT com `client_token` e `client_secret`. Na maioria dos fluxos, os recursos fazem isso automaticamente.

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

**Retorno:** `string` com o JWT de acesso (`accessToken` de `POST /token`).

## Instâncias e billing

### `client.instances.create(...)`

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

**Retorno:** `InstancePublicCreateResponse` — `id`, `name`, `token`, `url`, `webhook`, `events_subscribe`, `status`, `created_at`, `updated_at`.

### `client.instances.list(...)`

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

**Retorno:** pagina `{ page, size, total, total_pages, content[], summary }`. Cada item de `content` segue o resumo publico da instancia (`id`, `name`, `status`, etc.).

### `client.instances.get(instance_id)`

Retorna uma instância no mesmo formato de resumo público de cada linha de `client.instances.list()`.

```python theme={null}
instance = client.instances.get("VZ...")
```

**Retorno:** mesmo formato resumido de um item de `instances.list()` (`id`, `name`, `token`, `url`, `webhook`, `status`, etc.).

### `client.instances.update(instance_id, ..., instance_token=...)`

```python theme={null}
client.instances.update(
    "VZ...",
    name="Atendimento Comercial",
    instance_token="instance-token",
)
```

**Retorno:** instancia atualizada no mesmo formato resumido de `instances.get()`.

### `client.instances.restart(instance_id, instance_token=...)`

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

**Retorno:** `InstanceActionResponse` — `instance_id`, `status`, `details`.

### `client.instances.delete(instance_id, instance_token=...)`

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

**Retorno:** corpo vazio em sucesso (`204`) ou envelope de erro padrao.

### `client.instances.subscribe(instance_id, ..., instance_token=...)`

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

**Retorno:** `BillingHostedSession` — `url`, `session_id`, `mode` (`direct` ou checkout), `subscription_id`.

### `client.instances.resume_subscription(instance_id, instance_token=...)`

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

**Retorno:** `{ status: "ok" }`.

### `client.instances.cancel(instance_id, instance_token=...)`

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

**Retorno:** `{ message }` confirmando cancelamento ou agendamento.

## Chamadas avançadas

Use `client.request()` quando precisar de uma operação ainda não encapsulada por um recurso:

```python theme={null}
client.request(method, path, body=..., query=..., instance_token=...)
```

Para o contrato HTTP completo, use a aba [API](/pt-BR/api-reference/introduction).