> ## Documentation Index
> Fetch the complete documentation index at: https://muveya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Insumos del catálogo
> Busca, crea y mantén los insumos de tu clínica dental, y entiende los estados borrador, activo e inactivo.
El catálogo es la lista cerrada de insumos con los que trabaja tu clínica dental. Cada línea de pedido, caja de existencias y registro de consumo apunta a un insumo de esta lista, así que un insumo debe existir aquí antes de que alguien pueda pedirlo, recibirlo o usarlo. La consola llama *insumo* a cada elemento del catálogo; la API y el código lo llaman `item`.
## Quién puede hacerlo
| Acción | Permiso | Notas |
| - | - | - |
| Ver la lista y abrir un insumo | `catalog.read` | Todos los roles (Propietario, Administrador, Miembro) lo incluyen. |
| Crear un insumo, editarlo, activarlo o desactivarlo | `catalog.manage` | Propietarios y administradores lo tienen por su rol. Un miembro necesita que se le otorgue **Gestionar catálogo**. |
| Ver costos en la lista y en el insumo | `catalog.cost.read` | Ningún rol lo incluye, ni siquiera el de Propietario. Se otorga como **Ver costos de insumos**. Consulta [Costos](/docs/es/catalog/costs). |
Los permisos se asignan a cada persona en la pantalla **Equipo**. Consulta [Roles y permisos](/docs/es/account/roles-and-permissions).
## Dónde
Abre **Catálogo** en la navegación principal. El módulo tiene tres pantallas de insumos:
| Pantalla | Ruta | Para qué sirve |
| - | - | - |
| **Catálogo** | `/catalog` | Buscar, filtrar y abrir insumos. |
| **Nuevo insumo** | `/catalog/items/new` | Crear un insumo. |
| Detalle del insumo | `/catalog/items/:itemId` | Editar un insumo, cambiar su estado y gestionar sus presentaciones y su costo. |
## La lista del catálogo
La pantalla **Catálogo** (**Organiza los insumos que utiliza tu clínica dental.**) muestra:
* **Nuevo insumo**, en el encabezado, si tienes `catalog.manage`.
* Un buscador, **Buscar por SKU o nombre**. Encuentra cualquier parte del SKU o del nombre sin distinguir mayúsculas ni tildes, así que `anestesico` encuentra "Anestésico local".
* Enlaces a **Categorías** y, si tienes `catalog.manage`, a **Importar CSV** y **Exportar CSV**. Consulta [Categorías](/docs/es/catalog/categories) e [Importar y exportar](/docs/es/catalog/import-export).
* Dos filtros: **Categoría** (por defecto **Todas las categorías**) y **Estado** (por defecto **Todos los estados**, luego **Borrador**, **Activo** e **Inactivo**). **Limpiar filtros** reinicia la búsqueda y los dos filtros.
La tabla tiene las columnas **SKU**, **Nombre del insumo**, **Categoría**, **Unidad** y **Estado**, y además **Costo** si tienes `catalog.cost.read`. Haz clic en el nombre para abrir el insumo. Los insumos aparecen en el orden en que se crearon, del más antiguo al más reciente, 50 por página, con **Anterior** y **Siguiente** bajo la tabla y un contador de las filas visibles sobre el total.
| Lo que ves | Significado |
| - | - |
| **Todavía no hay insumos** | El catálogo está vacío. Quien gestiona el catálogo ve **Crea una categoría y agrega el primer insumo a tu catálogo.**; el resto ve **Un administrador puede agregar insumos a este catálogo.** |
| **No hay insumos que coincidan** | Nada coincide con la búsqueda o los filtros. **Prueba con otra búsqueda.** |
| **Categoría no disponible** | El insumo apunta a una categoría que la pantalla no encontró. Abre el insumo y elige una categoría. |
## Crear un insumo
Todo insumo pertenece a una categoría. Si no existe ninguna, el formulario dice **Crea una categoría antes de agregar insumos.** Puedes crearla en [Categorías](/docs/es/catalog/categories) o con **Nueva categoría** dentro del formulario, que además la deja seleccionada.
En **Catálogo**, haz clic en **Nuevo insumo**. Se abre la página **Nuevo insumo** con el texto **Define cómo se identifica y controla este insumo.**
En **Información del insumo**, ingresa **SKU**, **Nombre del insumo**, **Categoría**, **Unidad**, **Presentación**, **Criticidad** y **Descripción**. Las reglas de cada campo están en la tabla de abajo.
En **Requisitos de trazabilidad** (**Estas opciones definen los datos necesarios al registrar existencias.**), marca **Controlar lotes**, **Controlar números de serie**, **Controlar vencimientos** e **Insumo de alto valor** según corresponda. Las cuatro opciones empiezan sin marcar.
Haz clic en **Crear insumo**. La consola abre el detalle del nuevo insumo. El insumo nace como **Borrador**: actívalo cuando esté listo para pedirse.
El formulario de creación no tiene campo de costo. Registra el costo en el detalle del insumo después de crearlo, o inclúyelo en una importación CSV. Consulta [Costos](/docs/es/catalog/costs).
## Campos y validaciones
| Campo (etiqueta en la consola) | Obligatorio | Reglas | Se puede cambiar después |
| - | - | - | - |
| `sku` (**SKU**) | Sí | De 1 a 64 caracteres. Solo letras, dígitos, puntos, guiones bajos, barras y guiones, sin espacios. Único en tu clínica dental y comparado de forma exacta (`GLV-NIT-M` y `glv-nit-m` son códigos distintos). | Nunca. |
| `name` (**Nombre del insumo**) | Sí | Hasta 200 caracteres, no solo espacios. | Sí. |
| `description` (**Descripción**) | No | Hasta 2.000 caracteres. | Sí. |
| `categoryId` (**Categoría**) | Sí | Una categoría de tu propia clínica dental. | Sí. |
| `unitOfMeasure` (**Unidad**) | Sí | Una de las unidades de abajo. | Solo hasta que la unidad quede fija. Consulta [La unidad queda fija](#la-unidad-queda-fija). |
| `packaging` (**Presentación**) | No | Texto libre de hasta 200 caracteres, por ejemplo "Caja de 100". Es solo descriptivo: nunca cambia una cantidad. | Sí. |
| `criticality` (**Criticidad**) | Sí | `low` (**Baja**), `medium` (**Media**) o `high` (**Alta**). | Sí. |
| `tracksLot` (**Controlar lotes**) | No | Desactivado por defecto. | Sí. |
| `tracksSerial` (**Controlar números de serie**) | No | Desactivado por defecto. | Sí. |
| `tracksExpiry` (**Controlar vencimientos**) | No | Desactivado por defecto. | Sí. |
| `highValue` (**Insumo de alto valor**) | No | Desactivado por defecto. | Sí. |
La **Unidad** es la unidad base en la que se cuenta el insumo en todas partes: existencias, pedidos, consumo y presentaciones. Los valores permitidos son:
| Código | Etiqueta | Código | Etiqueta |
| - | - | - | - |
| `unit` | **Unidad** | `liter` | **Litro** |
| `box` | **Caja** | `gram` | **Gramo** |
| `pack` | **Paquete** | `kilogram` | **Kilogramo** |
| `bottle` | **Botella** | `pair` | **Par** |
| `ampoule` | **Ampolla** | `kit` | **Kit** |
| `milliliter` | **Mililitro** | | |
El campo de texto libre **Presentación** del formulario no es lo mismo que la sección **Presentaciones** del detalle del insumo. Para indicar que una caja trae 100 unidades, de modo que recibir 3 cajas sume 300 unidades, agrega una presentación en esa sección. Consulta [Presentaciones y códigos](/docs/es/catalog/presentations-and-codes).
### Qué hacen las opciones de trazabilidad
| Opción | Efecto |
| - | - |
| **Controlar lotes** | Cada recepción de existencias del insumo debe indicar un número de lote. |
| **Controlar números de serie** | Cada recepción debe indicar un número de serie por unidad recibida, sin repetir, y un número de serie ya recibido no se puede recibir otra vez. |
| **Controlar vencimientos** | Cada recepción debe indicar una fecha de vencimiento que no esté en el pasado. |
| **Insumo de alto valor** | Las reglas de aprobación de pedidos pueden apuntar a pedidos con insumos de alto valor (**Solo pedidos con insumos de alto valor**), y cada corrección de existencias del insumo necesita la aprobación de una segunda persona. |
Un cambio en estas opciones se aplica a las recepciones registradas después del cambio; las cajas ya recibidas conservan lo que se registró. Consulta [Recibir existencias](/docs/es/inventory/receive), [Política de aprobación](/docs/es/orders/approval-policy) y [Correcciones de existencias](/docs/es/inventory/corrections).
La **Criticidad** se guarda, se muestra en el insumo y se incluye en las exportaciones. En la versión actual no modifica alertas, reposición ni aprobaciones.
## Estados
| Estado | Etiqueta | Significado |
| - | - | - |
| `draft` | **Borrador** | Todo insumo nuevo empieza aquí, ya sea creado en el formulario o por importación CSV. No se puede agregar a pedidos. |
| `active` | **Activo** | El insumo se puede agregar a pedidos nuevos y aparece cuando alguien elige un insumo por nombre en la pantalla de recepción. |
| `inactive` | **Inactivo** | Un retiro sin borrado. El insumo, sus cajas y su historial se conservan; no se puede agregar a pedidos nuevos. |
```mermaid theme={null}
stateDiagram-v2
[*] --> draft: Crear insumo
draft --> active: Activar
active --> inactive: Desactivar
inactive --> active: Activar
```
No hay forma de volver a `draft`, y los insumos no se pueden eliminar. Desactiva los insumos que ya no uses.
### Por qué solo se pueden pedir insumos activos
Cuando alguien agrega un insumo a un pedido, muveya copia en la línea el SKU, el nombre, la unidad, la categoría, la marca de alto valor y el costo vigente del insumo. Esa copia solo tiene sentido si la unidad es definitiva, por eso la pantalla de pedidos ofrece solo insumos activos y el servidor rechaza cualquier otro con `orders.catalog_item_unavailable`: **Este insumo no está activo en el catálogo.** Las líneas que ya se agregaron conservan su copia aunque después el insumo se desactive o se edite. Consulta [Crear y seguir pedidos](/docs/es/orders/create-and-track).
## El detalle del insumo
Abre un insumo desde la lista. El título de la página es el nombre del insumo, con **Volver al catálogo** arriba.
* **Si tienes `catalog.manage`**, ves el mismo formulario de la creación con los valores actuales. El **SKU** está bloqueado y dice **El SKU identifica este insumo y no se puede cambiar.** Haz clic en **Guardar cambios**; **Insumo guardado** lo confirma.
* **Si no**, ves una lista de solo lectura: **SKU**, **Categoría**, **Unidad**, **Presentación**, **Descripción**, **Criticidad**, las cuatro opciones de trazabilidad como **Sí** o **No**, y **Costo** si tienes `catalog.cost.read`.
Debajo de los datos, todas las personas ven:
1. **Estado**, por ejemplo **Estado: Borrador**, con **Solo los insumos activos se pueden agregar a nuevos pedidos.**
2. **Presentaciones**: cómo se compra y se recibe el insumo. Consulta [Presentaciones y códigos](/docs/es/catalog/presentations-and-codes).
3. **Costo del insumo**, solo para quienes tienen `catalog.manage` y `catalog.cost.read`. Consulta [Costos](/docs/es/catalog/costs).
### Activar o desactivar
Ve a **Catálogo** y haz clic en el nombre del insumo.
Si el insumo no está activo, la sección de estado dice **La activación permite solicitar este insumo y fija su unidad:** seguido de la unidad. Si cambiaste la unidad y todavía no guardaste el cambio, dice **Guarda o descarta el cambio de unidad antes de activar.**
El botón dice **Activar y fijar unidad** cuando la activación también fijará la unidad, **Activar insumo** cuando la unidad ya está fija, y **Desactivar insumo** cuando el insumo está activo.
## La unidad queda fija
Las existencias, los pedidos y las presentaciones se cuentan en la unidad base del insumo, así que cambiarla después de usarla cambiaría el significado de las cantidades registradas. muveya protege la unidad:
* La unidad queda fija la primera vez que el insumo se *activa*, o la primera vez que se *reciben* existencias del insumo, aunque todavía sea un borrador.
* Una vez fija, sigue fija, también después de desactivar el insumo. El formulario muestra la unidad como texto con **Esta unidad está protegida y no puede cambiarse. Puedes editar los demás datos.**
* Todo lo demás, salvo el SKU, se puede seguir editando: nombre, descripción, categoría, presentación (el texto libre), criticidad y las opciones de trazabilidad.
Mientras la unidad no esté fija, puedes cambiarla y guardarla junto con los demás campos. Antes de guardar, el formulario muestra **Cambio elegido:** con la nueva unidad y un botón **Descartar cambio de unidad**. Cambiar la unidad tiene consecuencias:
* Un costo registrado para la unidad anterior pasa a `review_required` y debe confirmarse de nuevo. Consulta [Costos](/docs/es/catalog/costs).
* Una presentación publicada con la unidad anterior no sirve para recibir hasta que la corrijas, lo que la vuelve a publicar con la unidad actual.
Si la unidad no se puede verificar o cambió mientras tanto, el formulario te lo indica:
| Mensaje | Qué hacer |
| - | - |
| **Verificando unidad…** | Espera un momento. |
| **La unidad no puede guardarse con la información revisada. Revísala de nuevo o descarta ese cambio para guardar los demás datos.** | Otra persona cambió o fijó la unidad mientras editabas. Revisa la unidad actual o haz clic en **Descartar cambio de unidad**. |
| **No pudimos verificar si esta unidad puede cambiarse. Reintenta o guarda los demás datos.** | Haz clic en **Reintentar**. |
| **La configuración de unidad requiere revisión. Puedes editar los demás datos.** | Los datos guardados de la unidad son inconsistentes. Escribe a [team@muveya.com](mailto:team@muveya.com) con el SKU del insumo. |
| **No tienes permiso para revisar esta unidad.** | Solicita `catalog.manage`. |
## Identificadores
| Identificador | Dónde lo ves | Para qué sirve |
| - | - | - |
| SKU | En toda la consola | Tu propio código del insumo. Es lo que se usa para buscar y lo que la importación CSV usa para detectar duplicados. |
| `itemId` | En la barra de direcciones, `/catalog/items/:itemId` | El identificador interno permanente. Lo usan la API y MCP, por ejemplo `GET /v1/catalog/items/{itemId}`. |
| `categoryId` | En la pantalla de importación CSV | El identificador interno de la categoría, necesario en los archivos CSV. |
| Códigos del envase (GTIN, código del proveedor y código interno) | En **Presentaciones** | Encontrar una presentación al recibir. Consulta [Presentaciones y códigos](/docs/es/catalog/presentations-and-codes). |
La consola siempre muestra nombres y nunca identificadores, salvo en la pantalla de importación CSV, donde necesitas copiar los identificadores de categoría.
## Leer el catálogo fuera de la consola
La API pública lee el catálogo con `GET /v1/catalog/items` y `GET /v1/catalog/items/{itemId}` (scope `catalog:read`), y la herramienta MCP `catalog.search` busca insumos por nombre o SKU (los activos, por defecto). Ambas son de solo lectura: los insumos se crean y editan únicamente en la consola o mediante una importación CSV. Consulta [API para desarrolladores](/docs/es/api-reference/introduction) y [Herramientas MCP](/docs/es/mcp/tools).
## Qué registra el sistema
* El insumo, con estado `draft`, al crearlo.
* Cuando la unidad queda fija: quién la fijó y cuándo.
* Las ediciones de campos y los cambios de estado actualizan el insumo. En la versión actual no generan registros de auditoría separados; las importaciones CSV, las exportaciones y los retiros de códigos de envase sí.
## Qué puede salir mal
| Mensaje | Causa | Qué hacer |
| - | - | - |
| **Completa este campo.** | Falta un campo obligatorio. | Complétalo. |
| **Usa un máximo de 64 caracteres.** (o 200, 2000) | Un texto es demasiado largo. | Acórtalo. |
| **Usa letras, números, puntos, guiones, barras o guiones bajos.** | El SKU tiene espacios u otros caracteres. | Quítalos. |
| **Elige una opción válida.** | No elegiste categoría, unidad o criticidad. | Elige una. |
| **Este SKU ya existe. Usa un código diferente.** | `catalog.sku_taken`: otro insumo tiene ese SKU. | Usa otro SKU o abre el insumo existente. |
| **Esta categoría ya no está disponible. Elige otra.** | `catalog.category_not_found`. | Elige una categoría de la lista. |
| **La unidad cambió o requiere revisión. Revisa su configuración vigente antes de activar.** | `catalog.measurement_conflict` al activar. | Vuelve a cargar el insumo, revisa la unidad y actívalo de nuevo. |
| **Tu cuenta no tiene permiso para esta acción.** | No tienes `catalog.manage`. | Pide ayuda a un administrador de la clínica dental. |
| **Este registro no está disponible en la cuenta de clínica dental activa.** | El insumo no existe en la clínica dental con la que estás trabajando. | Revisa la clínica dental activa. |
| **Revisa los datos ingresados antes de volver a intentar.** | El servidor rechazó un valor. | Revisa cada campo con la tabla de arriba. |
| **Este insumo no está activo en el catálogo.** | Aparece en pedidos: el insumo está en borrador o inactivo. | Activa el insumo. |
## Páginas relacionadas
Crea los grupos a los que pertenece cada insumo.
Describe cómo se compra un insumo y los códigos impresos en él.
Registra costos y controla quién puede verlos.
Crea muchos insumos de una vez desde un archivo CSV.
Ingresa existencias de un insumo a una bodega.
Pide insumos activos para una sede.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.