> ## 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 PHP oficial da VZaps

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

Use este SDK quando quiser integrar a VZaps em backends PHP, CLIs, workers, comandos Laravel/Symfony, jobs e automações server-to-server.

## Requisitos

| Recurso  | Versão                          |
| -------- | ------------------------------- |
| PHP      | 8.1 ou superior                 |
| Composer | 2.x recomendado                 |
| Extensão | `json`                          |
| HTTP     | Guzzle 7, instalado pelo pacote |

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

## Instalar

```bash theme={null}
composer require vzaps/sdk
```

Para usar realtime WebSocket em CLI/worker, instale também o transporte opcional:

```bash theme={null}
composer require textalk/websocket
```

## Criar o cliente

```php theme={null}
use VZaps\Sdk\VZapsClient;

$vzaps = new VZapsClient(
    clientToken: getenv('VZAPS_CLIENT_TOKEN'),
    clientSecret: getenv('VZAPS_CLIENT_SECRET'),
);
```

## Credenciais

O SDK usa dois grupos de credenciais:

| Credencial      | Onde usar                    | Descrição                                                        |
| --------------- | ---------------------------- | ---------------------------------------------------------------- |
| `clientToken`   | `new VZapsClient()`          | Token público da conta, usado também no header `X-Client-Token`. |
| `clientSecret`  | `new VZapsClient()`          | Segredo usado pelo SDK para obter e renovar o JWT.               |
| `instanceToken` | Em cada chamada da instância | Token da instância, enviado como `X-Instance-Token`.             |

O `instanceToken` não fica no cliente global. Passe sempre na chamada que opera uma instância:

```php theme={null}
$vzaps->messages()->sendText([
    'instanceId' => 'VZ...',
    'instanceToken' => getenv('VZAPS_INSTANCE_TOKEN'),
    'phone' => '5511999999999',
    'message' => 'Olá pela VZaps',
]);
```

## Autenticação automática

O SDK obtém o JWT automaticamente usando `clientToken` e `clientSecret`, guarda o token em memória e renova antes do vencimento.

Você raramente precisa chamar o token manualmente. Quando precisar integrar com código HTTP próprio:

```php theme={null}
$accessToken = $vzaps->auth()->getAccessToken();
```

## Opções do cliente

| Opção              | Tipo                              | Padrão                               | Uso                                                 |
| ------------------ | --------------------------------- | ------------------------------------ | --------------------------------------------------- |
| `clientToken`      | `string`                          | -                                    | Obrigatório. Token da conta.                        |
| `clientSecret`     | `string`                          | -                                    | Obrigatório. Segredo da conta.                      |
| `timeoutSeconds`   | `float`                           | `30.0`                               | Timeout HTTP em segundos.                           |
| `tokenSkewSeconds` | `int`                             | `60`                                 | Renovar JWT antes do vencimento real.               |
| `httpClient`       | `Psr\Http\Client\ClientInterface` | Guzzle                               | Customizar transporte HTTP em testes, proxy ou TLS. |
| `webSocketFactory` | `callable`                        | `textalk/websocket` quando instalado | Customizar WebSocket.                               |
| `userAgent`        | `string`                          | `VZaps.SDK.PHP/<versão>`             | Header `User-Agent` em requests HTTP.               |

```php theme={null}
use GuzzleHttp\Client;
use VZaps\Sdk\VZapsClient;

$vzaps = new VZapsClient(
    clientToken: getenv('VZAPS_CLIENT_TOKEN'),
    clientSecret: getenv('VZAPS_CLIENT_SECRET'),
    timeoutSeconds: 10,
    httpClient: new Client([
        'timeout' => 10,
        'http_errors' => false,
    ]),
);
```

## Composer autoload

Em scripts PHP simples:

```php theme={null}
require __DIR__ . '/vendor/autoload.php';

use VZaps\Sdk\VZapsClient;
```

Em Laravel, Symfony e outros frameworks, use o autoload do Composer do próprio projeto e registre `VZapsClient` como service/singleton quando fizer sentido.

## Variáveis de ambiente recomendadas

```bash theme={null}
VZAPS_CLIENT_TOKEN=seu-client-token
VZAPS_CLIENT_SECRET=seu-client-secret
VZAPS_INSTANCE_ID=VZ...
VZAPS_INSTANCE_TOKEN=token-da-instância
```

## Tipagem de respostas

Por padrão, respostas são arrays PHP decodificados do JSON da API, porque o contrato pode evoluir.

```php theme={null}
/** @var array<string, mixed> $instances */
$instances = $vzaps->instances()->list([
    'page' => 1,
    'pageSize' => 20,
]);
```

Para requests principais, você pode usar DTOs com named arguments:

```php theme={null}
use VZaps\Sdk\Models\Messages\SendTextMessageRequest;

$vzaps->messages()->sendText(new SendTextMessageRequest(
    instanceId: 'VZ...',
    instanceToken: getenv('VZAPS_INSTANCE_TOKEN'),
    phone: '5511999999999',
    message: 'Olá pela VZaps',
));
```

Para campos novos ou avançados do contrato público, use arrays ou `GenericInstanceRequest`.

## Próximos passos

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