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

# Instalação

> Instale, autentique e configure o SDK .NET oficial da VZaps

O SDK .NET oficial da VZaps encapsula autenticação, chamadas HTTP, headers obrigatórios, eventos realtime e os principais recursos da API pública.

Use em APIs ASP.NET Core, Workers, serviços Windows/Linux, CLIs e automações server-to-server.

## Requisitos

| Recurso     | Versão                        |
| ----------- | ----------------------------- |
| .NET        | .NET Standard 2.0 ou superior |
| Recomendado | .NET 8 ou superior            |

## Instalar

```bash theme={null}
dotnet add package VZaps.SDK
```

## Criar o cliente

```csharp theme={null}
using VZaps;

using var client = new VZapsClient(new VZapsClientOptions
{
    ClientToken = "your-client-token",
    ClientSecret = "your-client-secret",
});
```

Com ASP.NET Core ou Worker, registre o cliente no container:

```csharp theme={null}
builder.Services.AddVZapsClient(options =>
{
    options.ClientToken = builder.Configuration["VZaps:ClientToken"];
    options.ClientSecret = builder.Configuration["VZaps:ClientSecret"];
});
```

Depois injete `VZapsClient` em handlers, controllers ou hosted services.

## Credenciais

| Credencial      | Onde usar                 | Descrição                                                        |
| --------------- | ------------------------- | ---------------------------------------------------------------- |
| `ClientToken`   | `VZapsClientOptions`      | Token de cliente da conta, também enviado como `X-Client-Token`. |
| `ClientSecret`  | `VZapsClientOptions`      | Segredo usado pelo SDK para obter e renovar JWTs.                |
| `InstanceToken` | Cada chamada de instância | Token da instância, enviado como `X-Instance-Token`.             |

Não exponha `ClientSecret` ou `InstanceToken` em front-ends públicos.

## Autenticação automática

O SDK obtém um JWT com `ClientToken` e `ClientSecret`, cacheia em memória e renova antes de expirar.

```csharp theme={null}
var accessToken = await client.Auth.GetAccessTokenAsync();
```

## Opções do cliente

| Opção              | Padrão        | Uso                                   |
| ------------------ | ------------- | ------------------------------------- |
| `Timeout`          | 30 segundos   | Timeout HTTP.                         |
| `TokenRefreshSkew` | 60 segundos   | Renova o JWT antes da expiração real. |
| `UserAgent`        | Padrão do SDK | Header HTTP `User-Agent`.             |

## Variáveis de ambiente

```bash theme={null}
VZAPS_CLIENT_TOKEN=your-client-token
VZAPS_CLIENT_SECRET=your-client-secret
VZAPS_INSTANCE_ID=VZ...
VZAPS_INSTANCE_TOKEN=your-instance-token
```

## Tipagem de respostas

Os exemplos usam `object` ou `JsonElement` quando a resposta pode variar. Em produção, você pode criar seus próprios DTOs e passá-los como `TResponse`.

```csharp theme={null}
var response = await client.Instances.ListAsync<JsonElement>(new InstanceListRequest
{
    Page = 1,
    PageSize = 20,
});
```

## Próximos passos

* Siga o [Starter Guide](/pt-BR/sdk/dotnet/starter-guide).
* Veja [Mensagens](/pt-BR/sdk/dotnet/messages) para métodos de envio.
* Veja [Realtime](/pt-BR/sdk/dotnet/realtime) para assinaturas WebSocket.