> ## 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/php/session). Para chats, veja [Chats](/pt-BR/sdk/php/chats). Para envio de mensagens, veja [Mensagens](/pt-BR/sdk/php/messages).

Campos comuns em chamadas de instância:

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

## Auth

### `auth()->getAccessToken()`

Obtém JWT com `clientToken` e `clientSecret`. Na maioria dos fluxos, os recursos fazem isso automaticamente.

```php theme={null}
$token = $vzaps->auth()->getAccessToken();
echo substr($token, 0, 16) . PHP_EOL;
```

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

## Instâncias e billing

### `instances()->create($data)`

```php theme={null}
$created = $vzaps->instances()->create([
    'name' => 'Atendimento',
    'webhook' => 'https://example.com/webhooks/vzaps',
    'eventsSubscribe' => ['Message', 'Connected', 'Disconnected'],
]);
```

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

### `instances()->list($data = null)`

```php theme={null}
$instances = $vzaps->instances()->list([
    'page' => 1,
    'pageSize' => 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.).

### `instances()->get($instanceId)`

Retorna uma instância no mesmo formato público resumido de cada item de `instances()->list()`.

```php theme={null}
$instance = $vzaps->instances()->get('VZ...');
```

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

### `instances()->update($instanceId, $data, $instanceToken = null)`

```php theme={null}
$vzaps->instances()->update('VZ...', [
    'name' => 'Atendimento Comercial',
], 'instance-token');
```

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

### `instances()->restart($instanceId, $instanceToken = null)`

```php theme={null}
$vzaps->instances()->restart('VZ...', 'instance-token');
```

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

### `instances()->delete($instanceId, $instanceToken = null)`

```php theme={null}
$vzaps->instances()->delete('VZ...', 'instance-token');
```

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

### `instances()->subscribe($instanceId, $data = [], $instanceToken = null)`

```php theme={null}
$checkout = $vzaps->instances()->subscribe('VZ...', [], 'instance-token');
```

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

### `instances()->resumeSubscription($instanceId, $instanceToken = null)`

```php theme={null}
$vzaps->instances()->resumeSubscription('VZ...', 'instance-token');
```

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

### `instances()->cancel($instanceId, $instanceToken = null)`

```php theme={null}
$vzaps->instances()->cancel('VZ...', 'instance-token');
```

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

## Chamadas avançadas

Use `$vzaps->request()` quando precisar de uma operação ainda não encapsulada por um recurso:

```php theme={null}
$response = $vzaps->request('POST', '/instances/get', ['id' => 'VZ...']);
```

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