*MCP › Referencia › Catálogo e inventario › Artículos*

# Actualizar una variante de un artículo

> Cambia el nombre, la tarifa de alquiler, el precio de venta o el código de barras de una variante.

El coste interno y externo de la variante no se aceptan: son lo que cuesta servirla a la empresa, y cruzados con la tarifa dan el margen. Devuelve el artículo completo, con sus `variants`, con la misma proyección que su GET.

HERRAMIENTA `filmo_items_variants_update` · `items:write` · 120/min · Anotación del servidor: Idempotente

## Argumentos

| Nombre | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `itemId` | string | Sí | Identificador del artículo. |
| `variantId` | string | Sí | Identificador de la variante. |
| `variantName` | string | No | Nombre de la variante. |
| `variantPrice` | string | No | Precio base de alquiler, como cadena decimal. |
| `salePrice` | string | No | Precio de venta por unidad, como cadena decimal; null lo borra. |
| `ean` | string | No | Código EAN; null lo borra. |
| `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. |
| `ifMatch` | string | No | Bloqueo optimista: el meta.etag que obtuviste de la lectura de detalle de este recurso (o "*"). Si el recurso ha cambiado desde entonces, la llamada falla con 412 precondition_failed antes de escribir nada; léelo de nuevo y reintenta. Omítelo para escribir sin condiciones. |

## Resultado

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

| Nombre | Tipo | Descripción |
| --- | --- | --- |
| `id` | string | Identificador único del artículo. |
| `name` | string | Nombre del artículo. |
| `sku` | string | Referencia SKU del artículo; null si no consta. |
| `description` | string | Descripción del artículo; null si no consta. |
| `orderInfo` | string | Información adicional del pedido (notas de preparación y entrega); null si no consta. |
| `ean` | string | EAN/código de barras; null si no consta. |
| `itemType` | string | Tipo de artículo: fixed (artículo simple) o variant (artículo con variantes). `fixed`, `variant` |
| `stockCalculationMethod` | string | Método de cálculo del stock: bulk (a granel, por cantidad) o serialized (por artículos serializados). `bulk`, `serialized` |
| `collectionId` | string | Identificador de la colección a la que pertenece; null si no está en ninguna. |
| `collectionName` | string | Nombre de la colección a la que pertenece; null si no está en ninguna. |
| `images` | string[] | URLs de las imágenes del artículo. |
| `salePrice` | string | Precio de venta como cadena decimal "1234.50" (ROUND_HALF_UP); null si no tiene. |
| `depositValue` | string | Importe de la fianza como cadena decimal "1234.50" (ROUND_HALF_UP); null si no tiene. |
| `minStock` | number | Stock mínimo configurado para las alertas; null si no está configurado. |
| `serializedItemsCount` | number | Número de unidades serializadas registradas del artículo. |
| `pricingSettings` | object | Configuración de precios de alquiler; null si no está configurada. |
| `pricingSettings.type` | string | Modo de precio: periodPrice (precio por periodo), fixedPrice (precio fijo) o pricingStructure (estructura de precios); null si el artículo no tiene ninguno configurado. `periodPrice`, `fixedPrice`, `pricingStructure` |
| `pricingSettings.price` | string | Precio base de alquiler como cadena decimal "1234.50" (ROUND_HALF_UP); null si no aplica. |
| `pricingSettings.period` | string | Unidad de periodo del precio: hour, day, week o month; null si el artículo no tiene ninguna configurada. `hour`, `day`, `week`, `month` |
| `insuranceEnabled` | boolean | Si el artículo admite seguro. |
| `discountEnabled` | boolean | Si el artículo admite descuentos. |
| `bufferBefore` | number | Tiempo de margen reservado antes del alquiler; null si no aplica. |
| `bufferBeforeUnit` | string | Unidad del margen previo: hora o día; null si no aplica. `hour`, `day` |
| `bufferAfter` | number | Tiempo de margen reservado después del alquiler; null si no aplica. |
| `bufferAfterUnit` | string | Unidad del margen posterior: hour o day; null si no aplica. `hour`, `day` |
| `physicalProperties` | object | Propiedades físicas (peso y dimensiones); null si no se han registrado. |
| `physicalProperties.weight` | number | Peso del artículo en kilogramos; null si no está registrado. |
| `physicalProperties.width` | number | Ancho del artículo en centímetros; null si no está registrado. |
| `physicalProperties.height` | number | Altura del artículo en centímetros; null si no consta. |
| `physicalProperties.length` | number | Longitud del artículo en centímetros; null si no consta. |
| `physicalProperties.volume` | number | Volumen del artículo en metros cúbicos (m³); null si no está registrado. |
| `physicalProperties.current` | number | Consumo de corriente en amperios; null si no consta. |
| `physicalProperties.power` | number | Potencia en vatios; null si no se ha registrado. |
| `variants` | object[] | Variantes del artículo (vacío si el artículo es de tipo fixed). |
| `variants.variantId` | string | Identificador único de la variante. |
| `variants.variantName` | string | Nombre de la variante. |
| `variants.variantPrice` | string | Precio de alquiler de la variante como cadena decimal "1234.50" (ROUND_HALF_UP). |
| `variants.salePrice` | string | Precio de venta de la variante como cadena decimal "1234.50" (ROUND_HALF_UP); null si no tiene. |
| `variants.ean` | string | EAN/código de barras de la variante; null si no consta. |
| `tags` | object[] | Etiquetas asociadas al artículo. |
| `tags.id` | string | Identificador único de la etiqueta. |
| `tags.name` | string | Nombre de la etiqueta. |
| `customFields` | object<string, any> | Valores de los campos personalizados por identificador de campo personalizado; las definiciones están en `/api/v1/custom-fields`. |
| `createdAt` | string<date-time> | Fecha de creación en ISO 8601 con desplazamiento. |
| `updatedAt` | string<date-time> | Fecha de la última actualización en ISO 8601 con desplazamiento. |
| `replacementValue` | string | Valor de reposición del artículo como cadena decimal "1234.50" (ROUND_HALF_UP); null si no consta. |
| `accessoryIds` | string[] | Identificadores de los artículos configurados como accesorios de este. |
| `alternativeIds` | string[] | Identificadores de los artículos configurados como alternativas de este. |

*Llamada · filmo_items_variants_update*

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "filmo_items_variants_update",
    "arguments": {
      "itemId": "item_8f2a1c",
      "variantId": "vari_8f2a1c"
    }
  }
}
```

