> ## 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.

# Conceptos

> El modelo detrás de cada pantalla de muveya: clínica dental, sedes, bodegas, insumos, cajas, registro de movimientos, pedidos, aprobaciones, custodia y permisos

Esta página explica los objetos con los que trabajas en muveya y las reglas que el servidor les aplica. Cada sección da la etiqueta de la consola, el identificador que usan la API y el código, y enlaces a las páginas de tareas. El [Glosario](/docs/es/glossary) lista cada término en los tres idiomas.

## Tu clínica dental

Una **clínica dental** (`tenant` en la API y el código) es tu cuenta de cliente: una clínica independiente o una red dental completa. Es el límite de aislamiento de muveya.

* Todo registro operativo (sedes, bodegas, insumos, cajas, movimientos, pedidos, decisiones, entregas) pertenece a una sola clínica dental. Nada se comparte ni se mueve entre dos de ellas, y una solicitud que no corresponde a tu clínica dental se rechaza.
* Una persona puede pertenecer a varias clínicas dentales. Usa **Elige una clínica dental** en **Inicio**, o el selector en la parte superior de la barra lateral, para cambiar la clínica en la que trabajas. El rol, los permisos y el acceso a sedes y bodegas se definen por separado en cada una.
* Una clave de API pertenece a una sola clínica dental. La API pública deduce la clínica dental a partir de la clave y nunca la acepta como parámetro. Consulta [Autenticación](/docs/es/api-reference/authentication).

## Sedes

Una **sede** (`clinic`, `clinicId`) es un sitio operativo de tu clínica dental, el lugar donde se piden, reciben y consumen insumos. La consola las lista en **Sedes**.

| Campo | Reglas |
| - | - |
| Nombre | Obligatorio, de 1 a 120 caracteres. Se puede renombrar. |
| Estado | `active` o `inactive` (**Activar sede** / **Desactivar sede**). No se puede crear un pedido nuevo para una sede inactiva. |

El **Acceso a sedes** de una persona decide qué pedidos, aprobaciones y entregas ve. Consulta [Sedes](/docs/es/locations/clinics).

## Bodegas

Una **bodega** (`warehouse`, `warehouseId`) es un lugar donde se guardan cajas. Cada caja está en una sola bodega a la vez.

| Tipo | `kind` | Pertenece a | Uso típico |
| - | - | - | - |
| **Central** | `central` | Ninguna sede; sirve a toda la clínica dental | El almacén principal que abastece a varias sedes |
| **Express** | `express` | Una sola sede, elegida al crearla | El pequeño almacén dentro de una sede, donde se entregan sus pedidos |

Reglas que aplica el servidor:

* Una bodega express debe indicar una sede existente de tu clínica dental; una bodega central no debe indicar ninguna.
* El nombre es obligatorio, de 1 a 120 caracteres.
* El estado es `active` o `inactive`. Una bodega inactiva no recibe existencias nuevas (se rechaza recibir en ella o trasladarle una caja) y no se puede elegir en pedidos nuevos.
* En la consola, **Entregar en la bodega** de un pedido nuevo ofrece solo las bodegas activas que pertenecen a la sede elegida, así que una sede necesita una bodega express antes de poder pedir. El servidor nunca acepta como destino la bodega express de otra sede. **Tomar existencias de** ofrece bodegas centrales.

El **Acceso a bodegas** de una persona decide qué existencias ve y mueve. Consulta [Bodegas](/docs/es/locations/warehouses).

## Boxes y áreas

Un **box o área** (`destination`, `destinationId`) es un lugar dentro de una sede donde se usan insumos: un box de atención (`treatment_room`) o cualquier otra área (`area`). Los boxes y áreas se gestionan desde la página de la sede.

| Control de stock | `stockControl` | Qué significa |
| - | - | - |
| **Sin conteo** | `uncounted` | Lo que se entrega al box sale del inventario de inmediato; lo que queda en el box no se cuenta. |
| **Stock contado** | `controlled` | El box guarda existencias contadas propias en una bodega express de la misma sede, su **Punto de stock**. La consola puede crear esa bodega automáticamente. Una bodega respalda como máximo un box. |

Los nombres de los boxes y áreas son únicos dentro de una sede. Un box está `active` o `inactive`; desactivarlo conserva su nombre en los registros pasados.

