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

# Rooms and areas

> Set up the treatment rooms and areas of each location, decide whether they count their own stock, and record where supplies were used.

**Rooms and areas** are the places inside a location where supplies are used: a treatment room, a
sterilization area, a reception desk. When stock leaves a box, the person recording it says which
room or area it went to, and the **Usage by room** report adds it up. The API and the technical
references call them `destinations`.

A room or area:

* belongs to exactly one location;
* has a **Type**: **Treatment room** or **Area**. The type is descriptive only; both behave the same;
* has a **Stock control**: **Not counted** or **Counted stock**. This is the setting that changes
  behavior;
* is **Active** or **Inactive**.

## Not counted or counted stock

| | **Not counted** (`uncounted`) | **Counted stock** (`controlled`) |
| - | - | - |
| What the console explains | **Deliveries leave inventory; what stays in the room is not counted.** | **The room keeps stock of its own that is counted.** |
| Stock point | None. The list shows a dash. | One express warehouse of the same location, shown in **Stock point**. |
| Handing supplies to the room | Recorded as one exit, **Delivered to the room** (`issue`). The units leave inventory once. | Not allowed as an exit. Move the whole box to the room's stock point first. |
| Using supplies in the room | Recorded as **Used directly** (`use`) from any box the room can take. | Recorded as a direct use from boxes that are at the room's stock point. |
| Counts, minimums and alerts | Nothing is counted in the room. | The stock point is a normal warehouse: it can be counted, have minimums and raise alerts. |

Choose **Counted stock** only for rooms where someone will actually count what is kept there.
For everything else, **Not counted** is simpler: supplies leave inventory when they are handed over.

## Who can do it

| Action | Permission |
| - | - |
| See a location's rooms and areas | Every active member of the account |
| Create, activate or deactivate a room or area | Owners and admins, or `settings.manage` (**Manage clinic configuration**) |
| Choose a room or area when stock leaves a box | `inventory.consume` (**Record usage**) or `inventory.adjust`, plus access to the box's warehouse |
| Move a box to a counted room | `inventory.transfer` (**Move boxes between warehouses**) or `inventory.adjust`, plus access to both warehouses |
| Open **Usage by room** | `inventory.read` (**View inventory**). Only exits from warehouses in your access are shown. |
| Attribute an exit later | `inventory.consume` or `inventory.adjust`, plus access to the warehouse the stock left |
| See care references in **Usage by room** | `orders.patient_ref.read` (**View external patient references**) |

See [Roles and permissions](/docs/en/account/roles-and-permissions).

## Where

* To set them up: **Locations**, open a location, section **Rooms and areas**
  (`console.muveya.com/clinics/` followed by the location id).
* To use them: the box page in **Inventory**. See [Use and move stock](/docs/en/inventory/use-and-moves).
* To read the report: **Inventory**, link **Usage by room** (`console.muveya.com/inventory/usage`).

## The Rooms and areas section

The section explains **Where supplies are used at this location. Recording an exit asks for one of
these.** Rooms are listed by name.

| Column | What it shows |
| - | - |
| **Name** | The room or area name. |
| **Type** | **Treatment room** or **Area**. |
| **Stock control** | **Not counted** or **Counted stock**. |
| **Stock point** | For a counted room, the name of its express warehouse, or **Warehouse unavailable** if it cannot be shown. A dash for a room that is not counted. |
| **Status** | **Active** or **Inactive**. |
| **Actions** | Managers only: **Activate** or **Deactivate**. |

When the location has none, the section says **No rooms or areas yet**, followed by **Add the
treatment rooms and areas where this location uses supplies.** for managers or **Ask your clinic
administrator to add rooms and areas.** for everyone else.

## Create a room or area

<Steps>
  <Step title="Open the location">
    In **Locations**, select the location. Scroll to **Rooms and areas**.
  </Step>

  <Step title="Open the form">
    Select **New room or area**. A dialog with the same title opens.
  </Step>

  <Step title="Name it and choose the type">
    Type the **Name**, for example `Room 2` or `Sterilization`. In **Type**, choose
    **Treatment room** (the default) or **Area**.
  </Step>

  <Step title="Choose the stock control">
    In **Stock control**, keep **Not counted** (the default) or choose **Counted stock**. The text
    under the field explains the choice.
  </Step>

  <Step title="Choose the stock point (counted rooms only)">
    With **Counted stock**, a **Stock point** field appears: **The express warehouse of this location
    that holds the room's stock.** Keep **Create automatically** or pick one of the listed
    warehouses.
  </Step>

  <Step title="Save">
    Select **Save room or area**. The room appears in the list as **Active**.
  </Step>
