*MCP › Referencia › Alquileres › Pedidos*

# Devolver líneas de pedido

> Marca el material que vuelve como devuelto: qué línea, cuántas unidades y en qué estado.

> **Envía tu propia idempotencyKey:** Un reintento sin la misma clave duplica el efecto. Envía tu propia `idempotencyKey` (un UUID) y reenvía la misma si reintentas.

> **Requiere confirmación humana:** Pon esta herramienta en la lista de «preguntar antes de ejecutar» de tu cliente. Las anotaciones son pistas que declara el servidor, no garantías: no decidas la aprobación solo por `destructiveHint`. El servidor marca esta herramienta con `_meta["anthropic/requiresUserInteraction"]`, que los clientes que lo respetan usan para preguntar a una persona antes de cada llamada.

Cuelga del recurso y no de un pedido porque una descarga cruza pedidos, que es lo que esta llamada resuelve de una vez. Envía `Idempotency-Key`: devolver dos veces la misma línea metería el material en el stock dos veces, y cada línea va como máximo una vez por petición (suma sus cantidades). Es un lote: `atomic` es true por defecto, así que una línea que no se puede devolver rechaza todo el lote con 409 y una incidencia por línea fallida, sin tocar nada; con `atomic: false` cada pedido se procesa por separado y la respuesta es 207 con un resultado por elemento, donde los fallidos no se devolvieron y el resto SÍ. Si todo va bien, la respuesta es 200 con un resultado por elemento, en el orden de la petición.

HERRAMIENTA `filmo_orders_line_items_return` · `orders:write` · 120/min · Anotación del servidor: Destructiva · Requiere confirmación humana · Envía tu propia idempotencyKey

## Argumentos

| Nombre | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `items` | object[] | Sí | Líneas que se devuelven. Al menos una, como máximo 500, cada línea como máximo una vez. |
| `items.lineItemId` | string | Sí | Línea de pedido que se devuelve. |
| `items.checkInQuantity` | number | Sí | Unidades que se devuelven, al menos una. Puede ser una devolución parcial. |
| `items.returnCondition` | string | Sí | Estado físico en el que vuelve el material: `good`, `damaged`, `lost`, `needs_repair` o `incident`. `good`, `damaged`, `lost`, `needs_repair`, `incident` |
| `checkedInAt` | string<date-time> | No | Fecha efectiva de la devolución, en ISO 8601 con desplazamiento. Por defecto, ahora. |
| `atomic` | boolean | No | Todo o nada (por defecto true): si alguna línea no se puede devolver, no se devuelve ninguna y la respuesta es 409 con una incidencia por línea. Con false, cada pedido se procesa por separado, la respuesta es 207 y cada elemento lleva su propio estado. = `true` |
| `idempotencyKey` | string | No | Clave de idempotencia elegida por el cliente (se recomienda un UUID). Repetir la misma clave con los mismos argumentos en 24 h devuelve la respuesta almacenada sin volver a ejecutar; con argumentos distintos responde 422. Es la forma segura de reintentar tras un fallo de red. |

## Resultado

En un éxito el resultado lleva `structuredContent` con `data` y `meta`. Estos son los atributos de `data`.

| Nombre | Tipo | Descripción |
| --- | --- | --- |
| `index` | integer | Posición del elemento en el array de la petición. |
| `id` | string | Identificador del elemento tal como se envió. |
| `status` | string | `returned` o `failed`. `returned`, `failed` |
| `error` | object | Por qué falló; null cuando es `returned`. |
| `error.code` | string | Código de error estable del elemento, del mismo catálogo que `errors[]`. |
| `error.message` | string | Motivo localizado. |

*Llamada · filmo_orders_line_items_return*

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "filmo_orders_line_items_return",
    "arguments": {
      "items": [
        {
          "lineItemId": "line_8f2a1c",
          "checkInQuantity": 1,
          "returnCondition": "good"
        }
      ],
      "idempotencyKey": "<a UUID you generate>"
    }
  }
}
```

*Resultado (generado desde el esquema)*

```json
{
  "structuredContent": {
    "data": [
      {
        "index": 1,
        "id": "id_8f2a1c",
        "status": "returned",
        "error": {
          "code": "<code>",
          "message": "<message>"
        }
      }
    ],
    "meta": {
      "idempotencyKey": "<the key you sent, or the one the server generated>",
      "rateLimit": {
        "limit": 120,
        "remaining": 119,
        "reset": 42
      }
    }
  }
}
```

## La misma operación por REST

Esta herramienta ejecuta [`POST /api/v1/orders/line-items/returns`](https://docs.filmo.io/es/rest-api/endpoint-reference/orders/return-order-lines).

---

URL canónica: https://docs.filmo.io/es/mcp/tools/orders/filmo-orders-line-items-return  
Última actualización: 2026-10-25