> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conta de teste

> Crie, atualize e exclua lotes de contas de teste do XBOX, acompanhe os trabalhos de criação, leia os lotes com suas contas e verifique se o acesso do lote de uma conta expirou.

As contas de teste do XBOX são criadas em lotes para um vendedor do Partner Center. Estes comandos criam,
atualizam e excluem lotes, acompanham o trabalho que cria as contas e leem os lotes e as
contas que eles contêm. Eles não podem alterar contas individuais e nunca retornam senhas. Sua
conta precisa da função de conta de teste do Partner Center para o vendedor.

Todos os comandos aceitam `--seller-id`. Sem essa opção, o comando usa `XBOX_SELLER_ID` ou o vendedor
salvo com [`xbox context set`](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/context) e, em seguida, seu único vendedor; se você tiver vários,
passe `--seller-id`.

## Comandos

| Comando | Descrição |
| - | - |
| `test-account batch list` | Lista os lotes de contas de teste do vendedor, do mais recente para o mais antigo. |
| `test-account batch get <batch-id>` | Mostra um lote e suas contas. |
| `test-account get <email>` | Encontra o lote que contém uma conta e informa se o acesso dele expirou. Consulte [Consultar uma conta](#looking-up-an-account). |
| `test-account batch create` | Cria um lote de contas de teste e aguarda o trabalho de criação dele. Consulte [Criar um lote](#creating-a-batch). |
| `test-account batch update <batch-id>` | Altera as sandboxes, a expiração do acesso às sandboxes ou as marcas de um lote e aguarda até que o lote as mostre. Consulte [Atualizar um lote](#updating-a-batch). |
| `test-account batch delete <batch-id>` | Exclui um lote e aguarda até que ele deixe de existir. Consulte [Excluir um lote](#deleting-a-batch). |
| `test-account job get <job-id>` | Mostra o estado de um trabalho de criação uma vez. |
| `test-account job wait <job-id>` | Aguarda um trabalho de criação até que ele pare de ser executado ou a espera atinja o tempo limite. |

`batch create`, `batch update` e `batch delete` pedem confirmação antes de alterar qualquer coisa e são
enviados uma única vez, sem novas tentativas. Consulte [Segurança e operações destrutivas](https://docs.xbox.com/pt-BR/tools/xbox-cli/safety.md).

## Opções para ler lotes

| Opção | Comandos | Descrição |
| - | - | - |
| `--seller-id <id>` | `batch list`, `batch get`, `test-account get` | ID do vendedor no Partner Center. |
| `--mine` | `list` | Somente os lotes que você criou. Não pode ser combinada com `--created-by-id`. |
| `--created-by-id <id>` | `list` | Somente os lotes criados por esta ID numérica de usuário do Partner Center. Não pode ser combinada com `--mine`. |
| `--email-prefix <text>` | `list` | Somente os lotes cujo modelo de email começa com este texto, sem diferenciar maiúsculas de minúsculas. |
| `--tag <tag>` | `list` | Somente os lotes com exatamente esta marca. Aceita um valor. |
| `--state <state>` | `list` | `complete` ou `pending`, em minúsculas. |
| `--limit <count>` | `list` | Retorna no máximo esta quantidade dos lotes correspondentes mais recentes. |
| `--include-sandboxes` | `list` | Retorna também as marcas (`keywords`) e o `sandboxAccess` de cada lote. Sem `--limit`, lista no máximo os 10 lotes correspondentes mais recentes; defina `--limit` para listar mais. |
| `--expired` | `list` | Somente os lotes cujo acesso às sandboxes expirou. Nesse caso, `--limit` se aplica aos lotes expirados. Consulte [Lotes expirados](#expired-batches). |
| `--output <format>` | `batch list`, `batch get`, `test-account get` | `json` (padrão), `json-compact` ou `table`. |

As marcas aparecem como `keywords` na saída JSON e em códigos de erro como
`test_account_keyword_invalid`. `--tag` corresponde a uma marca inteira, e não a parte dela.

Se você não puder ler todos os lotes do vendedor, não receberá nenhum erro: `batch list` retornará somente os
lotes que você criou.

### Lotes expirados

Um lote expira quando sua `accessExpirationDate`, a data em que o acesso às sandboxes termina,
passa. Um lote sem data nunca expira. A expiração não indica se as contas ainda podem
entrar.

`batch list --expired` lê a lista inteira do vendedor para encontrar os lotes expirados; por isso, é
mais lento para um vendedor com muitos lotes. Não pode ser combinado com `--include-sandboxes`; execute
`batch get` em um lote expirado para ver o acesso às sandboxes dele.

## Formato da resposta

`list` retorna:

```json theme={null}
{
  "batches": [
    {
      "id": 123456,
      "emailTemplate": "ABCDEF-smoke",
      "batchSize": 2,
      "createdBy": 7654321,
      "familyPermission": "Adult",
      "creationDate": "2026-09-12T04:00:00+00:00",
      "accessExpirationDate": "2027-03-12T04:00:00+00:00",
      "locale": "en-US",
      "keywords": null,
      "sandboxAccess": null,
      "isComplete": true,
      "jobId": null,
      "progress": null
    }
  ]
}
```

* `keywords` e `sandboxAccess` são `null`, a menos que você passe `--include-sandboxes`. `get`
  sempre os retorna.
* `isComplete` significa que o trabalho de criação parou, e não que todas as contas foram criadas. Compare
  o número de contas de `get` com `batchSize` e leia `progress` para ver a mensagem de
  status.
* `createdBy` é uma ID numérica de usuário do Partner Center.
* `jobId` é o trabalho em execução do lote e passa a ser `null` quando o trabalho para. Os trabalhos de atualização e exclusão
  também aparecem aqui, mas somente um trabalho de criação pode ser acompanhado com
  [`job wait`](#following-a-creation-job).

`get` retorna o mesmo objeto de lote, além das contas dele:

```json theme={null}
{
  "batch": { "id": 123456, "batchSize": 2, "isComplete": true },
  "accounts": [
    {
      "xuid": "2814600000000001",
      "email": "ABCDEF-smoke-1@example.com",
      "gamertag": "SmokeOne",
      "isDeleted": false
    }
  ]
}
```

Cada conta tem somente `xuid`, `email`, `gamertag` e `isDeleted`. `xuid` é uma cadeia de caracteres.

## Erros ao ler lotes

`batch list`, `batch get` e `test-account get` saem com o código 1 em caso de falha. Quando o serviço retorna
um erro JSON, stderr recebe um erro JSON com `status`, `title`, `detail`, `code` quando a
resposta inclui um, e seu `correlationId`; a maioria adiciona uma dica em `detail`. Outras falhas
imprimem uma linha de texto. Verifique o código de saída antes de analisar stderr.

| Status | Significado |
| - | - |
| 400 | Um filtro foi rejeitado, ou você tem vários vendedores e não escolheu um; passe `--seller-id`. |
| 403 | Você não é membro deste vendedor ou não tem a função de conta de teste do Partner Center para ele. Para `batch get`, o lote pode pertencer a outro vendedor (passe `--seller-id`), ou outro desenvolvedor o criou e você não pode ler todos os lotes do vendedor. Se o erro solicitar que você entre novamente, faça isso. |
| 404 | Não existe nenhum lote com essa ID, ou as contas de teste ainda não estão disponíveis. |
| 429 | Com o código `rate_limited`, você enviou solicitações demais em pouco tempo. O erro inclui `retryAfterSeconds`; consulte [Limites de taxa](https://docs.xbox.com/pt-BR/tools/xbox-cli/cli-for-agents.md#rate-limits). |
| 502 | O serviço não conseguiu concluir a solicitação; tente novamente. O serviço pode retornar 502 em vez de 403 quando você não tem a função de conta de teste ou, para `batch get`, quando outro desenvolvedor criou o lote. Com uma conta Microsoft pessoal, tentar novamente não ajuda; consulte [Problemas conhecidos](https://docs.xbox.com/pt-BR/tools/xbox-cli/known-issues.md#some-commands-dont-work-yet-with-a-personal-microsoft-account). |
| 503 | As contas de teste não estão disponíveis. |
| 504 | O serviço não respondeu a tempo; tente novamente. |

## Consultar uma conta

`test-account get <email>` informa se o lote que contém uma conta expirou. O email
deve terminar com `@xboxtest.com`. O comando pesquisa os 10 lotes mais recentes cujo modelo de email
corresponde ao nome da conta. Quando não encontra a conta neles, ele informa que os lotes mais antigos
não foram pesquisados e imprime os comandos `batch list` e `batch get` para que você os verifique
por conta própria.

Ele retorna o seguinte, abreviado aqui; `batch` contém todos os campos de lote que `batch list`
retorna:

```json theme={null}
{
  "account": { "xuid": "2814600000000001", "email": "ABCD-tester00007@xboxtest.com", "gamertag": "TesterSeven", "isDeleted": false },
  "batch": { "id": 123456, "emailTemplate": "ABCD-tester", "accessExpirationDate": "2026-01-01T00:00:00+00:00" },
  "expired": true,
  "expiredOn": "2026-01-01T00:00:00+00:00"
}
```

`expiredOn` é `null` quando o lote não expirou. Uma conta excluída é relatada somente quando não
existe nenhuma cópia ativa, com `account.isDeleted` definido. O comando sai com 0 sempre que encontra a
conta, expirada ou não; portanto, os scripts devem ler `expired`. Ele sai com 1 quando:

* A conta não está nos lotes que você pode ver. Ela pode pertencer a outro vendedor; então, tente
  `--seller-id`, ou outro desenvolvedor criou o lote dela e você não pode ler todos os lotes
  do vendedor.
* O email aparece em mais de um lote. stderr lista um comando `batch get` para cada um.
* Uma solicitação falha, como em [Erros ao ler lotes](#errors-when-reading-batches).

## Criar um lote

`batch create` inicia um trabalho que cria as contas e, em seguida, aguarda até que ele pare. As contas
contam para o limite de contas de teste do vendedor até que o lote seja
[excluído](#deleting-a-batch).

Em um terminal, o comando mostra o [seletor de pergunta de segurança](#choosing-a-security-question),
lista os valores que enviará, incluindo os padrões das opções que você omitiu, e pede sua
confirmação. Em seguida, ele [solicita](#secrets) a senha e a resposta de segurança, entra e envia
a solicitação. `--confirm` (`--yes`, `-y`) ignora somente a confirmação.

Sem um terminal, passe `--password-file`, `--security-answer-file` e `--confirm`. Sem
`--confirm`, o comando imprime os valores, recusa-se a continuar e não envia nada.

| Opção | Descrição |
| - | - |
| `--email-prefix <text>` | Obrigatória. O grupo de sandboxes, um hífen e um modelo, por exemplo `ABCD-tester`. O grupo de sandboxes é a parte da ID da sandbox antes do ponto, como `ABCD` em `ABCD.1`. |
| `--count <count>` | Obrigatória. Número de contas a serem criadas; no mínimo 1. O serviço define o máximo. |
| `--sandbox-id <id>` | Obrigatória. Uma sandbox que as contas podem acessar. Repita para adicionar mais sandboxes. |
| `--password-file <path>` | Arquivo que contém a senha da conta, ou `-` para stdin. Consulte [Segredos](#secrets). |
| `--security-answer-file <path>` | Arquivo que contém a resposta de segurança, ou `-` para stdin. Consulte [Segredos](#secrets). |
| `--child-count <count>` | Total de contas infantis no lote, todas vinculadas à primeira conta; 0 ou mais. `--count 5 --child-count 2` cria 5 contas e 2 contas infantis, e não 2 para cada uma. O serviço define o máximo. |
| `--first-name <text>` | O padrão é `Test`. |
| `--last-name <text>` | O padrão é `Account`. |
| `--security-question <text>` | A pergunta de segurança que todas as contas recebem. Consulte [Escolher uma pergunta de segurança](#choosing-a-security-question). |
| `--alternate-email <text>` | O padrão é seu email. |
| `--access-expiration <date>` | Quando o acesso às sandboxes expira, como `2026-12-31`, interpretado como UTC. O padrão é daqui a três meses. |
| `--tag <tag>` | Uma marca a ser armazenada no lote, que `batch list --tag` pode encontrar depois. Repita para adicionar mais marcas. |
| `--locale <locale>` | O padrão é `en-US`. |
| `--subscription <name>` | O nível das contas para os serviços do XBOX, `Silver` ou `Gold`, sem diferenciar maiúsculas de minúsculas. O padrão é `Gold`. |
| `--seller-id <id>` | Vendedor para o qual as contas serão criadas. |
| `--confirm`, `--yes`, `-y` | Cria sem o prompt de confirmação. |
| `--no-wait` | Retorna assim que o serviço aceita o trabalho. Não pode ser combinada com `--timeout`. |
| `--timeout <duration>` | Por quanto tempo aguardar o trabalho, como `90s`, `10m`, `2h` ou `1d`. O padrão é `5m`; no máximo `7d`. |
| `--output <format>` | `json` (padrão), `json-compact` ou `table`. |

### Escolher uma pergunta de segurança

Em um terminal, quando você não passa `--security-question` nem `--security-answer-file`, o
comando mostra um seletor numerado com estas perguntas. Enter seleciona a primeira. Para escolher uma
sem o seletor, passe o texto dela com `--security-question`:

1. What is your favorite hobby?
2. Who is your favorite athlete?
3. What is your maternal grandmother's first name?
4. What was your childhood best friend's first name?
5. What was the name of your first pet?
6. What is your current best friend's first name?
7. What was your favorite city to visit as a child?

Sem um terminal, ou com um arquivo de resposta e nenhuma pergunta, a pergunta é
`What is your favorite hobby?`. Pressionar Ctrl+C no seletor cancela sem criar nada.
Escolher uma pergunta não confirma a criação.

### Segredos

A senha e a resposta de segurança nunca são aceitas como valores de opção ou variáveis de
ambiente, para que fiquem fora do histórico do shell, das listagens de processos e dos logs. Cada uma vem de:

* Seu `--password-file` ou `--security-answer-file`. Uma única quebra de linha no final é removida.
* `-` no lugar de um caminho, o que a lê de stdin. Somente uma das duas pode ler stdin.
* Sem opção de arquivo, um prompt no terminal que não exibe o que você digita.

A senha deve ter de 8 a 16 caracteres e conter pelo menos três destes tipos: letras minúsculas,
letras maiúsculas, números e símbolos. O sublinhado não conta como símbolo. A senha
não pode ser igual à resposta de segurança.

### Espera e códigos de saída

Enquanto aguarda, o comando imprime o progresso em stderr. Ele grava o trabalho final em stdout, no
mesmo formato de [`job get`](#following-a-creation-job).

| Código de saída | Significado |
| - | - |
| 0 | O trabalho foi bem-sucedido ou foi aceito com `--no-wait`. stderr fornece o comando para acompanhá-lo. |
| 1 | Nada foi criado: a solicitação foi recusada ou rejeitada, falhou ou foi cancelada antes de ser enviada, ou recebeu um 503 com `feature_disabled` ou `service_configuration_invalid`. |
| 2 | O trabalho falhou. Algumas contas podem ter sido criadas; stderr fornece as contagens e o comando para inspecionar o lote. |
| 3 | O resultado é desconhecido. Consulte [Quando o resultado é desconhecido](#when-the-outcome-is-unknown). |
| 4 | O lote existe, mas a espera terminou antes que o trabalho parasse: o `--timeout` passou, você pressionou Ctrl+C ou a leitura do trabalho falhou. O trabalho continua em execução. stderr fornece o comando para retomar a espera. Não crie novamente. |

### Quando o resultado é desconhecido

Quando a CLI não consegue determinar se o serviço criou um lote, por exemplo quando a conexão cai
depois que a solicitação é enviada ou o serviço retorna um erro `5xx`, ela sai com 3. Ela nunca envia a
criação novamente. stderr imprime a hora em que a solicitação começou, em UTC, e estas etapas:

1. Aguarde alguns minutos; um lote que ainda está sendo criado pode não estar listado ainda.
2. Execute `xbox test-account batch list --mine --email-prefix <prefix>` e procure um lote com
   o mesmo prefixo de email e modelo criado nessa hora ou depois dela.
3. Se o `jobId` desse lote estiver definido, acompanhe-o com
   `xbox test-account job wait <job-id> --batch-id <batch-id>`. Se `jobId` for `null`, o trabalho
   parou; inspecione-o com `xbox test-account batch get <batch-id>`.
4. Crie novamente somente se esse lote não existir.

Os comandos impressos mantêm as opções de vendedor, perfil e entrada que você usou; portanto, você pode copiá-los
como estão.

### Erros ao criar

As falhas gravam em stderr um erro JSON com `status`, `title`, `detail` e `code` quando a
resposta inclui um. Ramifique com base em `code`, e não em `detail`.

| Código | Significado |
| - | - |
| `test_account_sandbox_access_denied` | Você não pode conceder acesso a um dos valores de `--sandbox-id`. Se todas as sandboxes forem recusadas, sua conta pode não estar vinculada ao vendedor, o vendedor pode não ter sandboxes ou o Partner Center pode não permitir que você gerencie contas de teste. |
| `test_account_count_invalid` | `--count` está fora do que o serviço permite. |
| `test_account_child_count_invalid` | `--child-count` está fora do que o serviço permite. |
| `test_account_email_prefix_invalid` | `--email-prefix` não é um grupo de sandboxes, um hífen e um modelo, como `ABCD-tester`. |
| `test_account_name_invalid` | `--first-name` ou `--last-name` foi rejeitado. |
| `test_account_password_invalid` | A senha não atende às regras de senha. |
| `test_account_security_question_invalid` | `--security-question` foi rejeitada. |
| `test_account_security_answer_invalid` | A resposta de segurança foi rejeitada, por exemplo porque é igual à senha ou aparece na pergunta de segurança. |
| `test_account_alternate_email_invalid` | `--alternate-email` foi rejeitado. |
| `test_account_keyword_invalid` | Um valor de `--tag` foi rejeitado, ou há valores demais. |
| `test_account_locale_invalid` | `--locale` não tem suporte; tente `en-US`. |
| `test_account_subscription_unavailable` | Essa `--subscription` não está disponível; tente `--subscription Silver`. |
| `test_account_limit_exceeded` | O vendedor atingiu o limite de contas de teste. |
| `test_account_access_denied` | Você não tem a função do Partner Center para criar contas de teste para este vendedor. |
| `test_account_create_outcome_unknown` | Código de saída 3; consulte [Quando o resultado é desconhecido](#when-the-outcome-is-unknown). |
| `downstream_request_rejected` | A solicitação foi rejeitada sem indicar um campo, por exemplo porque o grupo de `--email-prefix` não é um dos seus grupos de sandboxes ou porque a pergunta ou a resposta de segurança é longa demais. |
| `downstream_throttled` | As solicitações estão sendo limitadas e nada foi criado. Aguarde e tente novamente. |
| `rate_limited` | 429: você enviou solicitações demais em pouco tempo e nada foi criado. Consulte [Limites de taxa](https://docs.xbox.com/pt-BR/tools/xbox-cli/cli-for-agents.md#rate-limits). |
| Qualquer outro código, ou nenhum, em um 5xx | Código de saída 3, porque um lote pode existir; consulte [Quando o resultado é desconhecido](#when-the-outcome-is-unknown). |
| `feature_disabled`, `service_configuration_invalid` | 503: a criação de contas de teste não está disponível. Código de saída 1. |
| `invalid_request`, ou um `400` sem código | A solicitação estava malformada ou um valor não é permitido; `detail` ou `errors` indica o campo. Uma CLI mais recente que o serviço pode receber esse erro para uma opção à qual o serviço ainda não dá suporte. |

## Acompanhar um trabalho de criação

`batch create` imprime as IDs do lote e do trabalho assim que o trabalho é aceito. Um trabalho pode ser executado por
dias; portanto, você pode parar de aguardar a qualquer momento e acompanhá-lo depois:

| Opção | Comandos | Descrição |
| - | - | - |
| `<job-id>` | `get`, `wait` | Obrigatória. A ID do trabalho de `batch create`, ou a `jobId` de um lote de `batch list`. |
| `--batch-id <id>` | `get`, `wait` | Obrigatória. O lote ao qual o trabalho pertence. |
| `--seller-id <id>` | `get`, `wait` | Vendedor proprietário do lote. |
| `--timeout <duration>` | `wait` | Por quanto tempo aguardar, como `90s`, `10m`, `2h` ou `1d`. O padrão é `5m`; no máximo `7d`. |
| `--output <format>` | `get`, `wait` | `json` (padrão), `json-compact` ou `table`. |

Ambos retornam o trabalho:

```json theme={null}
{
  "batchId": 123456,
  "jobId": "0f8e5b2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "state": "running",
  "total": 5,
  "succeeded": 3,
  "failed": 0,
  "errorCode": null,
  "errorMessage": null,
  "progress": "Creating accounts"
}
```

`state` é `running`, `succeeded` ou `failed`. `errorCode` é `test_account_job_failed` quando o
trabalho falhou. `job wait` tenta novamente as falhas temporárias de leitura, como limitação ou uma
conexão perdida.

| Código de saída | `job get` | `job wait` |
| - | - | - |
| 0 | Em execução ou bem-sucedido | Bem-sucedido |
| 1 | A solicitação falhou | A primeira leitura falhou, por exemplo devido a uma ID de trabalho ou de lote incorreta; nada é gravado em stdout |
| 2 | Falhou | Falhou |
| 4 | Não usado | A espera terminou antes que o trabalho parasse: o `--timeout` passou, você pressionou Ctrl+C ou a leitura do trabalho falhou. O trabalho continua em execução. stderr fornece o comando para retomar a espera; execute-o depois que o erro em stderr for corrigido ou desaparecer. |

### Erros ao acompanhar um trabalho

Estes códigos de erro apontam para a ID do trabalho, `--batch-id` ou `--seller-id`:

| `code` | Significado |
| - | - |
| `test_account_job_not_in_batch` | 404: o trabalho não está no lote indicado por `--batch-id`. |
| `test_account_batch_not_found` | 404: esse lote não existe para este vendedor. |
| `downstream_request_rejected` | 404: não existe nenhum trabalho com essa ID. |
| `test_account_access_denied` | 403: o lote ou o trabalho pertence a outro vendedor; portanto, `--batch-id` ou `--seller-id` pode estar incorreto. Caso contrário, outro desenvolvedor iniciou o trabalho e você não pode ler todos os lotes do vendedor. |

## Atualizar um lote

`batch update` altera todas as contas de um lote: ele pode conceder a elas acesso a mais sandboxes,
remover o acesso, mudar quando esse acesso expira e adicionar marcas ao lote ou substituí-las. Em
seguida, ele aguarda até que o lote mostre a alteração.

Em um terminal, o comando primeiro mostra cada alteração solicitada ao lado do valor atual do lote,
avisa quando um trabalho ainda está em execução no lote e pede confirmação. Passe `--confirm` (`--yes`,
`-y`) para ignorar o prompt. Sem um terminal e sem `--confirm`, ele imprime as alterações,
recusa-se a continuar e não envia nada.

| Opção | Descrição |
| - | - |
| `<batch-id>` | Obrigatória. A ID do lote, de `batch list` ou `batch create`. |
| `--add-sandbox-id <id>` | Sandbox à qual conceder acesso às contas. Repita para adicionar mais sandboxes. |
| `--remove-sandbox-id <id>` | Sandbox da qual remover o acesso das contas. Repita para adicionar mais sandboxes. Uma sandbox não pode ser adicionada e removida ao mesmo tempo. |
| `--access-expiration <date>` | Nova data em que o acesso das contas às sandboxes expira, como `2026-12-31`. Ela deve estar no futuro, e o serviço mantém somente o dia. O serviço recusa essa opção para um lote sem sandboxes. |
| `--tag <tag>` | Marca a ser adicionada ao lote, com no máximo 100 caracteres. Uma marca que o lote já tem, sem diferenciar maiúsculas de minúsculas, é ignorada. Repita para adicionar mais marcas. Não pode ser combinada com `--clear-tags`. |
| `--replace-tags` | Substitui todas as marcas do lote pelos valores de `--tag`. Exige `--tag`. Aqui, maiúsculas e minúsculas importam; portanto, substituir `smoke` por `Smoke` é uma alteração. |
| `--clear-tags` | Remove todas as marcas do lote. |
| `--allow-not-mine` | Permite alterar um lote criado por outro desenvolvedor. Sem ela, a atualização é recusada com `test_account_batch_not_owned`. Suas permissões ainda podem recusá-la. |
| `--seller-id <id>` | Vendedor proprietário do lote. |
| `--confirm`, `--yes`, `-y` | Atualiza sem o prompt de confirmação. |
| `--no-wait` | Retorna assim que o serviço aceita a atualização. Não pode ser combinada com `--timeout`. |
| `--timeout <duration>` | Por quanto tempo aguardar a atualização, como `90s`, `10m` ou `2h`. O padrão é `5m`; no máximo `7d`. |
| `--output <format>` | `json` (padrão), `json-compact` ou `table`. |

Passe pelo menos uma alteração. Um lote pode ter no máximo 20 marcas. `--replace-tags` e
`--clear-tags` mantêm a marca que registra qual ferramenta criou o lote, que não conta
para o limite. Alterar sandboxes ou a expiração exige acesso a essas sandboxes;
estender a expiração exige acesso a todas as sandboxes do lote.

O comando retorna os valores do lote quando a atualização é concluída:

```json theme={null}
{
  "batchId": 123456,
  "jobId": "0f8e5b2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "state": "updated",
  "sandboxes": ["ABCD.1", "ABCD.2"],
  "accessExpirationDate": "2026-12-31T00:00:00+00:00",
  "keywords": ["smoke"]
}
```

`state` é `updated` quando o lote mostra a alteração, ou `updating` com `--no-wait` ou quando
a espera termina antes. Quando o lote já tem todos os valores solicitados, nada muda:
`state` é `unchanged`, `jobId` é `null` e o comando sai com 0. Os trabalhos de atualização não podem ser
acompanhados com `job get` ou `job wait`.

### Espera e códigos de saída ao atualizar

| Código de saída | Significado |
| - | - |
| 0 | O lote mostra a alteração, já tinha esses valores ou a atualização foi aceita com `--no-wait`. |
| 1 | Nada foi alterado: a solicitação foi recusada ou rejeitada, falhou antes de ser enviada, o lote não pôde ser lido antes do prompt ou você recusou. |
| 2 | O trabalho de atualização terminou, mas o lote não mostra a alteração. stderr indica os campos que diferem. Leia o lote com `batch get` e atualize-o novamente. |
| 3 | O resultado é desconhecido. Leia o lote com o comando `batch get` impresso antes de atualizar novamente. Quando nenhum trabalho estiver em execução, enviar a mesma alteração novamente é seguro. |
| 4 | A atualização foi aceita, mas a espera terminou enquanto ela ainda estava em execução: o `--timeout` passou, você pressionou Ctrl+C ou a leitura do lote falhou. Uma `jobId` que nunca é limpa sugere que o trabalho falhou ou travou. |

### Erros ao atualizar

| `code` | Significado |
| - | - |
| `test_account_batch_not_owned` | 403: outro desenvolvedor criou o lote. Passe `--allow-not-mine` para remover essa verificação. |
| `test_account_sandbox_access_denied` | 403: você não tem acesso a uma sandbox da alteração. Estender a expiração exige acesso a todas as sandboxes do lote. |
| `test_account_batch_not_found` | 404: esse lote não existe para este vendedor. |
| `test_account_batch_busy` | 409: um trabalho está em execução no lote. Aguarde até que `batch get` mostre `jobId` como `null`. |
| `test_account_keyword_invalid` | 400: um valor de `--tag` não é permitido. |
| `test_account_access_denied` | Você não tem a função do Partner Center para gerenciar contas de teste para este vendedor ou, com `--allow-not-mine`, para alterar um lote que você não criou. |
| `downstream_throttled` | As solicitações estão sendo limitadas. Aguarde e tente novamente. |
| `rate_limited` | 429: você enviou solicitações demais em pouco tempo. Consulte [Limites de taxa](https://docs.xbox.com/pt-BR/tools/xbox-cli/cli-for-agents.md#rate-limits). |
| `test_account_update_outcome_unknown` | 502: código de saída 3. |
| `feature_disabled`, `service_configuration_invalid` | 503: as contas de teste não estão disponíveis. Código de saída 1. |

Um `404` ou `405` sem código significa que a atualização de lotes não está disponível.

## Excluir um lote

`batch delete` exclui um lote inteiro e, em seguida, aguarda até que ele deixe de existir. Todas as contas do lote
perdem o acesso às sandboxes, e o registro de conta de teste delas é excluído. As contas
Microsoft e os perfis do XBOX das contas não são encerrados.

Em um terminal, o comando primeiro mostra o modelo de email, o tamanho e o criador do lote, avisa
quando um trabalho ainda está em execução nele e pede confirmação. Passe `--confirm` (`--yes`, `-y`) para ignorar o
prompt. Sem um terminal e sem `--confirm`, ele imprime o que excluiria, recusa-se a continuar
e não envia nada. Não há exclusão em massa; exclua os lotes um de cada vez.

| Opção | Descrição |
| - | - |
| `<batch-id>` | Obrigatória. A ID do lote, de `batch list` ou `batch create`. |
| `--allow-not-mine` | Permite excluir um lote criado por outro desenvolvedor. Sem ela, a exclusão é recusada com `test_account_batch_not_owned`. Suas permissões ainda podem recusá-la, com `test_account_access_denied`. |
| `--seller-id <id>` | Vendedor proprietário do lote. |
| `--confirm`, `--yes`, `-y` | Exclui sem o prompt de confirmação. |
| `--no-wait` | Retorna assim que o serviço aceita a exclusão. Não pode ser combinada com `--timeout`. |
| `--timeout <duration>` | Por quanto tempo aguardar até que o lote deixe de existir, como `90s`, `10m` ou `2h`. O padrão é `5m`; no máximo `7d`. |
| `--output <format>` | `json` (padrão), `json-compact` ou `table`. |

O comando retorna:

```json theme={null}
{
  "batchId": 123456,
  "jobId": "0f8e5b2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "state": "deleted",
  "emailTemplate": "ABCD-tester",
  "batchSize": 5
}
```

`state` é `deleted` quando o lote deixa de existir, ou `deleting` com `--no-wait` ou quando a espera
termina antes. Os trabalhos de exclusão não podem ser acompanhados com `job get` ou `job wait`; enquanto a exclusão é executada,
o lote mostra a `jobId` dela.

### Espera e códigos de saída ao excluir

| Código de saída | Significado |
| - | - |
| 0 | O lote deixou de existir ou a exclusão foi aceita com `--no-wait`. |
| 1 | Nada foi excluído: a solicitação foi recusada ou rejeitada, falhou antes de ser enviada, o lote não pôde ser lido antes do prompt ou você recusou. |
| 2 | O trabalho de exclusão parou, mas o lote ainda existe. Inspecione-o com `batch get`. |
| 3 | O resultado é desconhecido. Leia o lote com o comando `batch get` impresso: um `404` com `test_account_batch_not_found` significa que ele foi excluído, e uma `jobId` definida significa que a exclusão provavelmente está em execução. Se `jobId` for `null`, aguarde um minuto e leia-o novamente; exclua novamente somente se ainda for `null`. |
| 4 | A exclusão foi aceita, mas a espera terminou enquanto o lote ainda existia: o `--timeout` passou, você pressionou Ctrl+C ou a leitura do lote falhou. Uma `jobId` que permanece definida com `progress` inalterado sugere que a exclusão travou. |

### Erros ao excluir

| `code` | Significado |
| - | - |
| `test_account_batch_not_owned` | 403: outro desenvolvedor criou o lote; a mensagem indica a ID de usuário do Partner Center dele. Passe `--allow-not-mine` para remover essa verificação. |
| `test_account_batch_not_found` | 404: esse lote não existe para este vendedor ou já foi excluído. Somente este código significa que o lote deixou de existir. |
| `test_account_batch_busy` | 409: um trabalho está em execução no lote, o que pode ser uma exclusão já em andamento. Aguarde até que `batch get` mostre `jobId` como `null` ou retorne `404` com `test_account_batch_not_found`. |
| `test_account_access_denied` | Você não tem a função do Partner Center para gerenciar contas de teste para este vendedor ou, com `--allow-not-mine`, para excluir um lote que você não criou. |
| `downstream_throttled` | As solicitações estão sendo limitadas. Aguarde e tente novamente. |
| `rate_limited` | 429: você enviou solicitações demais em pouco tempo. Consulte [Limites de taxa](https://docs.xbox.com/pt-BR/tools/xbox-cli/cli-for-agents.md#rate-limits). |
| `test_account_delete_outcome_unknown` | 502 ou 504: código de saída 3. Um 504 sem código é tratado da mesma forma. |
| `feature_disabled`, `service_configuration_invalid` | 503: as contas de teste não estão disponíveis. Código de saída 1. |

Um `404` ou `405` sem código significa que a exclusão de lotes não está disponível.

## Saída em tabela

Todos os comandos aceitam `--output table`. Os horários são mostrados em UTC, e as linhas de resumo vão para
stderr; assim, stdout contém somente a tabela.

| Comando | Colunas |
| - | - |
| `test-account batch list` | `BATCH ID`, `EMAIL TEMPLATE`, `SIZE`, `STATE` (`complete` ou `pending`), `CREATED BY`, `CREATED (UTC)`, `EXPIRES (UTC)` e, depois, `SANDBOXES` com `--include-sandboxes`. |
| `test-account batch get` | Uma linha por conta: `EMAIL`, `GAMERTAG`, `XUID` e `DELETED`. stderr resume o lote e o acesso dele às sandboxes. |
| `test-account get` | Uma linha: `EMAIL`, `GAMERTAG`, `BATCH ID`, `EMAIL TEMPLATE`, `EXPIRES (UTC)` e `EXPIRED` (`yes` ou `no`). |
| `test-account batch create`, `job get`, `job wait` | Uma linha: `BATCH ID`, `JOB ID`, `STATE` (`running`, `succeeded` ou `failed`), `TOTAL`, `SUCCEEDED`, `FAILED`. |
| `test-account batch update` | Uma linha: `BATCH ID`, `JOB ID`, `STATE` (`updated`, `updating` ou `unchanged`), `EXPIRES (UTC)`. stderr lista as sandboxes e as palavras-chave. |
| `test-account batch delete` | Uma linha: `BATCH ID`, `JOB ID`, `STATE` (`deleted` ou `deleting`), `EMAIL TEMPLATE`, `SIZE`. |

## Exemplos

Estes comandos listam e leem lotes, contas e trabalhos:

```bash theme={null}
xbox test-account batch list --mine --limit 5

xbox test-account batch list --state pending --output table

xbox test-account batch list --email-prefix ABCDEF-smoke --include-sandboxes

xbox test-account batch get 123456 --output table

xbox test-account batch list --expired --limit 10

xbox test-account get ABCD-tester00007@xboxtest.com --output table

xbox test-account batch get 123456 --seller-id 1234567 --output json-compact

xbox test-account job get 0f8e5b2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b --batch-id 123456 --output table
```

Crie um lote de cinco contas. O comando solicita a senha e a resposta de segurança
e, em seguida, pede sua confirmação:

```bash theme={null}
xbox test-account batch create --email-prefix ABCD-tester --count 5 --sandbox-id ABCD.1
```

Crie um lote sem supervisão, com os segredos lidos de arquivos, sem prompt e com uma espera de até
30 minutos:

```bash theme={null}
xbox test-account batch create --email-prefix ABCD-smoke --count 2 --sandbox-id ABCD.1 \
  --password-file ./password.txt --security-answer-file ./answer.txt \
  --subscription Silver --tag smoke --timeout 30m --confirm
```

Aguarde até duas horas para que um trabalho de criação termine:

```bash theme={null}
xbox test-account job wait 0f8e5b2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b --batch-id 123456 --timeout 2h
```

Adicione uma sandbox e defina quando o acesso às sandboxes expira. O comando mostra as alterações, pede sua
confirmação e, em seguida, aguarda até que o lote as mostre:

```bash theme={null}
xbox test-account batch update 123456 --add-sandbox-id ABCD.2 --access-expiration 2026-12-31
```

Adicione duas marcas sem supervisão, sem aguardar:

```bash theme={null}
xbox test-account batch update 123456 --tag smoke --tag nightly --confirm --no-wait
```

Substitua todas as marcas por uma:

```bash theme={null}
xbox test-account batch update 123456 --tag nightly --replace-tags --confirm
```

Exclua um lote. O comando mostra o lote, pede sua confirmação e, em seguida, aguarda até que ele deixe de existir:

```bash theme={null}
xbox test-account batch delete 123456
```

Exclua um lote criado por outro desenvolvedor, sem supervisão e sem aguardar:

```bash theme={null}
xbox test-account batch delete 123456 --allow-not-mine --confirm --no-wait
```


## Related topics

- [Contas de teste](https://docs.xbox.com/pt-BR/services/xbox-services/develop/test-accounts/index.md)
- [Práticas recomendadas e testes para gamertags modernas](https://docs.xbox.com/pt-BR/services/xbox-services/fundamentals/identity/user-profile/gamertags/live-modern-gamertags-best-practices-and-testing.md)
- [Visão geral das áreas restritas dos serviços do XBOX](https://docs.xbox.com/pt-BR/services/xbox-services/fundamentals/sandboxes/live-setup-sandbox.md)
- [Criar e gerenciar contas de teste do XBOX](https://docs.xbox.com/pt-BR/publishing/game-publishing/how-to/how-to-create-and-manage-test-accounts.md)
- [Solução de problemas de erros de entrada e de área restrita](https://docs.xbox.com/pt-BR/services/xbox-services/develop/troubleshooting/live-troubleshoot-sandboxes.md)