</Steps>

### Fields and rules

| Field | Required | Rules |
| - | - | - |
| **Name** | Yes | 1 to 120 characters, spaces at the start and end removed. Must be unique within the location, counting inactive rooms too. The comparison is exact, so `Room 2` and `room 2` are different names. |
| **Type** | Yes | **Treatment room** (`treatment_room`) or **Area** (`area`). |
| **Stock control** | Yes | **Not counted** (`uncounted`) or **Counted stock** (`controlled`). |
| **Stock point** | Counted rooms only | **Create automatically**, or an active express warehouse of this location that no other room uses. A room that is not counted never has one. |

About the stock point:

* **Create automatically** creates a new express warehouse of this location, named like the room,
  in the same step as the room. If either one fails, neither is created. The new warehouse appears in
  **Warehouses**.
* The list of existing warehouses only shows active express warehouses of this location that are not
  already the stock point of another room, including inactive rooms.
* A warehouse is the stock point of at most one room.

<Warning>
  After a room is created, its name, type, stock control and stock point cannot be changed, and it
  cannot be deleted. To correct one, deactivate it and create a new room with a different name: the
  old name stays taken by the inactive room.
</Warning>

<Tip>
  Members whose **Warehouse access** lists specific warehouses do not get a new stock point
  automatically. Add it to their access in **Team**, or they cannot move boxes to the room or use
  its stock. See [Team](/docs/en/account/team).
</Tip>

## Statuses

| Status | Label | Meaning |
| - | - | - |
| `active` | **Active** | The room can be chosen when stock leaves a box. |
| `inactive` | **Inactive** | The room is kept and still named in history, but it can no longer be chosen. |

To change it, select **Deactivate** or **Activate** in the room's row. The change applies
immediately and can be reversed.

What deactivating a room does:

* It is no longer offered when recording an exit. An exit that still names it is refused with **That
  room or area is no longer active. Choose another one.**
* Past exits keep its name, and **Usage by room** still lists it in its filter.
* For a counted room, its stock point warehouse is not deactivated and stays tied to the room: it
  cannot become the stock point of another room. Consumptions recorded at that warehouse are no
  longer labeled with the room automatically. Deactivate the warehouse separately in
  **Warehouses** if it should stop taking stock.

## How rooms and areas are used when stock leaves a box

The full task is described in [Use and move stock](/docs/en/inventory/use-and-moves). What rooms and areas
change in it:

<Steps>
  <Step title="Which rooms are offered">
    On a box in a **central** warehouse, **Room or area** offers the active rooms of every location.
    On a box in an **express** warehouse, only the active rooms of that warehouse's location. When
    the account has more than one location, each room shows its location after its name, for example
    `Room 2 · Clínica Norte`. If only one room is possible, it is shown without a choice.
  </Step>

  <Step title="No rooms yet">
    If the location has no active room, the form says **No rooms or areas are set up for this
    location yet, so this consumption will not say where it went.** The consumption can still be
    recorded, but it will not appear in **Usage by room**. Managers also see the link **Set up rooms
    and areas**.
  </Step>

  <Step title="A room that is not counted">
    Choose **What happened**: **Delivered to the room** (the default, **It leaves inventory once; who
    used it can be attributed later without discounting again.**) or **Used directly** (**It was used
    right away.**).
  </Step>

  <Step title="A counted room">
    If the box is already at the room's stock point, the form says **Used from this room’s own counted
    stock.** and the exit is recorded as a direct use. If the box is elsewhere, the form says, for
    example, **Room 2 counts its own stock. Move the whole box there first; taking out part of a box
    comes later.** Members who can move boxes see **Move this box to Room 2**; others read **Ask
    someone who can move boxes to take this box to Room 2.**
  </Step>

  <Step title="Attribution">
    Fill in **Purpose**, **Responsible** and, optionally, **Care reference (optional)** (see the next
    section), then select **Consume**.
  </Step>
</Steps>

