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

# Cuenta de prueba

> Crea, actualiza y elimina lotes de cuentas de prueba de XBOX, haz el seguimiento de sus trabajos de creación, lee los lotes con sus cuentas y comprueba si el acceso del lote de una cuenta ha expirado.

Las cuentas de prueba de XBOX se crean en lotes para un vendedor de Partner Center. Estos comandos crean,
actualizan y eliminan lotes, hacen el seguimiento del trabajo que crea las cuentas, y leen los lotes y las
cuentas que contienen. No pueden cambiar cuentas individuales y nunca devuelven contraseñas. Tu
cuenta necesita el rol de cuentas de prueba de Partner Center para el vendedor.

Todos los comandos aceptan `--seller-id`. Sin esta opción, un comando usa `XBOX_SELLER_ID` o el vendedor
guardado con [`xbox context set`](https://docs.xbox.com/es/tools/xbox-cli/commands/context) y, después, tu único vendedor; si tienes varios,
pasa `--seller-id`.

## Comandos

| Comando | Descripción |
| - | - |
| `test-account batch list` | Enumera los lotes de cuentas de prueba del vendedor, del más reciente al más antiguo. |
| `test-account batch get <batch-id>` | Muestra un lote y sus cuentas. |
| `test-account get <email>` | Busca el lote que contiene una cuenta e informa de si su acceso ha expirado. Consulta [Búsqueda de una cuenta](#looking-up-an-account). |
| `test-account batch create` | Crea un lote de cuentas de prueba y espera a su trabajo de creación. Consulta [Creación de un lote](#creating-a-batch). |
| `test-account batch update <batch-id>` | Cambia los sandboxes de un lote, la expiración del acceso a los sandboxes o las etiquetas, y espera hasta que el lote los muestre. Consulta [Actualización de un lote](#updating-a-batch). |
| `test-account batch delete <batch-id>` | Elimina un lote y espera hasta que desaparezca. Consulta [Eliminación de un lote](#deleting-a-batch). |
| `test-account job get <job-id>` | Muestra una vez el estado de un trabajo de creación. |
| `test-account job wait <job-id>` | Espera a un trabajo de creación hasta que deje de ejecutarse o se agote el tiempo de espera. |

`batch create`, `batch update` y `batch delete` preguntan antes de cambiar nada, y se
envían una sola vez sin reintentos. Consulta [Seguridad y operaciones destructivas](https://docs.xbox.com/es/tools/xbox-cli/safety.md).

## Opciones para leer lotes

| Opción | Comandos | Descripción |
| - | - | - |
| `--seller-id <id>` | `batch list`, `batch get`, `test-account get` | Identificador de vendedor de Partner Center. |
| `--mine` | `list` | Solo los lotes que creaste. No se puede combinar con `--created-by-id`. |
| `--created-by-id <id>` | `list` | Solo los lotes creados por este identificador numérico de usuario de Partner Center. No se puede combinar con `--mine`. |
| `--email-prefix <text>` | `list` | Solo los lotes cuya plantilla de correo electrónico empieza por este texto, sin distinguir mayúsculas de minúsculas. |
| `--tag <tag>` | `list` | Solo los lotes con esta etiqueta exacta. Acepta un valor. |
| `--state <state>` | `list` | `complete` o `pending`, en minúsculas. |
| `--limit <count>` | `list` | Devuelve como máximo este número de los lotes coincidentes más recientes. |
| `--include-sandboxes` | `list` | También devuelve las etiquetas (`keywords`) y el `sandboxAccess` de cada lote. Sin `--limit`, enumera como máximo los 10 lotes coincidentes más recientes; establece `--limit` para enumerar más. |
| `--expired` | `list` | Solo los lotes cuyo acceso a los sandboxes ha expirado. En ese caso, `--limit` se aplica a los lotes expirados. Consulta [Lotes expirados](#expired-batches). |
| `--output <format>` | `batch list`, `batch get`, `test-account get` | `json` (predeterminado), `json-compact` o `table`. |

Las etiquetas aparecen como `keywords` en la salida JSON y en códigos de error como
`test_account_keyword_invalid`. `--tag` coincide con una etiqueta completa, no con parte de una.

Si no puedes leer todos los lotes del vendedor, no recibes ningún error: `batch list` devuelve solo los
lotes que creaste.

### Lotes expirados

Un lote ha expirado una vez que ha pasado su `accessExpirationDate`, la fecha en que termina su acceso a los sandboxes.
Un lote sin fecha nunca expira. La expiración no indica si las cuentas todavía pueden
iniciar sesión.

`batch list --expired` lee la lista completa del vendedor para encontrar los lotes expirados, por lo que es
más lento para un vendedor con muchos lotes. No se puede combinar con `--include-sandboxes`; ejecuta
`batch get` en un lote expirado para ver su acceso a los sandboxes.

## Forma de la respuesta

`list` devuelve:

```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` y `sandboxAccess` son `null` a menos que pases `--include-sandboxes`. `get`
  siempre los devuelve.
* `isComplete` significa que el trabajo de creación se detuvo, no que se crearon todas las cuentas. Compara
  el número de cuentas de `get` con `batchSize`, y lee `progress` para ver el mensaje de
  estado.
* `createdBy` es un identificador numérico de usuario de Partner Center.
* `jobId` es el trabajo en ejecución del lote, y es `null` una vez que el trabajo se ha detenido. Los trabajos de actualización y
  eliminación también aparecen aquí, pero solo se puede hacer el seguimiento de un trabajo de creación con
  [`job wait`](#following-a-creation-job).

`get` devuelve el mismo objeto de lote más sus cuentas:

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

Cada cuenta tiene solo `xuid`, `email`, `gamertag` e `isDeleted`. `xuid` es una cadena.

## Errores al leer lotes

`batch list`, `batch get` y `test-account get` salen con 1 cuando se produce un error. Cuando el servicio devuelve
un error JSON, stderr recibe un error JSON con `status`, `title`, `detail`, `code` cuando la
respuesta incluye uno, y su `correlationId`; la mayoría agregan una sugerencia a `detail`. Otros errores
imprimen una línea de texto. Comprueba el código de salida antes de analizar stderr.

| Estado | Significado |
| - | - |
| 400 | Se rechazó un filtro, o tienes varios vendedores y no elegiste uno; pasa `--seller-id`. |
| 403 | No eres miembro de este vendedor o no tienes el rol de cuentas de prueba de Partner Center para él. Para `batch get`, es posible que el lote pertenezca a otro vendedor (pasa `--seller-id`), o que otro desarrollador lo haya creado y no puedas leer todos los lotes del vendedor. Si el error te pide que vuelvas a iniciar sesión, hazlo. |
| 404 | No existe ningún lote con ese identificador, o las cuentas de prueba todavía no están disponibles. |
| 429 | Con el código `rate_limited`, enviaste demasiadas solicitudes en poco tiempo. El error incluye `retryAfterSeconds`; consulta [Límites de frecuencia](https://docs.xbox.com/es/tools/xbox-cli/cli-for-agents.md#rate-limits). |
| 502 | El servicio no pudo completar la solicitud; reintenta. El servicio puede devolver 502 en lugar de 403 cuando no tienes el rol de cuentas de prueba o, para `batch get`, cuando otro desarrollador creó el lote. Con una cuenta Microsoft personal, reintentar no sirve; consulta [Problemas conocidos](https://docs.xbox.com/es/tools/xbox-cli/known-issues.md#some-commands-dont-work-yet-with-a-personal-microsoft-account). |
| 503 | Las cuentas de prueba no están disponibles. |
| 504 | El servicio no respondió a tiempo; reintenta. |

## Búsqueda de una cuenta

`test-account get <email>` indica si el lote que contiene una cuenta ha expirado. El correo electrónico
debe terminar en `@xboxtest.com`. El comando busca en los 10 lotes más recientes cuya plantilla de correo
electrónico coincide con el nombre de la cuenta. Cuando no encuentra la cuenta allí, indica que no se buscó en los lotes
más antiguos e imprime comandos `batch list` y `batch get` para que los compruebes
tú mismo.

Devuelve lo siguiente, abreviado aquí; `batch` contiene todos los campos de lote que devuelve `batch list`:

```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` es `null` cuando el lote no ha expirado. Una cuenta eliminada solo se notifica cuando no
existe ninguna copia activa, con `account.isDeleted` establecido. El comando sale con 0 siempre que encuentra la
cuenta, haya expirado o no, por lo que los scripts deben leer `expired`. Sale con 1 cuando:

* La cuenta no está en los lotes que puedes ver. Es posible que pertenezca a otro vendedor, así que prueba con
  `--seller-id`, o que otro desarrollador haya creado su lote y no puedas leer todos los lotes del
  vendedor.
* El correo electrónico aparece en más de un lote. stderr enumera un comando `batch get` para cada uno.
* Se produce un error en una solicitud, como en [Errores al leer lotes](#errors-when-reading-batches).

## Creación de un lote

`batch create` inicia un trabajo que crea las cuentas y, después, espera a que se detenga. Las cuentas
cuentan para el límite de cuentas de prueba del vendedor hasta que el lote se
[elimina](#deleting-a-batch).

En un terminal, el comando muestra el [selector de pregunta de seguridad](#choosing-a-security-question),
enumera los valores que enviará, incluidos los valores predeterminados de las opciones que omitiste, y te pide
que confirmes. A continuación, te [solicita](#secrets) la contraseña y la respuesta de seguridad, inicia sesión y envía
la solicitud. `--confirm` (`--yes`, `-y`) omite solo la confirmación.

Sin un terminal, pasa `--password-file`, `--security-answer-file` y `--confirm`. Sin
`--confirm`, el comando imprime los valores, se niega y no envía nada.

| Opción | Descripción |
| - | - |
| `--email-prefix <text>` | Obligatoria. El grupo de sandboxes, un guion y una plantilla, por ejemplo `ABCD-tester`. El grupo de sandboxes es la parte de un identificador de sandbox anterior al punto, como `ABCD` en `ABCD.1`. |
| `--count <count>` | Obligatoria. Número de cuentas que se van a crear; al menos 1. El servicio establece el máximo. |
| `--sandbox-id <id>` | Obligatoria. Un sandbox al que pueden acceder las cuentas. Repítela para agregar más sandboxes. |
| `--password-file <path>` | Archivo que contiene la contraseña de la cuenta, o `-` para stdin. Consulta [Secretos](#secrets). |
| `--security-answer-file <path>` | Archivo que contiene la respuesta de seguridad, o `-` para stdin. Consulta [Secretos](#secrets). |
| `--child-count <count>` | Total de cuentas secundarias del lote, todas vinculadas a la primera cuenta; 0 o más. `--count 5 --child-count 2` crea 5 cuentas y 2 secundarias, no 2 por cada una. El servicio establece el máximo. |
| `--first-name <text>` | El valor predeterminado es `Test`. |
| `--last-name <text>` | El valor predeterminado es `Account`. |
| `--security-question <text>` | La pregunta de seguridad que recibe cada cuenta. Consulta [Elección de una pregunta de seguridad](#choosing-a-security-question). |
| `--alternate-email <text>` | El valor predeterminado es tu correo electrónico. |
| `--access-expiration <date>` | Cuándo expira el acceso a los sandboxes, como `2026-12-31`, interpretado en UTC. El valor predeterminado es dentro de tres meses. |
| `--tag <tag>` | Una etiqueta que se almacena en el lote y que `batch list --tag` puede encontrar más adelante. Repítela para agregar más etiquetas. |
| `--locale <locale>` | El valor predeterminado es `en-US`. |
| `--subscription <name>` | El nivel de las cuentas para los servicios XBOX, `Silver` o `Gold`, sin distinguir mayúsculas de minúsculas. El valor predeterminado es `Gold`. |
| `--seller-id <id>` | Vendedor para el que se crean las cuentas. |
| `--confirm`, `--yes`, `-y` | Crea sin la solicitud de confirmación. |
| `--no-wait` | Vuelve en cuanto el servicio acepta el trabajo. No se puede combinar con `--timeout`. |
| `--timeout <duration>` | Cuánto tiempo esperar al trabajo, como `90s`, `10m`, `2h` o `1d`. El valor predeterminado es `5m`; como máximo, `7d`. |
| `--output <format>` | `json` (predeterminado), `json-compact` o `table`. |

### Elección de una pregunta de seguridad

En un terminal, cuando no pasas `--security-question` ni `--security-answer-file`, el
comando muestra un selector numerado con estas preguntas. Al pulsar Entrar se selecciona la primera. Para elegir una
sin el selector, pasa su texto con `--security-question`:

1. What is your favorite hobby? (¿Cuál es tu pasatiempo favorito?)
2. Who is your favorite athlete? (¿Quién es tu deportista favorito?)
3. What is your maternal grandmother's first name? (¿Cuál es el nombre de tu abuela materna?)
4. What was your childhood best friend's first name? (¿Cuál era el nombre de tu mejor amigo de la infancia?)
5. What was the name of your first pet? (¿Cómo se llamaba tu primera mascota?)
6. What is your current best friend's first name? (¿Cuál es el nombre de tu mejor amigo actual?)
7. What was your favorite city to visit as a child? (¿Cuál era tu ciudad favorita para visitar cuando eras niño?)

Pasa el texto en inglés tal como aparece en la lista. Sin un terminal, o con un archivo de respuesta y sin pregunta, la pregunta es
`What is your favorite hobby?`. Ctrl+C en el selector cancela sin crear nada.
Elegir una pregunta no confirma la creación.

### Secretos

La contraseña y la respuesta de seguridad nunca se aceptan como valores de opción ni como variables de
entorno, de modo que no aparecen en el historial del shell, en las listas de procesos ni en los registros. Cada una procede de:

* Su `--password-file` o `--security-answer-file`. Se quita un único salto de línea final.
* `-` en lugar de una ruta de acceso, que la lee desde stdin. Solo una de las dos puede leer stdin.
* Sin opción de archivo, una solicitud en el terminal que no muestra lo que escribes.

La contraseña debe tener entre 8 y 16 caracteres y contener al menos tres de los siguientes elementos: letras minúsculas,
letras mayúsculas, números y símbolos. El guion bajo no cuenta como símbolo. La contraseña
no puede coincidir con la respuesta de seguridad.

### Espera y códigos de salida

Mientras espera, el comando imprime el progreso en stderr. Escribe el trabajo final en stdout, con
la misma forma que [`job get`](#following-a-creation-job).

| Código de salida | Significado |
| - | - |
| 0 | El trabajo se completó correctamente o se aceptó con `--no-wait`. stderr proporciona el comando para hacer su seguimiento. |
| 1 | No se creó nada: la solicitud se denegó o se rechazó, produjo un error o se canceló antes de enviarse, o recibió un 503 con `feature_disabled` o `service_configuration_invalid`. |
| 2 | El trabajo produjo un error. Es posible que se hayan creado algunas cuentas; stderr proporciona los recuentos y el comando para inspeccionar el lote. |
| 3 | El resultado es desconocido. Consulta [Cuando el resultado es desconocido](#when-the-outcome-is-unknown). |
| 4 | El lote existe, pero la espera terminó antes de que el trabajo se detuviera: pasó el `--timeout`, pulsaste Ctrl+C o se produjo un error al leer el trabajo. El trabajo sigue ejecutándose. stderr proporciona el comando para reanudar la espera. No vuelvas a crear el lote. |

### Cuando el resultado es desconocido

Cuando la CLI no puede saber si el servicio creó un lote, por ejemplo cuando la conexión se interrumpe
después de enviar la solicitud o el servicio devuelve un error `5xx`, sale con 3. Nunca vuelve a enviar la
creación. stderr imprime la hora a la que se inició la solicitud, en UTC, y estos pasos:

1. Espera unos minutos; es posible que un lote que todavía se está creando aún no aparezca en la lista.
2. Ejecuta `xbox test-account batch list --mine --email-prefix <prefix>` y busca un lote con
   el mismo prefijo de correo electrónico y la misma plantilla, creado a esa hora o después.
3. Si el `jobId` de ese lote está establecido, haz su seguimiento con
   `xbox test-account job wait <job-id> --batch-id <batch-id>`. Si `jobId` es `null`, el trabajo se ha
   detenido; inspecciónalo con `xbox test-account batch get <batch-id>`.
4. Vuelve a crear el lote solo si no existe ningún lote de ese tipo.

Los comandos impresos conservan las opciones de vendedor, perfil e inicio de sesión que usaste, por lo que puedes copiarlos
tal como están.

### Errores al crear

Los errores escriben en stderr un error JSON con `status`, `title`, `detail` y `code` cuando la
respuesta incluye uno. Bifurca según `code`, no según `detail`.

| Código | Significado |
| - | - |
| `test_account_sandbox_access_denied` | No puedes conceder acceso a uno de los valores de `--sandbox-id`. Si se deniegan todos los sandboxes, es posible que tu cuenta no esté vinculada al vendedor, que el vendedor no tenga sandboxes o que Partner Center no te permita administrar cuentas de prueba. |
| `test_account_count_invalid` | `--count` está fuera de lo que permite el servicio. |
| `test_account_child_count_invalid` | `--child-count` está fuera de lo que permite el servicio. |
| `test_account_email_prefix_invalid` | `--email-prefix` no es un grupo de sandboxes, un guion y una plantilla, como `ABCD-tester`. |
| `test_account_name_invalid` | Se rechazó `--first-name` o `--last-name`. |
| `test_account_password_invalid` | La contraseña no cumple las reglas de contraseña. |
| `test_account_security_question_invalid` | Se rechazó `--security-question`. |
| `test_account_security_answer_invalid` | Se rechazó la respuesta de seguridad, por ejemplo porque es igual a la contraseña o aparece en la pregunta de seguridad. |
| `test_account_alternate_email_invalid` | Se rechazó `--alternate-email`. |
| `test_account_keyword_invalid` | Se rechazó un valor de `--tag`, o hay demasiados. |
| `test_account_locale_invalid` | `--locale` no se admite; prueba con `en-US`. |
| `test_account_subscription_unavailable` | Esa `--subscription` no está disponible; prueba con `--subscription Silver`. |
| `test_account_limit_exceeded` | El vendedor ha alcanzado su límite de cuentas de prueba. |
| `test_account_access_denied` | No tienes el rol de Partner Center para crear cuentas de prueba para este vendedor. |
| `test_account_create_outcome_unknown` | Código de salida 3; consulta [Cuando el resultado es desconocido](#when-the-outcome-is-unknown). |
| `downstream_request_rejected` | La solicitud se rechazó sin indicar un campo, por ejemplo porque el grupo de `--email-prefix` no es uno de tus grupos de sandboxes, o porque la pregunta o la respuesta de seguridad es demasiado larga. |
| `downstream_throttled` | Las solicitudes se están limitando y no se creó nada. Espera y vuelve a intentarlo. |
| `rate_limited` | 429: enviaste demasiadas solicitudes en poco tiempo y no se creó nada. Consulta [Límites de frecuencia](https://docs.xbox.com/es/tools/xbox-cli/cli-for-agents.md#rate-limits). |
| Cualquier otro código, o ninguno, en un 5xx | Código de salida 3, porque es posible que exista un lote; consulta [Cuando el resultado es desconocido](#when-the-outcome-is-unknown). |
| `feature_disabled`, `service_configuration_invalid` | 503: la creación de cuentas de prueba no está disponible. Código de salida 1. |
| `invalid_request`, o un `400` sin código | La solicitud tenía un formato incorrecto o un valor no está permitido; `detail` o `errors` indica el campo. Una CLI más reciente que el servicio puede recibir esto para una opción que el servicio todavía no admite. |

## Seguimiento de un trabajo de creación

`batch create` imprime los identificadores del lote y del trabajo en cuanto se acepta el trabajo. Un trabajo puede ejecutarse durante
días, por lo que puedes dejar de esperar en cualquier momento y hacer su seguimiento más adelante:

| Opción | Comandos | Descripción |
| - | - | - |
| `<job-id>` | `get`, `wait` | Obligatorio. El identificador del trabajo de `batch create`, o el `jobId` de un lote de `batch list`. |
| `--batch-id <id>` | `get`, `wait` | Obligatoria. El lote al que pertenece el trabajo. |
| `--seller-id <id>` | `get`, `wait` | Vendedor propietario del lote. |
| `--timeout <duration>` | `wait` | Cuánto tiempo esperar, como `90s`, `10m`, `2h` o `1d`. El valor predeterminado es `5m`; como máximo, `7d`. |
| `--output <format>` | `get`, `wait` | `json` (predeterminado), `json-compact` o `table`. |

Ambos devuelven el trabajo:

```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` es `running`, `succeeded` o `failed`. `errorCode` es `test_account_job_failed` cuando el
trabajo produjo un error. `job wait` reintenta los errores de lectura temporales, como la limitación o una conexión
interrumpida.

| Código de salida | `job get` | `job wait` |
| - | - | - |
| 0 | En ejecución o completado correctamente | Completado correctamente |
| 1 | La solicitud produjo un error | La primera lectura produjo un error, por ejemplo por un identificador de trabajo o de lote incorrecto; no se escribe nada en stdout |
| 2 | Error | Error |
| 4 | No se usa | La espera terminó antes de que el trabajo se detuviera: pasó el `--timeout`, pulsaste Ctrl+C o se produjo un error al leer el trabajo. El trabajo sigue ejecutándose. stderr proporciona el comando para reanudar la espera; ejecútalo una vez que el error de stderr se haya corregido o haya desaparecido. |

### Errores al hacer el seguimiento de un trabajo

Estos códigos de error apuntan al identificador del trabajo, a `--batch-id` o a `--seller-id`:

| `code` | Significado |
| - | - |
| `test_account_job_not_in_batch` | 404: el trabajo no está en el lote que indica `--batch-id`. |
| `test_account_batch_not_found` | 404: no existe ese lote para este vendedor. |
| `downstream_request_rejected` | 404: no existe ningún trabajo con ese identificador. |
| `test_account_access_denied` | 403: el lote o el trabajo pertenece a otro vendedor, por lo que es posible que `--batch-id` o `--seller-id` sean incorrectos. De lo contrario, otro desarrollador inició el trabajo y no puedes leer todos los lotes del vendedor. |

## Actualización de un lote

`batch update` cambia todas las cuentas de un lote: puede darles acceso a más sandboxes,
quitarles acceso, mover la fecha en que expira ese acceso, y agregar etiquetas al lote o reemplazarlas.
Después, espera hasta que el lote muestre el cambio.

En un terminal, el comando muestra primero cada cambio solicitado junto al valor actual del lote,
advierte cuando todavía se está ejecutando un trabajo en el lote, y pregunta. Pasa `--confirm` (`--yes`,
`-y`) para omitir la solicitud. Sin un terminal y sin `--confirm`, imprime los cambios,
se niega y no envía nada.

| Opción | Descripción |
| - | - |
| `<batch-id>` | Obligatorio. El identificador del lote, de `batch list` o `batch create`. |
| `--add-sandbox-id <id>` | Sandbox al que se da acceso a las cuentas. Repítela para agregar más sandboxes. |
| `--remove-sandbox-id <id>` | Sandbox al que se quita el acceso de las cuentas. Repítela para agregar más sandboxes. Un sandbox no se puede agregar y quitar a la vez. |
| `--access-expiration <date>` | Nueva fecha en que expira el acceso de las cuentas a los sandboxes, como `2026-12-31`. Debe estar en el futuro, y el servicio conserva solo el día. El servicio rechaza esta opción para un lote sin sandboxes. |
| `--tag <tag>` | Etiqueta que se agrega al lote, de 100 caracteres como máximo. Se omite una etiqueta que el lote ya tiene, sin distinguir mayúsculas de minúsculas. Repítela para agregar más etiquetas. No se puede combinar con `--clear-tags`. |
| `--replace-tags` | Reemplaza todas las etiquetas del lote por los valores de `--tag`. Necesita `--tag`. Aquí sí se distinguen mayúsculas de minúsculas, por lo que reemplazar `smoke` por `Smoke` es un cambio. |
| `--clear-tags` | Quita todas las etiquetas del lote. |
| `--allow-not-mine` | Permite cambiar un lote que creó otro desarrollador. Sin esta opción, la actualización se rechaza con `test_account_batch_not_owned`. Es posible que tus permisos sigan impidiéndola. |
| `--seller-id <id>` | Vendedor propietario del lote. |
| `--confirm`, `--yes`, `-y` | Actualiza sin la solicitud de confirmación. |
| `--no-wait` | Vuelve en cuanto el servicio acepta la actualización. No se puede combinar con `--timeout`. |
| `--timeout <duration>` | Cuánto tiempo esperar a la actualización, como `90s`, `10m` o `2h`. El valor predeterminado es `5m`; como máximo, `7d`. |
| `--output <format>` | `json` (predeterminado), `json-compact` o `table`. |

Pasa al menos un cambio. Un lote puede tener como máximo 20 etiquetas. `--replace-tags` y
`--clear-tags` conservan la etiqueta que registra qué herramienta creó el lote, que no cuenta
para el límite. Cambiar los sandboxes o la expiración requiere acceso a esos sandboxes;
ampliar la expiración requiere acceso a todos los sandboxes del lote.

El comando devuelve los valores del lote una vez completada la actualización:

```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` es `updated` una vez que el lote muestra el cambio, o `updating` con `--no-wait` o cuando
la espera termina antes. Cuando el lote ya tiene todos los valores solicitados, no cambia nada:
`state` es `unchanged`, `jobId` es `null` y el comando sale con 0. No se puede hacer el seguimiento de los trabajos de actualización
con `job get` ni `job wait`.

### Espera y códigos de salida al actualizar

| Código de salida | Significado |
| - | - |
| 0 | El lote muestra el cambio, ya tenía estos valores o la actualización se aceptó con `--no-wait`. |
| 1 | No se cambió nada: la solicitud se denegó o se rechazó, produjo un error antes de enviarse, no se pudo leer el lote antes de la solicitud de confirmación o la rechazaste. |
| 2 | El trabajo de actualización terminó, pero el lote no muestra el cambio. stderr indica los campos que difieren. Lee el lote con `batch get` y, después, vuelve a actualizarlo. |
| 3 | El resultado es desconocido. Lee el lote con el comando `batch get` impreso antes de volver a actualizarlo. Una vez que no se esté ejecutando ningún trabajo, es seguro volver a enviar el mismo cambio. |
| 4 | La actualización se aceptó, pero la espera terminó mientras todavía se estaba ejecutando: pasó el `--timeout`, pulsaste Ctrl+C o se produjo un error al leer el lote. Un `jobId` que nunca se borra sugiere que el trabajo produjo un error o se bloqueó. |

### Errores al actualizar

| `code` | Significado |
| - | - |
| `test_account_batch_not_owned` | 403: otro desarrollador creó el lote. Pasa `--allow-not-mine` para omitir esta comprobación. |
| `test_account_sandbox_access_denied` | 403: no tienes acceso a un sandbox del cambio. Ampliar la expiración requiere acceso a todos los sandboxes del lote. |
| `test_account_batch_not_found` | 404: no existe ese lote para este vendedor. |
| `test_account_batch_busy` | 409: se está ejecutando un trabajo en el lote. Espera hasta que `batch get` muestre `jobId` como `null`. |
| `test_account_keyword_invalid` | 400: un valor de `--tag` no está permitido. |
| `test_account_access_denied` | No tienes el rol de Partner Center para administrar cuentas de prueba para este vendedor o, con `--allow-not-mine`, para cambiar un lote que no creaste. |
| `downstream_throttled` | Las solicitudes se están limitando. Espera y vuelve a intentarlo. |
| `rate_limited` | 429: enviaste demasiadas solicitudes en poco tiempo. Consulta [Límites de frecuencia](https://docs.xbox.com/es/tools/xbox-cli/cli-for-agents.md#rate-limits). |
| `test_account_update_outcome_unknown` | 502: código de salida 3. |
| `feature_disabled`, `service_configuration_invalid` | 503: las cuentas de prueba no están disponibles. Código de salida 1. |

Un `404` o `405` sin código significa que la actualización de lotes no está disponible.

## Eliminación de un lote

`batch delete` elimina un lote completo y, después, espera hasta que desaparezca. Cada cuenta del lote
pierde su acceso a los sandboxes, y se elimina su registro de cuenta de prueba. Las cuentas Microsoft
y los perfiles de XBOX de las cuentas no se cierran.

En un terminal, el comando muestra primero la plantilla de correo electrónico, el tamaño y el creador del lote, advierte
cuando todavía se está ejecutando un trabajo en él, y pregunta. Pasa `--confirm` (`--yes`, `-y`) para omitir la
solicitud. Sin un terminal y sin `--confirm`, imprime lo que eliminaría, se niega
y no envía nada. No hay eliminación masiva; elimina los lotes de uno en uno.

| Opción | Descripción |
| - | - |
| `<batch-id>` | Obligatorio. El identificador del lote, de `batch list` o `batch create`. |
| `--allow-not-mine` | Permite eliminar un lote que creó otro desarrollador. Sin esta opción, la eliminación se rechaza con `test_account_batch_not_owned`. Es posible que tus permisos sigan impidiéndola, con `test_account_access_denied`. |
| `--seller-id <id>` | Vendedor propietario del lote. |
| `--confirm`, `--yes`, `-y` | Elimina sin la solicitud de confirmación. |
| `--no-wait` | Vuelve en cuanto el servicio acepta la eliminación. No se puede combinar con `--timeout`. |
| `--timeout <duration>` | Cuánto tiempo esperar a que el lote desaparezca, como `90s`, `10m` o `2h`. El valor predeterminado es `5m`; como máximo, `7d`. |
| `--output <format>` | `json` (predeterminado), `json-compact` o `table`. |

El comando devuelve:

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

`state` es `deleted` una vez que el lote ha desaparecido, o `deleting` con `--no-wait` o cuando la espera
termina antes. No se puede hacer el seguimiento de los trabajos de eliminación con `job get` ni `job wait`; mientras se ejecuta la eliminación,
el lote muestra su `jobId`.

### Espera y códigos de salida al eliminar

| Código de salida | Significado |
| - | - |
| 0 | El lote ha desaparecido o la eliminación se aceptó con `--no-wait`. |
| 1 | No se eliminó nada: la solicitud se denegó o se rechazó, produjo un error antes de enviarse, no se pudo leer el lote antes de la solicitud de confirmación o la rechazaste. |
| 2 | El trabajo de eliminación se detuvo, pero el lote sigue existiendo. Inspecciónalo con `batch get`. |
| 3 | El resultado es desconocido. Lee el lote con el comando `batch get` impreso: un `404` con `test_account_batch_not_found` significa que se eliminó, y un `jobId` establecido significa que probablemente la eliminación se está ejecutando. Si `jobId` es `null`, espera un minuto y vuelve a leerlo; vuelve a eliminarlo solo si sigue siendo `null`. |
| 4 | La eliminación se aceptó, pero la espera terminó mientras el lote todavía existía: pasó el `--timeout`, pulsaste Ctrl+C o se produjo un error al leer el lote. Un `jobId` que sigue establecido con `progress` sin cambios sugiere que la eliminación se bloqueó. |

### Errores al eliminar

| `code` | Significado |
| - | - |
| `test_account_batch_not_owned` | 403: otro desarrollador creó el lote; el mensaje indica su identificador de usuario de Partner Center. Pasa `--allow-not-mine` para omitir esta comprobación. |
| `test_account_batch_not_found` | 404: no existe ese lote para este vendedor, o ya se eliminó. Solo este código significa que el lote ha desaparecido. |
| `test_account_batch_busy` | 409: se está ejecutando un trabajo en el lote, que podría ser una eliminación ya en curso. Espera hasta que `batch get` muestre `jobId` como `null`, o devuelva `404` con `test_account_batch_not_found`. |
| `test_account_access_denied` | No tienes el rol de Partner Center para administrar cuentas de prueba para este vendedor o, con `--allow-not-mine`, para eliminar un lote que no creaste. |
| `downstream_throttled` | Las solicitudes se están limitando. Espera y vuelve a intentarlo. |
| `rate_limited` | 429: enviaste demasiadas solicitudes en poco tiempo. Consulta [Límites de frecuencia](https://docs.xbox.com/es/tools/xbox-cli/cli-for-agents.md#rate-limits). |
| `test_account_delete_outcome_unknown` | 502 o 504: código de salida 3. Un 504 sin código se trata igual. |
| `feature_disabled`, `service_configuration_invalid` | 503: las cuentas de prueba no están disponibles. Código de salida 1. |

Un `404` o `405` sin código significa que la eliminación de lotes no está disponible.

## Salida de tabla

Todos los comandos aceptan `--output table`. Las horas se muestran en UTC, y las líneas de resumen van a
stderr, de modo que stdout contiene solo la tabla.

| Comando | Columnas |
| - | - |
| `test-account batch list` | `BATCH ID`, `EMAIL TEMPLATE`, `SIZE`, `STATE` (`complete` o `pending`), `CREATED BY`, `CREATED (UTC)`, `EXPIRES (UTC)` y, después, `SANDBOXES` con `--include-sandboxes`. |
| `test-account batch get` | Una fila por cuenta: `EMAIL`, `GAMERTAG`, `XUID` y `DELETED`. stderr resume el lote y su acceso a los sandboxes. |
| `test-account get` | Una fila: `EMAIL`, `GAMERTAG`, `BATCH ID`, `EMAIL TEMPLATE`, `EXPIRES (UTC)` y `EXPIRED` (`yes` o `no`). |
| `test-account batch create`, `job get`, `job wait` | Una fila: `BATCH ID`, `JOB ID`, `STATE` (`running`, `succeeded` o `failed`), `TOTAL`, `SUCCEEDED`, `FAILED`. |
| `test-account batch update` | Una fila: `BATCH ID`, `JOB ID`, `STATE` (`updated`, `updating` o `unchanged`), `EXPIRES (UTC)`. stderr enumera los sandboxes y las palabras clave. |
| `test-account batch delete` | Una fila: `BATCH ID`, `JOB ID`, `STATE` (`deleted` o `deleting`), `EMAIL TEMPLATE`, `SIZE`. |

## Ejemplos

Estos comandos enumeran y leen lotes, cuentas y trabajos:

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

Crea un lote de cinco cuentas. El comando solicita la contraseña y la respuesta de seguridad y,
después, te pide que confirmes:

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

Crea un lote de forma desatendida, con los secretos leídos desde archivos, sin solicitud de confirmación y con una espera de hasta
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
```

Espera hasta dos horas a que termine un trabajo de creación:

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

Agrega un sandbox y establece cuándo expira el acceso a los sandboxes. El comando muestra los cambios, te pide
que confirmes y, después, espera hasta que el lote los muestre:

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

Agrega dos etiquetas de forma desatendida, sin esperar:

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

Reemplaza todas las etiquetas por una:

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

Elimina un lote. El comando muestra el lote, te pide que confirmes y, después, espera hasta que desaparezca:

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

Elimina un lote que creó otro desarrollador, de forma desatendida y sin esperar:

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


## Related topics

- [Cuentas de prueba](https://docs.xbox.com/es/services/xbox-services/develop/test-accounts/index.md)
- [Información general sobre los sandboxes de los servicios de XBOX](https://docs.xbox.com/es/services/xbox-services/fundamentals/sandboxes/live-setup-sandbox.md)
- [Procedimientos recomendados y pruebas para gamertags modernos](https://docs.xbox.com/es/services/xbox-services/fundamentals/identity/user-profile/gamertags/live-modern-gamertags-best-practices-and-testing.md)
- [Crear y administrar cuentas de prueba de XBOX](https://docs.xbox.com/es/publishing/game-publishing/how-to/how-to-create-and-manage-test-accounts.md)
- [Solución de problemas de errores de inicio de sesión y sandbox](https://docs.xbox.com/es/services/xbox-services/develop/troubleshooting/live-troubleshoot-sandboxes.md)
