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

# Crear un artículo

> Registra un artículo en el catálogo de inventario.

El SKU es opcional: si se omite, el servidor asigna el siguiente disponible de la cuenta. Con inventoryMethod=serialized cada unidad física se controla por su número de serie; con bulk, por cantidad, y no se puede cambiar una vez que hay stock. Devuelve el artículo creado con detalle.

HERRAMIENTA `filmo_items_create` · `items:write` · 120/min

## Argumentos

| Nombre | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | string | Sí | Nombre del artículo. Obligatorio. |
| `sku` | string | No | Referencia SKU. Si se omite, el servidor genera la siguiente disponible para la cuenta. Única dentro de la cuenta. |
| `inventoryMethod` | string | No | Cómo se controla el stock. bulk: cantidad total por almacén. serialized: cada unidad física con su número de serie. No se puede cambiar una vez que hay stock. `bulk`, `serialized` = `"bulk"` |
| `collectionId` | string | No | Identificador de la colección en la que se organiza; omítelo para dejarlo sin clasificar. |
| `tags` | string[] | No | Etiquetas, por identificador o por nombre. Un nombre que no existe crea la etiqueta. |
| `variationsEnabled` | boolean | No | true crea un artículo con variantes y su variante por defecto. Omítelo o false para un artículo simple. |
| `showInOrderSearch` | boolean | No | Si el artículo aparece en la búsqueda de artículos dentro de un pedido. Por defecto es true. |
| `useSkuAsOrganizationMasterId` | boolean | No | Solo para cuentas de organización: copia el SKU final en organizationMasterId para poder emparejar el artículo entre cuentas. Por defecto es false. |
| `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_create*

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "filmo_items_create",
    "arguments": {
      "name": "Example"
    }
  }
}
```

*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 [`POST /api/v1/items`](https://docs.filmo.io/es/rest-api/endpoint-reference/items/create-an-item).

---

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