# Ciclo de vida da instância

Uma instância representa a sessão de WhatsApp de uma empresa em um servidor. Criação, conexão, reinício e exclusão têm efeitos diferentes.

## Fluxo de integração

| Etapa | Operação | Resultado esperado |
|---|---|---|
| Criar | [POST /instance/init](https://wpp.atendro.cloud/docs/api/create-instance.md) | ID e token; estado `disconnected` |
| Preparar eventos | [POST /v1/webhook](https://wpp.atendro.cloud/docs/api/configure-global-webhook.md) | Destino global herdado pela instância |
| Conectar | [POST /instance/connect](https://wpp.atendro.cloud/docs/api/connect-instance.md) | Início de conexão, QR ou código de pareamento |
| Acompanhar | [GET /instance/status](https://wpp.atendro.cloud/docs/api/get-instance-status.md) | Estado, `connected`, `loggedIn` e resumo de webhook |
| Reiniciar sessão | [POST /instance/restart](https://wpp.atendro.cloud/docs/api/restart-instance.md) | Retoma a sessão com credenciais guardadas |
| Desvincular | [POST /instance/disconnect](https://wpp.atendro.cloud/docs/api/disconnect-instance.md) | Remove a credencial local e tenta desvincular remotamente |
| Excluir | [DELETE /instance](https://wpp.atendro.cloud/docs/api/delete-instance.md) | Remove a instância e seus dados associados |

## Criação e vínculo

O cadastro usa `admintoken`. `name` é obrigatório; `systemName` e `companyId` ajudam a identificar a integração. Guarde o vínculo servidor → empresa → ID de instância no backend do Atendro.

`kind` é fixado na criação: `whatsapp` (padrão) para mensagens e `calls` para voz. A instância de ligação tem pareamento próprio e pode usar um número dedicado ou outro dispositivo vinculado do mesmo número.

O campo `companyId` não concede autorização automaticamente. A aplicação deve validar o vínculo em cada ação e em cada evento recebido.

## Estados da sessão

| Estado | Significado |
|---|---|
| `disconnected` | Não há sessão autenticada disponível para as operações |
| `connecting` | Pareamento ou conexão em andamento |
| `connected` | Sessão conectada; considere também `connected` e `loggedIn` na resposta |

O QR é temporário. Mostre-o apenas ao usuário autorizado e consulte o status para obter uma versão vigente. Não registre QR, código de pareamento ou chaves de sessão.

## Webhook de conexão

O evento `connection` informa mudanças de estado. Configure a inscrição antes de iniciar o pareamento, porque uma URL nova começa a receber eventos após seu cadastro.

`qrcode` é aceito por compatibilidade, mas não é entregue. Obtenha o QR pelo fluxo privado de connect/status. Veja [payloads dos eventos](https://wpp.atendro.cloud/docs/guias/eventos.md).

## Reinício e desconexão

`restart` preserva a credencial de sessão. `disconnect` limpa a credencial local mesmo quando `unlinked` é `false`; nesse caso, a confirmação remota da desvinculação não ocorreu.

O reinício administrativo do worker em [POST /admin/restart](https://wpp.atendro.cloud/docs/api/admin-restart-worker.md) devolve `202` e agenda o trabalho em background. Ele não retorna uma contagem de sessões já reiniciadas.

## Sessões distribuídas

Cada sessão tem um worker dono e um lease. `409 session_owned_elsewhere` indica que a sessão está sob responsabilidade de outro worker; não crie outra instância para contornar o erro.

Uma instância conectada permite apenas os recursos anunciados por `GET /v1/capabilities`. Conexão não implica suporte a chamadas de voz.