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

> Como instalar, autenticar e configurar o SDK Go oficial da VZaps

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

Use este SDK em backends Go, workers, CLIs e automações server-to-server.

## Requisitos

| Recurso | Versão           |
| ------- | ---------------- |
| Go      | 1.22 ou superior |

<Tip>
  Não exponha `ClientSecret` nem `InstanceToken` em front-end público. Prefira usar o SDK em backend, API routes, jobs e automações server-to-server.
</Tip>

## Instalar

```bash theme={null}
go get github.com/vzaps/vzaps-sdk-go/vzaps
```

## Criar o cliente

```go theme={null}
import (
	"os"

	vzaps "github.com/vzaps/vzaps-sdk-go/vzaps"
)

client, err := vzaps.NewClient(vzaps.ClientOptions{
	ClientToken:  os.Getenv("VZAPS_CLIENT_TOKEN"),
	ClientSecret: os.Getenv("VZAPS_CLIENT_SECRET"),
})
if err != nil {
	panic(err)
}
```

Para scripts rápidos, `MustNewClient` faz panic se as opções forem inválidas:

```go theme={null}
client := vzaps.MustNewClient(vzaps.ClientOptions{
	ClientToken:  os.Getenv("VZAPS_CLIENT_TOKEN"),
	ClientSecret: os.Getenv("VZAPS_CLIENT_SECRET"),
})
```

## Credenciais

O SDK usa dois grupos de credenciais:

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

`InstanceToken` não fica no cliente global. Passe em toda chamada que opera uma instância:

```go theme={null}
_, err := client.Messages.SendText(context.Background(), vzaps.MessageSendTextRequest{
	MessageSendBaseRequest: vzaps.MessageSendBaseRequest{
		InstanceScopedRequest: vzaps.InstanceScopedRequest{
			InstanceID:    "VZ...",
			InstanceToken: os.Getenv("VZAPS_INSTANCE_TOKEN"),
		},
		Phone: "5511999999999",
	},
	Message: "Olá da VZaps",
})
```

## Autenticação automática

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

Raramente precisa chamar `Auth.GetAccessToken()` manualmente. Quando integrar com lógica customizada:

```go theme={null}
accessToken, err := client.Auth.GetAccessToken(ctx)
```

## Opções do cliente

| Opção          | Tipo              | Padrão               | Uso                                                            |
| -------------- | ----------------- | -------------------- | -------------------------------------------------------------- |
| `ClientToken`  | `string`          | -                    | Obrigatório. Token de cliente da conta.                        |
| `ClientSecret` | `string`          | -                    | Obrigatório. Segredo da conta.                                 |
| `Timeout`      | `time.Duration`   | `30s`                | Timeout HTTP.                                                  |
| `TokenSkew`    | `time.Duration`   | `1m`                 | Renovar JWT antes da expiração real.                           |
| `HTTPClient`   | `HTTPDoer`        | `http.DefaultClient` | Transporte HTTP customizado em testes ou runtimes específicos. |
| `Dialer`       | `WebSocketDialer` | gorilla padrão       | Transporte WebSocket para realtime.                            |
| `UserAgent`    | `string`          | -                    | Header `User-Agent` nas requisições HTTP.                      |

## Variáveis de ambiente recomendadas

```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

Métodos de recurso retornam `map[string]any` porque a API pode evoluir. Deserialize em structs próprias ou use `client.Request` com saída tipada:

```go theme={null}
var instance map[string]any
err := client.Request(ctx, http.MethodPost, "/instances/get", vzaps.RequestOptions{
	Body: map[string]string{"id": "VZ..."},
}, &instance)
```

Para listas, defina structs com tags `json` no formato da API pública.

## Próximos passos

* Siga o [Starter Guide](/pt-BR/sdk/go/starter-guide) para criar uma instância, assinar, parear e enviar a primeira mensagem.
* Veja [Mensagens](/pt-BR/sdk/go/messages) para todos os tipos de envio.
* Veja [Instâncias e billing](/pt-BR/sdk/go/instances-and-billing), [Sessão](/pt-BR/sdk/go/session) e [Chats](/pt-BR/sdk/go/chats) para recursos centrais da instância.
* Veja [Webhooks](/pt-BR/sdk/go/webhooks), [Filas](/pt-BR/sdk/go/queues), [Grupos](/pt-BR/sdk/go/groups), [TypeBot](/pt-BR/sdk/go/typebot) e [Chatwoot](/pt-BR/sdk/go/chatwoot) para configuração e integrações.