Al registrar un consumo de una caja puedes indicar adónde fue y cómo:

* **Qué pasó** (`usage`): **Uso directo** (`use`) o **Entrega al box o área** (`issue`). Una entrega a un box sale del inventario una sola vez; quién la usó se puede atribuir después en **Uso por box o área** sin volver a descontar existencias.
* **Propósito** (`purpose`): `procedure`, `cleaning`, `administrative` u `other`.
* **Responsable** (`responsibleUserId`): la persona del equipo responsable, que puede ser distinta de quien registra.
* **Referencia de atención (opcional)** (`careRef`): el código de tu sistema clínico, nunca el nombre de un paciente. Letras, dígitos y `. _ : / -`, sin espacios, hasta 64 caracteres. Se guarda sellada.

Un box con **Stock contado** rechaza **Entrega al box o área** y solo acepta consumos registrados desde una caja que ya está en su punto de stock: primero traslada la caja completa. Una caja en una bodega express solo se puede atribuir a boxes y áreas de la sede de esa bodega; una caja en una bodega central se puede atribuir a boxes y áreas de cualquier sede. Consulta [Boxes y áreas](/docs/es/locations/destinations) y [Registrar consumo y trasladar cajas](/docs/es/inventory/use-and-moves).

## Insumos y catálogo

Un **insumo** (`CatalogItem`, `itemId`) es un artículo que tu clínica dental autorizó. Describe lo que se puede pedir y recibir; no representa existencias.

| Campo | Campo de la API | Reglas |
| - | - | - |
| **SKU** | `sku` | Obligatorio, único en tu clínica dental, hasta 64 caracteres (letras, dígitos, `.`, `_`, `/`, `-`). No se puede cambiar después. |
| **Nombre del insumo** | `name` | Obligatorio, hasta 200 caracteres. |
| **Categoría** | `categoryId` | Obligatoria; una categoría de tu clínica dental. |
| **Unidad** | `unitOfMeasure` | La unidad base en que se cuenta toda cantidad de este insumo. Queda fija al activar el insumo o al recibirlo por primera vez. |
| **Criticidad** | `criticality` | `low`, `medium` o `high`. |
| **Presentación** | `packaging` | Texto libre, solo descriptivo. Nunca cambia cantidades. No confundir con las **Presentaciones** del insumo. |
| **Controlar lotes**, **Controlar números de serie**, **Controlar vencimientos** | `tracksLot`, `tracksSerial`, `tracksExpiry` | Lo que una recepción debe registrar para cada caja. |
| **Insumo de alto valor** | `highValue` | Puede activar reglas de aprobación, y toda corrección de sus existencias requiere una segunda persona. |
| **Costo**, **Moneda** | `cost`, `currency` | Opcionales. Consulta [Costos](/docs/es/catalog/costs). |

**Estado.** Un insumo nace `draft` (**Borrador**). Al activarlo (**Activar y fijar unidad**) pasa a `active` (**Activo**) y su unidad queda fija. `inactive` (**Inactivo**) es un retiro sin borrado: no se elimina nada. Solo los insumos activos se pueden agregar a pedidos, y la consola solo ofrece insumos activos al recibir.

**Unidades.** La unidad base sale de una lista cerrada:

| `unitOfMeasure` | Etiqueta en la consola |
| - | - |
| `unit` | **Unidad** |
| `box` | **Caja** |
| `pack` | **Paquete** |
| `bottle` | **Botella** |
| `ampoule` | **Ampolla** |
| `milliliter` | **Mililitro** |
| `liter` | **Litro** |
| `gram` | **Gramo** |
| `kilogram` | **Kilogramo** |
| `pair` | **Par** |
| `kit` | **Kit** |

**Presentaciones.** Una presentación (`presentationId`) es cómo compras el insumo, por ejemplo "Caja de 100". Sus **Unidades base que contiene** son un número entero desde 1. Recibir 3 de una presentación que contiene 100 suma 300 unidades base. Las presentaciones tienen versiones: corregir una publica una versión nueva, y las cajas ya recibidas conservan la versión con que se recibieron. Una presentación está `active` o `retired`; una retirada ya no se puede recibir.

