# Pool de números

> Liste e gerencie os números de teste atribuídos a um projeto do Sandbox.

Números de teste exigem acesso da equipe ao beta. Quando o beta é oferecido,
um proprietário ou administrador da equipe abre [Recursos opcionais](https://docs.polymorfa.com/teams/opt-in-features),
seleciona **Números de teste** e **Participar**, revisa os termos e seleciona
**Aceitar e participar**. O Inspector aparece separadamente na mesma lista. Sem acesso a números de
teste, a criação e o uso ficam bloqueados; os números existentes continuam
disponíveis para consulta, parada e exclusão.

Cada projeto do Sandbox pode ter números de teste próprios do projeto. Eles são
sessões com `testMode` e não se conectam a destinatários reais do WhatsApp.

## Listar números

Uma chave de equipe com `sessions:read` pode listar as sessões do projeto:

```bash cURL
curl "https://api.polymorfa.com/platform/sessions?projectId=$PROJECT_ID" \
  -H "Authorization: Bearer $POLYMORFA_TEAM_KEY"
```

```typescript TypeScript
const numbers = await platform.sessions.list({ projectId: "<project-id>" });
const testNumbers = numbers.data.data.filter(number => number.testMode);
```

As linhas de números de teste têm `testMode: true`. Use o identificador de
sessão e o telefone retornados em vez de presumir uma quantidade fixa de números
ou um formato de número.

## Adicionar um número de teste

Use a Platform API pública com uma chave de equipe:

```bash
curl -X POST "https://api.polymorfa.com/platform/sessions/testing" \
  -H "Authorization: Bearer $POLYMORFA_TEAM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "<project UUID>",
    "name": "CI sender",
    "country": "US"
  }'
```

`projectId` é obrigatório. `country` aceita qualquer um dos 243 códigos de país
ISO alfa-2 compatíveis com o WhatsApp e tem `US` como padrão. O seletor de país
do Console mostra a lista completa e pesquisável, com bandeiras, nomes de
países, nomes curtos e códigos de discagem. Se você omitir `name`, o nome fica
vazio e o Console e o Inspector usam o número de telefone gerado como rótulo de
fallback. Os metadados de formato de telefone validam a identidade gerada
internamente. Uma resposta de criação bem-sucedida significa que o dispositivo
controlado pela API está conectado e pronto.

Números de teste se comunicam apenas com números de teste ativos do mesmo
projeto. Enviar para um destinatário malformado, desconhecido, parado, removido
ou de outro projeto retorna a mesma resposta `404 Not Found`. O envio rejeitado
não cria conversa, contato, mensagem nem estado de destinatário. Mensagens,
mídia, grupos, canais, contatos, presença, perfis, catálogos comerciais e outras
ações públicas de sessão atualizam uma única conta simulada compartilhada, que
fica visível tanto no dispositivo controlado pela API quanto no Inspector. O
dispositivo controlado pela API aceita uma mensagem enquanto o Inspector do
destinatário está fechado e entrega a mensagem pendente quando ele se
reconecta. Remover o destinatário cancela as mensagens pendentes dele.

O Inspector conclui a inicialização normal do cliente com a sessão simulada.
Recursos opcionais do WhatsApp que não são simulados ficam indisponíveis sem
interromper as mensagens nem reconectar o número de teste.

## Iniciar, parar ou remover um número de teste

Use uma chave de equipe com `sessions:manage`. A
[chave de teste](https://docs.polymorfa.com/testing/test-key) do projeto também inicia, para e reinicia
os números de teste dele, mas não os remove.

```bash cURL
curl -X POST \
  "https://api.polymorfa.com/platform/sessions/$SESSION_ID/start" \
  -H "Authorization: Bearer $POLYMORFA_TEAM_KEY"
```

```typescript TypeScript
await platform.sessions.start("<number-id>", { projectId: "<project-id>" });
```

```bash cURL
curl -X POST \
  "https://api.polymorfa.com/platform/sessions/$SESSION_ID/stop" \
  -H "Authorization: Bearer $POLYMORFA_TEAM_KEY"
```

```typescript TypeScript
await platform.sessions.stop("<number-id>", { projectId: "<project-id>" });
```

```bash cURL
curl -X DELETE \
  "https://api.polymorfa.com/platform/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $POLYMORFA_TEAM_KEY"
```

```typescript TypeScript
await platform.sessions.delete("<number-id>");
```

*TypeScript:*

`delete` e `deleteMany` removem apenas números de teste.

Parar mantém o registro e as configurações do número de teste sem desvincular um
dispositivo do Inspector que seja dono da sessão. As respostas de início, parada
e reinício confirmam o recebimento da solicitação. Confira o status do número
antes de considerar a ação concluída. Repetir uma solicitação de início ou
reinício ainda pendente mantém a mesma tentativa. Se a limpeza anterior ainda
não foi confirmada, resolva essa pendência antes de iniciar outra tentativa.

A remoção fecha uma sessão aberta do Inspector e limpa o estado simulado do
número antes de o registro sumir. Se
não for possível fechar o número, a solicitação de remoção falha e mantém o
registro disponível para você tentar novamente. A remoção é permanente. Números
de teste não têm histórico retido pelo armazenamento hospedado de mensagens e
não podem entrar em contato com destinatários reais.

Use uma chave de equipe ou um token de projeto com `sessions:manage` para
iniciar, parar ou remover um número de teste.

- **[Inspector: propriedade e dispositivos](https://docs.polymorfa.com/pt-br/testing/inspector/devices)**
Abra uma sessão de teste no app para desktop.

- **[Eventos de teste](https://docs.polymorfa.com/pt-br/testing/test-events)**
Envie eventos de webhook de teste assinados.