<Info>
  Any consumption recorded without a room, from any channel (for example WhatsApp), on a box that sits
  at the stock point of an active counted room is automatically recorded as a direct use in that room.
</Info>

### Rules the system enforces

* The room must be active (`inventory.destination_not_found`).
* A box in an express warehouse can only go to a room of the same location. A box in a central
  warehouse can go to any location's room (`inventory.destination_mismatch`).
* A counted room refuses **Delivered to the room** (`inventory.destination_requires_transfer`) and
  accepts a direct use only from its own stock point (`inventory.destination_mismatch`).
* If the box was moved to another warehouse while you were recording, the exit is refused rather
  than attributed to the wrong place (`inventory.destination_mismatch`).
* The quantity must be a whole number greater than zero.

## Attribution fields

| Field | Values | Notes |
| - | - | - |
| **Purpose** | **Not specified**, **Procedure** (`procedure`), **Cleaning** (`cleaning`), **Administrative** (`administrative`), **Other** (`other`) | Optional. A closed list, so reports never depend on free text. |
| **Responsible** | An active member of the team | Defaults to you. If you choose someone else, the form says, for example, **Recorded by you, responsible: Dra. Pérez.** |
| **Care reference (optional)** | The code from the external clinical system | **The code from the clinical system, never the patient’s name.** 1 to 64 characters: it starts with a letter or digit and then uses only letters, digits and `.` `_` `:` `/` `-`, with no spaces. Example: `ext-7f3a`. |
| Recorded by | You | Stored automatically. It is a different field from **Responsible**. |

The care reference is stored sealed. It never appears on the box page or in movement lists; it is
shown only in **Usage by room**, and only to members with `orders.patient_ref.read`.

<Warning>
  Never type a patient's name, national ID or any direct identifier as a care reference. The format
  blocks names with spaces, but it cannot recognize every identifier.
</Warning>

## The Usage by room report

**Inventory**, **Usage by room** shows **What left stock toward each room or area, and how much of it
is already attributed.**

Filters:

| Filter | Default | Rules |
| - | - | - |
| **Room or area** | **All rooms and areas** | Lists every room, active or not. |
| **From** and **To** | The last 7 days, including today | Whole calendar days in your time zone. **From** must be on or before **To**, at most 92 days apart; otherwise the screen says **Choose a start date on or before the end date, at most 92 days apart.** |

**Totals** has one row per room, supply and unit (units are never added across different units):

| Column | Meaning |
| - | - |
| **Room or area** | The room. |
| **Supply** | The supply name and code. |
| **Unit** | The unit the quantities are in. |
| **Delivered** | Quantity handed to rooms that are not counted. |
| **Used directly** | Quantity recorded as direct use. |
| **Attributed** | How much of those exits was attributed later. |

**Exits** lists each exit: **When**, **Supply**, **Quantity**, **Unit**, **Room or area**, **What
happened**, **Purpose**, **Responsible**, **Recorded by**, **Pending** (quantity not yet
attributed) and, when you may see it, **Care reference**. A button **Attributions (3)** expands the
later attributions of an exit, each with **When**, **Quantity**, **Responsible**, **Purpose**,
**Recorded by** and, when allowed, **Care reference**.

* Only exits recorded with a room or area appear. Otherwise the screen says **No exits with a room or
  area in these dates.** and **Only consumptions recorded with a room or area appear here.**
* A read covers at most 2,000 exits. Beyond that, the screen says **This is a partial view. Narrow
  the dates to see every exit.** and the totals are incomplete.
* A person who is no longer on the team is shown as **Not on the team**.

### Attribute an exit later

Use this when supplies were handed to a room and you learn later who used them and for what.

<Steps>
  <Step title="Find the exit">
    In **Usage by room**, find the exit. **Attribute** appears when you can record usage and the exit
    still has a **Pending** quantity.
  </Step>

  <Step title="Fill in the attribution">
    Set **Quantity to attribute** (it starts at the pending quantity), **Responsible**, **Purpose** and,
    optionally, **Care reference (optional)**.
  </Step>

  <Step title="Save">
    Select **Save attribution**. The screen confirms **Attribution recorded.** and the pending quantity
    goes down. Select **Close** when you are done.
  </Step>
</Steps>

Rules:

* The quantity is a whole number greater than zero, and the total attributed can never exceed the
  exit. More than what is pending is refused with **That is more than is still pending for this
  exit.**
