> ## 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.
# Costos
> Registra cuánto cuesta un insumo, entiende los estados y el historial del costo, y controla quién puede verlo y cómo lo usan los pedidos.
Cada insumo puede tener un costo vigente: un monto por unidad base, en una moneda. Los costos son confidenciales. El servidor los omite en toda lectura salvo que la persona tenga el permiso de costos, y cada cambio conserva el costo anterior en un historial. Cuando alguien agrega el insumo a un pedido, la línea guarda una copia del costo vigente en ese momento.
## Quién puede hacerlo
| Acción | Permiso |
| - | - |
| Ver costos en la consola, en exportaciones CSV y en líneas de pedido | `catalog.cost.read` (**Ver costos de insumos**) |
| Registrar un costo en la consola | `catalog.manage` *y* `catalog.cost.read` |
| Leer costos mediante la API pública | Una clave de API con `catalog:read` *y* `catalog.cost:read` |
Ningún rol incluye `catalog.cost.read`, ni siquiera el de Propietario: siempre se otorga de forma explícita, persona por persona. Tenerlo no permite cambiar costos ni unidades. Consulta [Roles y permisos](/docs/es/account/roles-and-permissions).
## Dónde aparecen los costos
| Lugar | Lo que ves |
| - | - |
| Lista de **Catálogo** | Una columna **Costo**, solo con `catalog.cost.read`. |
| Detalle del insumo, vista de solo lectura | Una fila **Costo**, solo con `catalog.cost.read`. |
| Detalle del insumo, sección **Costo del insumo** | El formulario para registrar un costo, solo con `catalog.manage` y `catalog.cost.read`. |
| Importación CSV | Columnas opcionales `cost` y `currency`. Consulta [Importar y exportar](/docs/es/catalog/import-export). |
| Exportación CSV | Seis columnas de costo, solo con `catalog.cost.read`. |
| Líneas de pedido | El costo copiado al agregar la línea, solo con `catalog.cost.read`. |
## Montos, monedas y unidades menores
muveya guarda cada monto como un número entero de *unidades menores* de la moneda, como los centavos, junto con un código de moneda ISO 4217 de tres letras mayúsculas. Así los montos son exactos.
| Lo que quieres decir | `cost` guardado | `currency` |
| - | - | - |
| USD 12,00 | `1200` | `USD` |
| USD 0,35 | `35` | `USD` |
| BRL 7,90 | `790` | `BRL` |
| CLP 1.200 | `1200` | `CLP` |
* **En la consola** escribes el monto en unidades normales: dígitos, opcionalmente seguidos de un punto o una coma decimal y como máximo tantos decimales como use la moneda (dos para USD y BRL, ninguno para CLP). No uses separadores de miles: `1250,50` es válido, `1.250,50` no. La consola convierte el monto a unidades menores de forma exacta y nunca adivina la moneda.
* **En archivos CSV y en la API** el monto ya está en unidades menores: un número entero como `1200`.
* `0` es un costo válido y es distinto de no tener costo. No se aceptan montos negativos.
## Registrar un costo
Ve a **Catálogo** y haz clic en el nombre del insumo.
Está al final de la página: **Los cambios de costo se guardan por separado y conservan su historial.** La línea **Costo por** seguida de la unidad, por ejemplo **Costo por Caja**, indica a qué unidad base se aplicará el monto.
Escribe el **Monto** (**Elige una moneda e ingresa el monto sin separadores de miles.**) y la **Moneda**, por ejemplo `CLP`. Si el insumo ya tiene costo, ambos campos empiezan con él.
Haz clic en **Guardar costo**. **Costo guardado** lo confirma.
Qué pasa al guardar:
* El costo anterior, si existe, se cierra y queda en el historial.
* El nuevo monto pasa a ser el costo vigente desde ese momento.
* El costo queda asociado a la unidad del insumo tal como estaba cuando la revisaste. Si la unidad cambió mientras tanto, no se guarda nada y el formulario dice **La unidad que revisaste cambió. Revisa la unidad actual antes de confirmar este importe.**, luego **Unidad actual:** con la unidad y un botón **Revisar costo para la unidad actual**. Haz clic en él, revisa el monto y guarda otra vez.
El formulario de creación no tiene campo de costo. Un insumo nuevo recibe su primer costo aquí o desde una importación CSV.
Usa una sola moneda para todos los insumos de tu clínica dental. El valor de un pedido suma solo las líneas en la moneda de su primera línea con costo; las líneas en otra moneda quedan fuera del valor.
## Estados del costo
Toda lectura que incluye un costo incluye también `costStatus`. Revisa el estado antes de usar el monto.
| `costStatus` | Lo que muestra la consola | Significado | Qué hacer |
| - | - | - | - |
| `unset` | **Sin definir** | Nunca se registró un costo. No es lo mismo que un costo igual a cero. | Registra un costo si quieres que los pedidos tengan valor. |
| `verified` | El monto y **Costo por** la unidad | El monto se aplica a la unidad actual del insumo. | Nada. |
| `review_required` | El monto, **Registrado por** la unidad anterior y **Requiere confirmación para la unidad actual.** | Existe un monto anterior, pero se registró para una unidad que el insumo ya no tiene, o viene de datos antiguos sin unidad. No lo multipliques por cantidades de la unidad actual. | Guarda el costo otra vez en **Costo del insumo** para confirmarlo para la unidad actual. |
| `invalid` | **Los datos anteriores del costo requieren revisión.**, con el monto si se pudo leer | Los datos guardados del costo son inconsistentes. Nunca se convierten en dinero ni se tratan como ausentes. El formulario de costo queda deshabilitado. | Escribe a [team@muveya.com](mailto:team@muveya.com) con el SKU del insumo. |
Un costo `review_required` suele aparecer después de que alguien cambia la unidad del insumo mientras todavía se puede editar. Consulta [Insumos del catálogo](/docs/es/catalog/items#la-unidad-queda-fija).
Donde iría un costo pueden aparecer otros dos mensajes:
* **La información del costo no está disponible.**: tienes el permiso, pero no se pudo leer el costo. Vuelve a cargar la página.
* **La unidad registrada no está disponible.**: se muestra el monto, pero falta la unidad a la que corresponde.
## Historial del costo
Cada vez que se reemplaza un costo, el anterior se cierra y se guarda con su monto, su moneda, el momento en que empezó a regir, quién lo registró y la unidad a la que correspondía. El historial solo crece: nada se edita ni se borra.
La versión actual no tiene pantalla, operación de API ni herramienta MCP para consultar el historial de costos. Las líneas de pedido conservan el costo que copiaron, así que los pedidos pasados siguen mostrando lo que se pagó en su momento.
## Omisión de datos: quién ve qué
Los costos se omiten en el servidor; no solo se ocultan en la pantalla. Para una persona sin `catalog.cost.read`:
* Los campos `cost`, `currency`, `costStatus` y `costMeasurement` no existen en ninguna lectura del catálogo: la consola, `GET /v1/catalog/items`, `GET /v1/catalog/items/{itemId}` y la herramienta MCP `catalog.search`. No existir significa no existir, nunca cero.
* Una exportación CSV no trae las seis columnas de costo.
* Las líneas de pedido no muestran su copia del costo.
* Guardar un costo nunca devuelve el monto en la respuesta.
El valor total del pedido depende de otro permiso, `orders.value.read`. Consulta [Crear y seguir pedidos](/docs/es/orders/create-and-track).
Así se ve un costo en una lectura de la API hecha con una clave que tiene `catalog.cost:read`:
```json theme={null}
{
"itemId": "665f1a2b3c4d5e6f7a8b9c0d",
"sku": "GLV-NIT-M",
"name": "Nitrile gloves size M",
"categoryId": "665f1a2b3c4d5e6f7a8b9c01",
"unitOfMeasure": "pair",
"criticality": "high",
"tracksLot": true,
"tracksSerial": false,
"tracksExpiry": true,
"highValue": false,
"status": "active",
"costStatus": "review_required",
"cost": 1200,
"currency": "CLP",
"costMeasurement": {
"unitOfMeasure": "unit",
"measurementVersion": 1,
"quantityProtocol": "base_number_v1"
}
}
```
Aquí el monto se registró por `unit`, pero el insumo ahora se cuenta en `pair`, así que el monto debe confirmarse antes de aplicarse. `costMeasurement` indica la unidad, su versión y la regla de cantidad (`base_number_v1`, números enteros de la unidad base) para las que se registró el monto.
## Cómo usan el costo los pedidos
Cuando alguien agrega un insumo a un pedido en borrador, muveya copia en la línea el costo vigente en ese momento, junto con el SKU, el nombre, la unidad, la categoría y la marca de alto valor.
| `costStatus` del insumo al agregar la línea | Resultado |
| - | - |
| `verified` | La línea guarda el monto y la moneda. |
| `unset` | La línea se agrega sin costo y no suma nada al valor del pedido. |
| `review_required` o `invalid` | La línea se rechaza con `catalog.cost_unverified`. La pantalla del pedido muestra **El registro cambió o ya existe. Revísalo antes de volver a intentar.** Confirma el costo en el insumo y agrega la línea de nuevo. |
* Cambiar el costo después no modifica las líneas ya agregadas.
* El valor del pedido es la suma del costo por la cantidad solicitada en las líneas que tienen costo, en la moneda de la primera de ellas.
* Las reglas de aprobación con valor mínimo o máximo de pedido usan ese valor, así que los insumos sin costo no cuentan. Consulta [Política de aprobación](/docs/es/orders/approval-policy).
## Qué registra el sistema
* El costo vigente, con su moneda, el momento en que empezó a regir, quién lo registró y la unidad a la que corresponde.
* Los costos anteriores cerrados, en el historial.
* En cada línea de pedido, el costo y la moneda copiados.
## Qué puede salir mal
| Mensaje | Código | Qué hacer |
| - | - | - |
| **Ingresa un monto exacto, no negativo y sin separadores de miles.** | | Quita separadores y decimales de más. |
| **Usa un código de moneda de tres letras mayúsculas, como CLP.** | | Escribe un código como `CLP`. |
| **Completa este campo.** | | Ingresa un monto. |
| **La unidad que revisaste cambió. Revisa la unidad actual antes de confirmar este importe.** | `catalog.measurement_conflict` | Haz clic en **Revisar costo para la unidad actual** y guarda de nuevo. |
| **No se confirmó el cambio. Intenta nuevamente.** | `catalog.cost_clock_conflict` | El nuevo costo no obtuvo una hora posterior a la del costo vigente. Guarda de nuevo. |
| **Los datos anteriores del costo requieren revisión.** | `catalog.cost_unverified` | El costo o su historial no se pueden usar con seguridad. Escribe a [team@muveya.com](mailto:team@muveya.com). |
| **La configuración de unidad requiere revisión. Puedes editar los demás datos.** | `catalog.measurement_unverified` | Escribe a [team@muveya.com](mailto:team@muveya.com) con el SKU. |
| **Tu cuenta no tiene permiso para esta acción.** | `tenants.insufficient_role` | Solicita `catalog.manage`. |
| **Este registro no está disponible en la cuenta de clínica dental activa.** | `catalog.item_not_found` | Revisa la clínica dental activa. |
| **Falta un campo obligatorio.** (fila de importación CSV) | `catalog.cost_incomplete` | La fila tiene costo sin moneda, o moneda sin costo. Indica ambos o ninguno. |
Ninguno de estos errores aplica el cambio propuesto. Revisa la información antes de volver a intentar.
## Páginas relacionadas
Insumos, unidades y estados.
Costos en archivos CSV.
Dónde aparecen las copias del costo y el valor del pedido.
Reglas de aprobación según el valor del pedido.
Otorga **Ver costos de insumos**.
`catalog:read` y `catalog.cost:read`.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.