**Códigos.** Una presentación puede tener códigos impresos en el empaque: `gtin` (**GTIN (código de barras)**, de 8 a 14 dígitos), `supplier` (**Código del proveedor**) e `internal` (**Código interno**). Un código identifica qué artículo es, no qué caja es, y apunta a una sola presentación a la vez. Consulta [Presentaciones y códigos](/docs/es/catalog/presentations-and-codes).

## Cajas

Una **caja** (`StockBox`, `boxId`) es un contenedor físico de un insumo. Tiene:

* un **código de caja** (`code`) único en tu clínica dental. Puedes escribir tu propia etiqueta al recibir, o muveya genera una;
* el insumo que contiene y su cantidad, siempre en la unidad base del insumo;
* el lote, los números de serie y la fecha de vencimiento cuando el insumo los controla;
* **Recibida como**: la presentación, la versión y la cantidad con que llegó, cuando se recibió como presentación;
* la bodega en la que está y su estado.

Una caja solo se crea con una recepción, o al separar parte de otra caja. Nunca se edita: su cantidad solo cambia mediante movimientos del registro.

| Estado | Etiqueta en la consola | Significado |
| - | - | - |
| `active` | **Activa** | En una bodega y utilizable, salvo que su fecha de vencimiento ya haya pasado |
| `in_transit` | **En tránsito** | Despachada para un pedido y aún no recibida. No se puede reservar, consumir ni trasladar. |
| `quarantine` | **En cuarentena** | Apartada para revisión. No acepta movimientos y nunca se toma para un pedido. |
| `expired` | **Vencida** | Marcada como vencida. Fuera de las existencias utilizables. |
| `depleted` | **Agotada** | Su cantidad en mano llegó a cero por consumo o por una corrección. |
| `disposed` | **Dada de baja** | Descartada. Fuera de las existencias utilizables. |

Cómo cambia el estado de una caja:

* De `active` a `depleted`: un consumo, o una corrección, que la deja en cero.
* De `active` a `quarantine`, `expired` o `disposed`: **Sacar la caja de uso**, que solo aparece en cajas activas. muveya también acepta dar de baja una caja en cuarentena o vencida, pero la consola no tiene un botón para eso. El [Retiro de lote](/docs/es/inventory/lot-recall) pone en cuarentena de una vez todas las cajas activas de un lote.
* De `active` a `in_transit`: el despacho. De `in_transit` a `active` en la bodega de destino: una recepción aceptada. De `in_transit` de vuelta al origen como `active` o `quarantine`: una recepción disputada.

**Vencimiento.** Una caja cuya fecha de vencimiento ya pasó no se puede consumir, reservar ni separar, aunque su estado siga siendo `active`. La fecha de vencimiento vale hasta el final de ese día calendario en UTC.

**Separar parte de una caja** crea un contenedor nuevo con el mismo insumo, lote, vencimiento y fecha de recepción, vinculado a su caja de origen. Solo se pueden separar unidades libres (no reservadas), nunca todo el contenido, y no desde una caja que controla números de serie. Al preparar un pedido, una caja se separa automáticamente cuando contiene más de lo que el pedido necesita. Consulta [Cajas y etiquetas](/docs/es/inventory/boxes).

## El registro de movimientos

Cada cambio de existencias es un **movimiento** (`StockMovement`) que se agrega a un registro inmutable. Un movimiento guarda su tipo, la caja, el insumo, el cambio de cantidad, quién lo hizo (`actorId`), cuándo ocurrió (`occurredAt`, según el reloj del servidor) y, cuando corresponde, el pedido, las bodegas, un motivo, la segunda persona que aprobó o el box o área.

Nada en el registro se edita ni se borra. Un error se corrige con un movimiento nuevo que lo compensa, y el original sigue visible.