* Any exit recorded with a room can be attributed, whether it was delivered or used directly.
* An exit accepts at most 500 attributions.
* Saving the same attribution twice (for example a double tap) is recorded once; the screen says
  **Already recorded.**
* An attribution cannot be edited or removed.

## What the system records

* **The room or area**: its location, name, type, stock control, stock point and status. Changing
  the status updates that record. No audit entry is written for these changes.
* **Each exit**: one `consume` movement in the stock ledger, which removes the quantity from the box
  once. It stores the room (`destinationId`), what happened (`usage`: `issue` or `use`), the purpose,
  the responsible person, who recorded it and the sealed care reference. These fields never change
  afterwards.
* **Each later attribution**: a separate, append-only record linked to the exit. It is never a stock
  movement, so it cannot discount stock a second time.
* **Moving a box to a counted room**: a normal move between warehouses; the total stock does not
  change.

Rooms and areas are not part of the public API or MCP today.

## What can go wrong

When setting up rooms and areas:

| Message | Why | What to do |
| - | - | - |
| **Enter a value.** | **Name** is empty. | Type a name. |
| **This value is too long.** | The name has more than 120 characters. | Shorten it. |
| **This location already has a room or area with that name.** | The name is already used in this location, possibly by an inactive room (`destinations.name_taken`). | Choose another name. |
| **Choose an active express warehouse of this location that no other room uses.** | The chosen stock point is inactive, central, from another location, or already used by another room (`destinations.warehouse_invalid`). | Choose another warehouse, or keep **Create automatically**. |
| **This record is not available in the active dental clinic account.** | The location or the room does not exist in this account (`clinics.not_found`, `destinations.not_found`). | Reload the location from **Locations**. |
| **Your account does not have permission for this action.** | You do not have `settings.manage` (`tenants.insufficient_role`). | Ask an owner or admin. |
| **Review the entered values before trying again.** | The data was refused (`common.invalid_request`). | Check the fields and retry. |

When recording an exit or an attribution:

| Message | Why | What to do |
| - | - | - |
| **This room counts its own stock. Move the box there first.** | You tried to deliver to a counted room (`inventory.destination_requires_transfer`). | Move the whole box to the room, then record the use. |
| **This box belongs to another location than the chosen room or area. Check where the box is.** | The box and the room are in different locations, the box is not at the counted room's stock point, or it was moved meanwhile (`inventory.destination_mismatch`). | Reload the box and choose a room of its location. |
| **That room or area is no longer active. Choose another one.** | The room was deactivated (`inventory.destination_not_found`). | Choose another room. |
| **The responsible person is no longer on the team. Choose someone else.** | The chosen responsible is not an active member (`inventory.responsible_not_member`). | Choose another person. |
| **Use letters, digits and . \_ : / - without spaces.** | The care reference has a space or a character that is not allowed. | Fix it, or leave it empty. |
| **Use the code from the clinical system, without spaces.** | muveya refused the care reference (`inventory.care_ref_invalid`). | Use the external system's code. |
| **That is more than is still pending for this exit.** | The attribution exceeds what is pending (`inventory.attribution_exceeds_exit`). | Lower the quantity. |
| **The record changed or already exists. Review it before trying again.** | The exit cannot take more attributions, or a retried action did not match the original (`inventory.exit_not_attributable`, `inventory.idempotency_key_conflict`). | Reload **Usage by room** and review the exit. |
| **This record is not available in the active dental clinic account.** | The exit is from a warehouse outside your access (`inventory.movement_not_found`). | Ask an administrator for access to that warehouse. |

## Related pages

<CardGroup cols={2}>
  <Card title="Use and move stock" icon="right-left" href="/docs/en/inventory/use-and-moves">
    Record consumption, choose the room and move boxes.
  </Card>

  <Card title="Locations" icon="location-dot" href="/docs/en/locations/clinics">
    The sites rooms and areas belong to.
  </Card>

  <Card title="Warehouses" icon="warehouse" href="/docs/en/locations/warehouses">
    Express warehouses that act as stock points.
  </Card>

  <Card title="Roles and permissions" icon="user-shield" href="/docs/en/account/roles-and-permissions">
    Who can set up rooms, record usage and see care references.
  </Card>
</CardGroup>


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