*Resultado (generado desde el esquema)*

```json
{
  "structuredContent": {
    "data": {
      "id": "id_8f2a1c",
      "name": "Example",
      "sku": "<sku>",
      "description": "<description>",
      "orderInfo": "<orderInfo>",
      "ean": "<ean>",
      "itemType": "fixed",
      "stockCalculationMethod": "bulk",
      "collectionId": "coll_8f2a1c",
      "collectionName": "Example",
      "images": [
        "<images>"
      ],
      "salePrice": "1234.50",
      "depositValue": "1234.50",
      "minStock": 1,
      "serializedItemsCount": 1,
      "pricingSettings": {
        "type": "periodPrice",
        "price": "1234.50",
        "period": "hour"
      },
      "insuranceEnabled": true,
      "discountEnabled": true,
      "bufferBefore": 1,
      "bufferBeforeUnit": "hour",
      "bufferAfter": 1,
      "bufferAfterUnit": "hour",
      "physicalProperties": {
        "weight": 1,
        "width": 1,
        "height": 1,
        "length": 1,
        "volume": 1,
        "current": 1,
        "power": 1
      },
      "variants": [
        {
          "variantId": "vari_8f2a1c",
          "variantName": "Example",
          "variantPrice": "1234.50",
          "salePrice": "1234.50",
          "ean": "<ean>"
        }
      ],
      "tags": [
        {
          "id": "id_8f2a1c",
          "name": "Example"
        }
      ],
      "customFields": {
        "key": "<key>"
      },
      "createdAt": "2026-09-01T08:00:00Z",
      "updatedAt": "2026-09-01T08:00:00Z",
      "replacementValue": "1234.50",
      "accessoryIds": [
        "acce_8f2a1c"
      ],
      "alternativeIds": [
        "alte_8f2a1c"
      ]
    },
    "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 [`PATCH /api/v1/items/{itemId}/variants/{variantId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/items/update-a-variant-of-an-item).

---

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