| Tipo | Etiqueta en la consola | Se registra cuando | En mano | Reservado |
| - | - | - | - | - |
| `receive` | **Recibido** | Se reciben existencias, o una caja aceptada llega al destino del pedido | sube | sin cambio |
| `reserve` | **Reservado** | Se reservan existencias para un pedido aprobado | sin cambio | sube |
| `release` | **Liberado** | Se libera una reserva | sin cambio | baja |
| `pick` | **Tomado para el pedido** | Se escanea una caja reservada para su pedido | sin cambio | sin cambio |
| `dispatch` | **Despachado** | Una caja tomada sale de su bodega | baja | baja |
| `transfer_out`, `transfer_in` | **Salida por traslado**, **Entrada por traslado** | Una caja completa pasa a otra bodega | sin cambio | sin cambio |
| `split_out`, `split_in` | **Separación (salida)**, **Separación (entrada)** | Parte de una caja se separa en un contenedor nuevo | baja en la caja original, sube en la nueva | sin cambio |
| `consume` | **Consumido** | Se registra un consumo | baja | sin cambio |
| `return` | **Devuelto** | Una caja disputada vuelve a la bodega de donde salió | sube | sin cambio |
| `adjust_gain`, `adjust_loss` | **Corrección (alta)**, **Corrección (baja)** | Se aplica una corrección o una diferencia de conteo | sube o baja | sin cambio |
| `expire` | **Vencido** | Una caja se marca como vencida | sin cambio | sin cambio |
| `quarantine` | **En cuarentena** | Una caja o un lote entra en cuarentena | sin cambio | sin cambio |
| `dispose` | **Desechado** | Una caja se da de baja | sin cambio | sin cambio |

Una operación reintentada nunca cuenta dos veces: cada una lleva una clave de idempotencia, y una repetición devuelve el primer resultado. Consulta [Resumen del inventario](/docs/es/inventory/overview).

## Saldos

Para cada caja, muveya deriva del registro:

| Cifra | Campo | Significado |
| - | - | - |
| **En mano** | `onHand` | La cantidad física en la caja: la suma de sus cambios en mano. Nunca es menor que cero. |
| **Reservado** | `reserved` | La parte comprometida con pedidos aprobados. |
| **Disponible** | `available` | `onHand - reserved`: lo que todavía se puede reservar. |

**Reposición** muestra además **Utilizable ahora**: las existencias de cajas activas y no vencidas que realmente se pueden usar.

## FEFO y FIFO

Cuando muveya reserva existencias para un pedido, ordena las cajas candidatas de cada insumo:

* **FEFO** (`fefo`, lo primero que vence es lo primero que sale) cuando alguna caja candidata tiene fecha de vencimiento: primero el vencimiento más próximo, las cajas sin vencimiento al final, y luego la recepción más antigua.
* **FIFO** (`fifo`, lo primero que entra es lo primero que sale) en los demás casos: primero la recepción más antigua.

Solo son candidatas las cajas activas y no vencidas. Si el pedido indica una bodega de origen (**Tomar existencias de**), solo se consideran las cajas de esa bodega; si no, el servidor no limita la búsqueda a una bodega. Una línea puede tomar de varias cajas.

## Pedidos

Un **pedido** (`Order`, `orderId`) es una solicitud interna de insumos de una sede, que se entrega en una de sus bodegas. Cada pedido tiene un número único en tu clínica dental (`number`, se muestra como `#12`).

| Tipo | `type` | Quién puede crearlo | Datos adicionales |
| - | - | - | - |
| **General** | `general` | `orders.create` | Motivo opcional |
| **Clínico** | `clinical` | `orders.create` y `orders.clinical.create` (la opción **Es para el tratamiento de un paciente** de la consola) | Referencia del paciente opcional (`patientRef`), hasta 200 caracteres |

Reglas:

* Solo quien pidió puede agregar, cambiar o quitar líneas, y solo mientras el pedido es un borrador. Cada línea es un insumo activo y una cantidad entera de al menos 1, en la unidad base del insumo. Al agregar una línea, guarda una copia del costo, la categoría y la marca de alto valor del insumo.
* Solo quien pidió puede enviar el pedido, y necesita al menos una línea. El valor del pedido queda congelado al enviarlo.
* El **Motivo (opcional)** admite hasta 2000 caracteres y se rechaza si parece contener datos personales.
* Solo quien pidió puede cancelarlo, y solo desde `draft`, `submitted` o `pending_approval`.
* Enviar y cancelar verifican la versión del pedido: si el pedido cambió un momento antes, la acción se rechaza y la pantalla muestra la versión más reciente.

