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

# POST /users/xuid(xuid)/lists/PINS/{listname}/index({index})?insertIndex={insertIndex}

> POST /users/xuid(xuid)/lists/PINS/{listname}/index({index})?insertIndex={insertIndex}

# POST /users/xuid(xuid)/lists/PINS/{listname}/index({index})?insertIndex={insertIndex}

Mueve un elemento de una lista a una posición diferente dentro de la lista.
El dominio de estos URI es `eplists.xboxlive.com`.

* [Comentarios](#ID4EV)
* [Parámetros de URI](#ID4EEB)
* [Parámetros de cadena de consulta](#ID4EWC)
* [Cuerpo de la solicitud](#ID4EVD)
* [Códigos de estado HTTP](#ID4EEE)
* [Encabezados de solicitud obligatorios](#ID4E1BAC)
* [Cuerpo de la respuesta](#ID4EQDAC)

## Comentarios

Esta llamada se proporciona para permitir que el cliente mueva fácilmente un elemento a un índice diferente dentro de la lista en una sola operación. Solo se puede mover un elemento a la vez. Si el índice del elemento que se va a mover no existe, se devolverá un HTTP 400. El índice del punto de inserción sigue las mismas reglas que una inserción estándar. De forma predeterminada será 0 (el principio de la lista) y cualquier número mayor que el número de elementos de la lista volverá a insertar el elemento al final de la lista. Del mismo modo, el final de la lista se puede indicar pasando "end" para insertIndex.

Esta llamada también permite identificar el elemento que se va a mover mediante el itemId (o la combinación provider/providerId). En este caso, el itemId debe pasarse en el cuerpo de la solicitud y debe coincidir con un elemento existente en la lista. Si no lo hace, se devolverá un error HTTP 400 con IndexOutOfRange en la descripción; para esta versión especial de la llamada, use "-1" como índice del elemento que se va a mover.

Esta llamada requiere que se incluya un encabezado "If-Match:versionNumber" en la solicitud si se especifica el elemento por índice. Si se usa itemId para indicar qué elemento se va a mover, el encabezado "If-Match" es opcional. Si está presente, el encabezado "If-Match" siempre se validará. En el encabezado "If-Match", versionNumber es el número de versión actual de la lista. Si no se incluye (y es obligatorio), o no coincide con el número de versión actual de la lista, se devolverá un código de estado HTTP 412 (error de condición previa) y el cuerpo de la respuesta contendrá los metadatos más recientes de la lista, que incluyen el número de versión actual. Esto se hace para evitar que las actualizaciones de distintos clientes se sobrescriban entre sí.

## Parámetros de URI

| Parámetro | Tipo | Descripción |
| - | - | - |
| XUID | string | XUID del usuario. |
| listname | string | Nombre de la lista que se va a manipular. |
| index | string | Especifica el índice actual del elemento que se va a mover. Si el valor del índice es cero o un entero positivo, hace referencia al índice actual del elemento y el cuerpo de la solicitud de la llamada debe estar vacío. Sin embargo, si el valor del índice es "-1", el elemento que se va a mover debe especificarse mediante ItemId o Provider/ProviderID en el cuerpo de la solicitud de la llamada. |

## Parámetros de cadena de consulta

\| Parámetro| Tipo| Descripción|
\| --- | --- | --- | --- | --- | --- |
\| insertIndex| string| Especifica la ubicación de la lista donde se va a insertar el elemento. Los valores permitidos son cero, enteros positivos y "end". "end" coloca el elemento al final de la lista actual. Si el valor especificado está más allá del final de la lista, el elemento se inserta al final de la lista. |

## Cuerpo de la solicitud

Solo se envía un cuerpo de solicitud cuando se especifica el elemento que se va a mover mediante itemId o mediante Provider/ProviderId.

Ejemplo de solicitud

```cpp theme={null}
{
  "Item":
  {
    "ItemId":  "ed591a0c-dde3-563f-99af-530278a3c402",
    "ProviderId":  null,
    "Provider": null
  }
}
    
```

## Códigos de estado HTTP

El servicio devuelve uno de los códigos de estado de esta sección en respuesta a una solicitud realizada con este método en este recurso. Para obtener una lista completa de los códigos de estado HTTP estándar que se usan con los servicios de XBOX Live, consulte [Códigos de estado HTTP estándar](https://docs.xbox.com/es/reference/live/rest/additional/httpstatuscodes.md).

\| Código| Frase de motivo| Descripción|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| 200| OK | La solicitud se completó correctamente. El cuerpo de la respuesta debe contener el recurso solicitado (para un GET). Las solicitudes POST y PUT recibirán metadatos actualizados de la lista (versión de la lista, recuento, etc.).|
\| 201| Created | Se ha creado una lista nueva. Se devuelve en la inserción inicial en una lista. La respuesta incluye metadatos actualizados de la lista y el encabezado de ubicación contiene el URI de la lista.|
\| 304| Not Modified| Se devuelve en solicitudes GET. Indica que el cliente tiene la versión más reciente de la lista. El servicio compara el valor del encabezado **If-Match** con la versión de la lista. Si son iguales, se devuelve un 304 sin datos. |
\| 400| Bad Request | La solicitud tenía un formato incorrecto. Podría ser un valor o tipo no válido para un parámetro de URI o de cadena de consulta. También puede ser el resultado de la falta de un parámetro o valor de datos obligatorio, o de que la solicitud indicara una versión de la API que falta o no es válida. Consulte el encabezado **X-XBL-Contract-Version**. |
\| 401| Unauthorized | La solicitud requiere autenticación del usuario.|
\| 403| Forbidden | La solicitud no está permitida para el usuario o el servicio.|
\| 404| Not Found | El autor de la llamada no tiene acceso al recurso. Esto indica que no se ha creado tal lista.|
\| 412| Precondition Failed | Indica que la versión de la lista ha cambiado y que una solicitud de modificación ha fallado. Una solicitud de modificación es una inserción, actualización o eliminación. El servicio comprueba el encabezado **If-Match** para la versión de la lista. Si no coincide con la versión actual de la lista, la operación falla y se devuelve este código junto con los metadatos actuales de la lista (que incluyen la versión actual). |
\| 500| Internal Server Error | El servicio rechaza la solicitud debido a un error del lado del servidor.|
\| 501| Not Implemented | El autor de la llamada solicitó un URI que no se ha implementado en el servidor. (Actualmente solo se usa cuando se realiza una solicitud para un nombre de lista que no está en la lista de permitidos).|
\| 503| Service Unavailable | El servidor rechaza la solicitud, normalmente debido a una carga excesiva. Después de un retraso (consulte el encabezado **Retry-after**), la solicitud se puede reintentar. |

## Encabezados de solicitud obligatorios

\| Encabezado| Descripción|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| Authorization| Contiene el token STS que se usa para autenticar y autorizar la solicitud. Debe ser un token del servicio XSTS e incluir el XUID como una de las notificaciones. |
\| X-XBL-Contract-Version| Especifica qué versión de la API se solicita (enteros positivos). Pins admite la versión 2. Si falta este encabezado o el valor no se admite, el servicio devolverá un 400 - Bad request con "Unsupported or missing contract version header" en la descripción del estado.|
\| Content-Type| Especifica si el contenido de los cuerpos de solicitud/respuesta estará en json o xml. Los valores admitidos son "application/json" y "application/xml"|
\| If-Match| Este encabezado debe contener el número de versión actual de una lista al realizar solicitudes de modificación. Las solicitudes de modificación usan los verbos PUT, POST o DELETE. Si la versión del encabezado "If-Match" no coincide con la versión actual de la lista, la solicitud se rechazará con un código de retorno HTTP 412 - error de condición previa. (Opcional) También se puede usar para solicitudes GET; si está presente y la versión pasada coincide con la versión actual de la lista, no se devolverán datos de la lista y se devolverá un código HTTP 304 - Not Modified. |

## Cuerpo de la respuesta

Si la llamada se realiza correctamente, el servicio devuelve los metadatos más recientes de la lista.

### Ejemplo de respuesta

```cpp theme={null}
{ 
  "ListVersion":  1,
  "ListCount":  1,
  "MaxListSize": 200,
  "AllowDuplicates": "true",
  "AccessSetting":  "OwnerOnly"
}

      
```


## Related topics

- [/users/xuid(xuid)/lists/PINS/{listname}/index({index})?insertIndex={insertIndex}](https://docs.xbox.com/es/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnamewindows-apg.md)
- [POST (/users/xuid(xuid)/lists/PINS/{listname})](https://docs.xbox.com/es/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnamepost.md)
- [/users/xuid(xuid)/lists/PINS/{listname}](https://docs.xbox.com/es/reference/live/rest/uri/lists/uri-usersxuidlistspinslistname.md)
- [DELETE (/users/xuid(xuid)/lists/PINS/{listname})](https://docs.xbox.com/es/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnamedelete.md)
- [DELETE /users/xuid(xuid)/lists/PINS/{listname}/RemoveItems](https://docs.xbox.com/es/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnameremoveitemsdelete.md)