| Estado | Etiqueta en la consola | Significado |
| - | - | - |
| `draft` | **Borrador** | En preparación por quien pide |
| `submitted` | **Enviado** | Enviado; espera que se aplique la política de aprobación |
| `pending_approval` | **Esperando aprobación** | Necesita una o más decisiones |
| `approved` | **Aprobado** | Aprobado; todavía sin existencias reservadas |
| `rejected` | **Rechazado** | Rechazado. Final. |
| `cancelled` | **Cancelado** | Cancelado por quien pidió. Final. |
| `allocated` | **Existencias reservadas** | Todas las líneas tienen existencias reservadas |
| `picking` | **En preparación** | Se tomó al menos una caja |
| `dispatched` | **Despachado** | Las cajas salieron de la bodega de origen |
| `delivered` | **Entregado** | Entrega confirmada |
| `exception` | **Problema de entrega** | Entrega confirmada con un problema |
| `received` | **Recibido** | Todas las cajas aceptadas en el destino |
| `partially_fulfilled` | **Recibido en parte** | Al menos una caja disputada |
| `closed` | **Cerrado** | Cerrado por el destino. Final. |

```mermaid theme={null}
stateDiagram-v2
    [*] --> draft
    draft --> submitted: enviar
    draft --> cancelled: cancelar
    submitted --> pending_approval: la política exige aprobación
    submitted --> approved: la política no exige aprobación
    submitted --> cancelled: cancelar
    pending_approval --> approved: aprobado en todas las etapas
    pending_approval --> rejected: rechazado
    pending_approval --> cancelled: cancelar
    approved --> allocated: existencias reservadas
    allocated --> picking: primera caja tomada
    picking --> dispatched: despacho
    dispatched --> delivered: entrega confirmada
    dispatched --> exception: problema de entrega informado
    delivered --> received: todas las cajas aceptadas
    delivered --> partially_fulfilled: una caja disputada
    received --> closed: cerrar
    partially_fulfilled --> closed: cerrar
    rejected --> [*]
    cancelled --> [*]
    closed --> [*]
```

Cualquier otro cambio de estado se rechaza. Consulta [Crear y seguir pedidos](/docs/es/orders/create-and-track).

## Aprobaciones y separación de funciones

La **política de aprobación** decide qué pedidos enviados necesitan la decisión de alguien. Consulta [Política de aprobación](/docs/es/orders/approval-policy).

* **Versiones.** Publicar crea una versión nueva (`policyVersion`) que reemplaza a la vigente. Las versiones publicadas nunca se editan. Hasta que se publica la primera versión, los pedidos enviados se quedan en `submitted`; después, se procesan la próxima vez que se envía cualquier pedido.
* **Reglas.** Cada regla tiene condiciones y un requisito. Condiciones: rango de valor del pedido (`minValue`, `maxValue`, en unidades menores, inclusive), tipos de pedido (`orderTypes`), categorías (`categories`) e insumos de alto valor (`highValue`). Una condición vacía coincide con todo pedido; una condición de valor nunca coincide con un pedido sin valor. El requisito es un **Nombre de la etapa** (`stage`, hasta 64 caracteres), el permiso que debe tener quien decide (`requiredScope`, `approvals.decide` cuando la consola escribe la regla) y **Personas que deben aprobar** (`minApprovers`, de 1 a 10). Una política tiene como máximo 100 reglas.
* **Evaluación.** Al enviar, muveya aplica la versión vigente al pedido y guarda el plan resultante con el pedido. Si ninguna regla coincide (o la política no tiene reglas, como con **Publicar sin aprobaciones**), el sistema aprueba el pedido de inmediato (`auto_approve`) y la aprobación automática queda auditada.
* **Decisiones.** Quien decide elige una etapa y elige **Aprobar** o **Rechazar**. Un rechazo termina el pedido de inmediato. El pedido pasa a `approved` solo cuando cada etapa tiene la cantidad requerida de aprobadores distintos. Cada decisión es un registro inmutable (`approved` o `rejected`) con la persona, la hora, la etapa, la versión de la política y un comentario opcional (hasta 500 caracteres en la consola).

Separación de funciones:

* **Quien pidió nunca puede decidir su propio pedido.** El intento se rechaza y queda auditado, y la bandeja de aprobaciones nunca muestra tus propios pedidos.
* Una persona decide una misma etapa de un pedido una sola vez.
* Quien decide debe tener todos los permisos que exige la etapa y acceso a la sede del pedido.
* Una decisión tomada sobre una versión desactualizada del pedido se rechaza sin escribir nada.
* Las correcciones de existencias sobre su umbral necesitan una segunda persona distinta (consulta la sección Conteos y correcciones).
* La entrega se confirma desde el lado de origen (`delivery.confirm`) y la recepción desde el lado de destino (`receipt.confirm`). Una persona limitada a sedes específicas que tiene acceso tanto a la sede de origen como a una sede de destino distinta no puede confirmar la recepción ni cerrar el pedido.

Consulta [Aprobar o rechazar pedidos](/docs/es/orders/approvals).

## Abastecimiento y custodia

Una vez aprobado, un pedido se ejecuta mediante un **abastecimiento** (`fulfillment`), que sigue las cajas desde la bodega de origen hasta el destino. La custodia es por caja completa: una caja viaja entera, y una caja que contiene más de lo que el pedido necesita se separa primero.

| Paso | Quién | Estado del pedido después | Registro | Caja |
| - | - | - | - | - |
| Asignación | El sistema, justo después de aprobar | `allocated` | `reserve` en cada caja elegida | Sigue `active` |
| Preparación | `fulfillment.pick` | `picking` (primera caja) | `pick`; además `split_out`, `split_in`, `release` y `reserve` cuando se separa una caja | Sigue `active` |
| Despacho | `fulfillment.dispatch` | `dispatched` | `dispatch` | `in_transit` |
| Entrega | `delivery.confirm` | `delivered`, o `exception` con un problema | Ninguno | Sigue `in_transit` |
| Recepción | `receipt.confirm` | `received`, o `partially_fulfilled` con una disputa | Caja aceptada: `receive` en el destino. Caja disputada: `return` en el origen | Aceptada: `active` en el destino. Disputada: `active` o `quarantine` en el origen |
| Cierre | `fulfillment.close` | `closed` | Ninguno | Sin cambio |

El abastecimiento también tiene su propio estado: `allocating` (**Reservando existencias**) mientras corre la reserva, y luego los mismos valores del pedido, de `allocated` a `closed`.

Reglas que conviene conocer:

* **La asignación es todo o nada.** Si una línea no se puede reservar por completo, se libera todo lo reservado en ese intento y el pedido se queda en **Aprobado**. muveya lo vuelve a intentar en una asignación posterior.
* **La preparación** solo acepta cajas reservadas para ese pedido; cada caja se registra una sola vez.
* **El despacho**: la consola ofrece **Despachar pedido** cuando todas las cajas reservadas están tomadas, y puedes anotar el transportista. Cada caja tomada debe contener exactamente la cantidad del pedido, algo que la preparación garantiza al separar las cajas más grandes.
* **Los problemas de entrega** abarcan todo el envío. La consola ofrece **No se pudo entregar**, **Llegó dañado**, **Fue a un lugar equivocado** y **Otra cosa**, más detalles opcionales. Un pedido en `exception` no se puede recibir ni cerrar desde la consola, y sus cajas siguen **En tránsito**; escribe a [team@muveya.com](mailto:team@muveya.com) para resolverlo.
* **La recepción** debe decidir cada caja entregada una vez. Una caja disputada necesita un motivo (la consola ofrece **Dañada**, **Falta**, **Insumo equivocado**, **Vencida** y **Otro**) y una descripción en **Evidencia del problema**; puedes pedir que quede en cuarentena cuando vuelva.
* **El cierre** no mueve existencias; está disponible cuando cada caja se aceptó o se devolvió.
* Cada uno de estos pasos escribe un registro inmutable con la persona y la hora. El **Historial** del pedido en **Entregas** los muestra junto con los movimientos de las cajas.

Consulta [Resumen de entregas](/docs/es/deliveries/overview) e [Historial de custodia](/docs/es/deliveries/custody-history).

## Conteos y correcciones

Las verificaciones físicas y las correcciones requieren `inventory.adjust`.

* **Corregir esta caja** registra un alta o una baja con una cantidad y un motivo (**Corrección de conteo**, **Dañado**, **Uso no registrado**, **Otro**).
* **Contar un insumo** cuenta las cajas activas de un insumo en una bodega. **Empezar a contar** abre un conteo antes de contar, para detectar cualquier movimiento que ocurra mientras tanto. Un conteo (`cycleCount`) está `open`, `submitted` o `cancelled`. Al guardarlo, cada caja termina sin diferencia, corregida, esperando aprobación o con cambios durante el conteo (hay que contar de nuevo).
* Una **campaña de conteo** (`countCampaign`) agrupa los conteos de una bodega y está `open` (**En curso**) o `closed` (**Cerrado**). **Conteos** también lista las cajas que no se contaron recientemente.
* **Umbral de aprobación.** Una corrección mayor que el umbral todavía no cambia las existencias: se convierte en una solicitud en **Correcciones de existencias** que otra persona con `inventory.adjust` debe aprobar desde su propia sesión. El umbral es de 100 unidades base por defecto; un mínimo por bodega puede bajarlo (de 0 a 100), nunca subirlo. Para insumos de alto valor, toda corrección requiere otra persona. Una caja tiene como máximo una solicitud pendiente.

| Estado de la solicitud | Etiqueta en la consola | Resultado |
| - | - | - |
| `pending` | **Pendientes** | Todavía no se escribe nada |
| `approved` | **Aprobada por …** | Se escribe exactamente un movimiento de corrección, con ambas personas |
| `rejected` | **Rechazada por …** | No se escribe nada |
| `withdrawn` | **Retirada** | No se escribe nada |
| `stale` | **Desactualizada: la caja cambió** | No se escribe nada; hay que solicitar o contar de nuevo |

Consulta [Correcciones](/docs/es/inventory/corrections) y [Conteos](/docs/es/inventory/counts).

## Reposición y alertas

Un **mínimo por bodega** (`stockPolicy`) se define para un insumo en una bodega, en su unidad base:

| Campo | Reglas |
| - | - |
| **Mínimo** | Número entero desde 0. Cero significa "nunca alertar". |
| **Pedido habitual** | Opcional, número entero desde 1. Se sugiere cuando el insumo queda bajo el mínimo. |
| **Avisar antes del vencimiento (días)** | Opcional, de 1 a 365. Por defecto, 30. |
| **Umbral de aprobación** | Opcional, de 0 a 100. |

**Reposición** compara **Utilizable ahora** con el mínimo: **Bajo el mínimo** (`below_minimum`), **Suficiente** (`ok`) o **Sin mínimo** (`no_minimum`).

Las **alertas de existencias** se generan solas: `low_stock` (**Bajo el mínimo**) y `expiry_approaching` (**Por vencer**, que se muestra como **Vencido** cuando la fecha ya pasó). Una alerta está `open` hasta que la condición desaparece, y luego `resolved`. Consulta [Reposición y alertas](/docs/es/inventory/replenishment-and-alerts).

## Permisos y acceso a sedes y bodegas

El acceso de una persona en una clínica dental tiene tres partes.

**1. Rol** (`roleTemplate`): una plantilla.

| Rol | Etiqueta en la consola | Incluye |
| - | - | - |
| `owner` | **Propietario** | `catalog.read`, `catalog.manage`, `members.manage`, `settings.manage`. Solo un propietario puede cambiar roles, invitar administradores y transferir la propiedad. Una clínica dental siempre conserva un propietario activo. |
| `admin` | **Administrador** | `catalog.read`, `catalog.manage`, `members.manage`, `settings.manage` |
| `member` | **Miembro** | `catalog.read` |

**2. Permisos** (`scopes`): todo lo demás se otorga uno por uno, a cualquier rol. `inventory.adjust` incluye además `inventory.receive`, `inventory.consume` e `inventory.transfer`.

| Familia | Permisos | Grupo en la consola |
| - | - | - |
| Catálogo | `catalog.read`, `catalog.manage`, `catalog.cost.read` | **Catálogo** |
| Inventario | `inventory.read`, `inventory.receive`, `inventory.consume`, `inventory.transfer`, `inventory.adjust` | **Inventario** |
| Pedidos | `orders.create`, `orders.read.all`, `orders.value.read`, `orders.clinical.create`, `orders.patient_ref.read` | **Pedidos** |
| Aprobaciones | `approvals.policy.manage`, `approvals.decide` | **Aprobaciones** |
| Abastecimiento | `fulfillment.pick`, `fulfillment.dispatch`, `delivery.confirm`, `receipt.confirm`, `fulfillment.close`, `fulfillment.read` | **Abastecimiento** |
| Reportes y auditoría | `reports.read`, `audit.read` | **Reportes y auditoría** |
| Administración | `members.manage`, `settings.manage`, `integrations.manage` | **Administración** |

`audit.read` e `integrations.manage` se pueden otorgar, pero ninguna pantalla de la consola los usa por ahora.

**3. Acceso a sedes y bodegas**: **Acceso a sedes** (`clinicScopeMode`, `clinicIds`) y **Acceso a bodegas** (`warehouseScopeMode`, `warehouseIds`), cada uno con todas (incluidas las que se creen después), una lista seleccionada o ninguna. El acceso a sedes limita los pedidos, aprobaciones y entregas que ve una persona; el acceso a bodegas limita las existencias que ve y mueve. El propietario fundador empieza con acceso a todo. Nadie puede cambiar su propio acceso a sedes y bodegas, y una invitación siempre otorga al menos una sede.

La consola oculta lo que no puedes usar, pero el servidor revisa cada solicitud por su cuenta. Consulta [Roles y permisos](/docs/es/account/roles-and-permissions).

## Omisión de datos en el servidor

Algunos campos los omite el servidor cuando quien consulta no tiene el permiso. No aparecen en la respuesta (no se muestran vacíos), así que ninguna pantalla, exportación o integración puede revelarlos.

| Campo | Dónde aparece | Permiso que lo muestra |
| - | - | - |
| Costo y moneda del insumo (`cost`, `currency`) | Catálogo, exportación CSV | `catalog.cost.read` |
| Copia del costo en cada línea del pedido | Detalle del pedido | `catalog.cost.read` |
| Valor del pedido y su moneda, y el valor que evaluó la política de aprobación | Pedidos, detalle del pedido, bandeja de aprobaciones | `orders.value.read` |
| Referencia del paciente de un pedido clínico (`patientRef`) | Detalle del pedido | `orders.patient_ref.read` |
| Referencia de atención de un consumo (`careRef`) | **Uso por box o área** | `orders.patient_ref.read` |

La API pública nunca devuelve valores de pedidos ni referencias de pacientes. La referencia del paciente se guarda cifrada y nunca se envía a la IA, y los mensajes de WhatsApp nunca muestran costos, valores de pedidos ni referencias de pacientes. Consulta [Seguridad y privacidad](/docs/es/trust/security-and-privacy).

## Auditoría

Además del registro de movimientos y de los registros inmutables de decisiones, entregas, recepciones y cierres, muveya escribe registros de auditoría para acciones sensibles y rechazos, por ejemplo decisiones de aprobación, un intento rechazado de aprobar el propio pedido, aprobaciones automáticas, correcciones de existencias, pasos de custodia e importaciones de catálogo rechazadas. Los registros de auditoría nunca se editan. Por ahora no hay pantalla ni API que los busque; usa los **Movimientos** de una caja y el **Historial** de un pedido para seguir lo que pasó.

## Idiomas, zonas horarias y moneda

* **Idiomas.** La consola, los mensajes del servidor y los correos de invitación están en inglés (`en`), español (`es`) y portugués (`pt`). Elige con **Idioma** en la barra lateral, en el encabezado de la vista para teléfono o en las pantallas de inicio de sesión. Tu navegador recuerda la elección; la primera vez, la consola sigue el idioma de tu navegador y, si no puede, usa inglés. Los códigos, estados y nombres de permisos quedan en inglés en todos los idiomas.
* **Zonas horarias.** muveya guarda cada hora en UTC. La mayoría de las pantallas muestran fechas y horas en la zona horaria de tu dispositivo. El reporte de consumo agrupa días y semanas en UTC, y los resultados de analítica declaran `timezone` como `UTC`. No hay una configuración de zona horaria por clínica dental.
* **Moneda.** No hay una configuración de moneda por clínica dental. Cada costo de insumo lleva su propio código ISO 4217 (tres letras mayúsculas, como `USD` o `CLP`) y un monto en unidades menores enteras: `1200` equivale a USD 12,00 o CLP 1200. El valor de un pedido solo suma las líneas en la misma moneda que su primera línea con costo, así que mantén tu catálogo en una sola moneda.

## Páginas relacionadas

* [Inicio rápido](/docs/es/quickstart)
* [Glosario](/docs/es/glossary)
* [Roles y permisos](/docs/es/account/roles-and-permissions)
* [Resumen del inventario](/docs/es/inventory/overview)
* [Resumen de entregas](/docs/es/deliveries/overview)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.