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

# Depósitos

> Crie depósitos centrais e express, ative ou desative esses depósitos e entenda como pedidos, estoque e entregas os usam.

Um **depósito** é um lugar onde os insumos são guardados e contados. Cada caixa de estoque fica em
exatamente um depósito, cada pedido é entregue em um depósito e cada movimento de estoque indica de
qual depósito saiu ou a qual chegou. A API também o chama de `warehouse`.

## Depósitos centrais e express

| Tipo | Rótulo | Pertence a | Uso comum |
| - | - | - | - |
| `central` | **Central** | Nenhuma unidade. Atende toda a conta de clínica odontológica. | O depósito principal ou centro de distribuição que abastece todas as unidades. |
| `express` | **Express** | Exatamente uma unidade. | O estoque mantido em uma unidade, incluindo o ponto de estoque de uma sala contada. |

A regra de pertencimento é rígida:

* Um depósito express sempre pertence a uma unidade, escolhida na criação.
* Um depósito central nunca pertence a uma unidade.
* O tipo e a unidade de um depósito não podem ser alterados depois da criação.

```mermaid theme={null}
flowchart LR
  C["Depósito central"] -->|abastece| E1["Depósito express da Clínica Norte"]
  C -->|abastece| E2["Depósito express da Clínica Sul"]
  E1 --- L1["Unidade: Clínica Norte"]
  E2 --- L2["Unidade: Clínica Sul"]
```

## Quem pode fazer

| Ação | Quem |
| - | - |
| Abrir **Depósitos** | Todas as pessoas ativas da conta |
| Criar um depósito | Proprietários e administradores, ou pessoas com `settings.manage` |
| Ativar ou desativar um depósito | Proprietários e administradores, ou pessoas com `settings.manage` |
| Ver e movimentar o estoque de um depósito | Pessoas com as permissões de estoque e acesso a esse depósito. Veja [Registrar consumo e transferir caixas](/docs/pt/inventory/use-and-moves). |
| Definir em quais depósitos uma pessoa trabalha | Proprietários e administradores, ou pessoas com `members.manage` (em **Equipe**) |

Em **Equipe**, `settings.manage` aparece como **Gerenciar configuração da clínica**. Quem não tem essa
permissão vê a lista somente para leitura: sem o botão **Novo depósito** e sem a coluna **Ações**.
Veja [Funções e permissões](/docs/pt/account/roles-and-permissions).

## Onde

Navegação principal, **Depósitos** (`console.muveya.com/warehouses`).

## A lista de depósitos

A lista mostra todos os depósitos da conta, na ordem em que foram criados.

| Coluna | O que mostra |
| - | - |
| **Nome do depósito** | O nome. |
| **Tipo de depósito** | **Central** ou **Express**. |
| **Unidade** | **Todas as unidades** para um depósito central. Para um depósito express, o nome da unidade dele, ou **Unidade indisponível** se essa unidade não puder ser mostrada. |
| **Status** | **Ativa** ou **Inativa**. |
| **Ações** | Só para quem administra: **Ativar** ou **Desativar**. |

**Buscar depósitos** filtra pelo nome do depósito, sem diferenciar maiúsculas, minúsculas nem
acentos.

Estados vazios:

* Sem depósitos: **Ainda não há depósitos**. Quem administra lê **Crie um depósito central ou vincule
  um depósito express a uma unidade.**; as demais pessoas leem **Peça a quem administra sua clínica
  para adicionar um depósito.**
* Uma busca sem resultado: **Nenhum resultado encontrado** e **Tente outra busca.**

<Note>
  Esta lista não é filtrada pelo acesso aos depósitos: todas as pessoas veem todos os depósitos aqui. O
  acesso aos depósitos define o estoque que cada pessoa pode ver e movimentar em **Inventário**, não o
  que esta lista mostra.
</Note>

## Criar um depósito

<Steps>
  <Step title="Abra o formulário">
    Em **Depósitos**, selecione **Novo depósito**. Uma caixa de diálogo com o título **Novo depósito**
    se abre.
  </Step>

  <Step title="Dê um nome">
    Digite o **Nome do depósito**, por exemplo `Depósito Central São Paulo` ou `Estoque Clínica Norte`.
  </Step>

  <Step title="Escolha o tipo">
    Em **Tipo de depósito**, escolha **Central** (a opção padrão) ou **Express**.
  </Step>

  <Step title="Escolha a unidade (só express)">
    Se você escolheu **Express**, aparece o campo **Unidade**. Abra **Escolha uma unidade** e selecione
    a unidade à qual o depósito pertence. Só unidades ativas são oferecidas.
  </Step>

  <Step title="Salve">
    Selecione **Salvar depósito**. Ao terminar, a caixa de diálogo se fecha e o depósito aparece na
    lista como **Ativa**.
  </Step>
</Steps>

Selecione **Cancelar** para fechar sem criar nada.

### Campos e regras

| Campo | Obrigatório | Regras |
| - | - | - |
| **Nome do depósito** | Sim | De 1 a 120 caracteres. Os espaços no início e no fim são removidos. Não há verificação de nome único. |
| **Tipo de depósito** | Sim | **Central** ou **Express**. Não pode ser alterado depois. |
| **Unidade** | Só para **Express** | Uma unidade ativa desta conta. Não pode ser alterada depois. Um depósito central nunca tem unidade. |

* Se a conta não tem nenhuma unidade ativa, o formulário mostra **Crie uma unidade ativa antes de
  adicionar um depósito express.** Primeiro crie ou ative uma unidade. Veja
  [Unidades](/docs/pt/locations/clinics).
* Um depósito novo sempre começa como **Ativa**.
* Não é possível renomear, mudar o tipo ou a unidade, nem excluir. Se um depósito foi criado errado,
  crie o correto, transfira as caixas para ele (veja
  [Registrar consumo e transferir caixas](/docs/pt/inventory/use-and-moves)) e desative o antigo.

### Depósitos criados para você

* **Primeira configuração a partir do Início.** O cartão **Crie a primeira unidade** cria uma unidade
  e depois abre **Novo depósito** com o nome **Depósito principal** já preenchido. Se a conta já tem
  uma unidade, mas nenhum depósito, o cartão **Crie um depósito** abre a mesma caixa de diálogo com o
  mesmo nome. Veja [Unidades](/docs/pt/locations/clinics).
* **Ponto de estoque de uma sala contada.** Quando você cria uma sala ou área com **Estoque contado** e
  mantém **Criar automaticamente**, o muveya cria um depósito express dessa unidade com o mesmo nome
  da sala. Ele aparece nesta lista como qualquer outro depósito express. Veja
  [Salas e áreas](/docs/pt/locations/destinations).

## Status

| Status | Rótulo | Significado |
| - | - | - |
| `active` | **Ativa** | O depósito pode receber estoque novo e pedidos novos. |
| `inactive` | **Inativa** | O depósito e o histórico dele são mantidos, mas ele não recebe estoque novo nem pedidos novos. |

Para mudar, selecione **Desativar** ou **Ativar** na linha do depósito. A mudança vale na hora, pode
ser desfeita e não tem etapa de confirmação.

### O que acontece ao desativar um depósito

| Área | Efeito |
| - | - |
| Recebimento de estoque | O depósito deixa de ser oferecido no recebimento. Se uma tela desatualizada ainda o enviar, a operação é recusada (`inventory.warehouse_inactive`) e nada é registrado. |
| Transferência de caixas para ele | Deixa de ser oferecido como destino de transferência, e uma transferência para ele é recusada da mesma forma. |
| Caixas que já estão nele | Continuam onde estão, com as quantidades. Ainda podem ser consumidas ou transferidas para um depósito ativo. |
| Pedidos novos | Deixa de aparecer em **Entregar no depósito** e em **Retirar estoque de**. Se uma tela desatualizada ainda o enviar, o pedido é recusado com **Esse depósito não está ativo.** |
| Pedidos já criados | Nada é verificado de novo. Eles seguem, e um recebimento confirmado ainda credita este depósito. |
| Filtros de estoque e histórico | O depósito continua aparecendo nos filtros de estoque e em cada movimento que o menciona. |
| Sala contada | Se ele é o ponto de estoque de uma sala, a sala continua apontando para ele e não é mais possível levar caixas para essa sala. Considere desativar a sala também. |

Desativar um depósito nunca movimenta, remove nem ajusta estoque e não grava nada no registro de
movimentos.

## Como os depósitos são usados

### Pedidos

Ao criar um pedido (veja [Criar e acompanhar pedidos](/docs/pt/orders/create-and-track)):

* **Entregar no depósito** lista os depósitos express ativos da unidade escolhida em **Clínica**,
  limitados aos depósitos do seu acesso. Se a unidade não tem nenhum, a tela diz **Esta clínica ainda
  não tem um depósito ativo. Crie um em Depósitos primeiro.** Se tem, mas nenhum está no seu acesso,
  diz **Você não tem nenhum depósito desta clínica atribuído. Peça acesso a um administrador.**
* **Retirar estoque de** oferece **Qualquer depósito central** ou um depósito central ativo específico.

<Note>
  Com **Qualquer depósito central**, o pedido não indica depósito de origem. Ao reservar estoque para
  ele, o muveya procura caixas utilizáveis de cada insumo sem limitar a busca a um depósito, então as
  caixas podem vir de qualquer depósito que tenha esse insumo, não só dos centrais. Escolha um depósito
  central específico quando o estoque precisar sair dele.
</Note>

### Estoque

* Cada caixa pertence a um depósito. A lista de estoque pode ser filtrada por **Depósito**.
* O recebimento coloca as caixas novas em um depósito ativo ao qual você tem acesso. Veja
  [Receber estoque](/docs/pt/inventory/receive).
* Transferir uma caixa muda o depósito dela e registra a transferência no registro de movimentos. Veja
  [Registrar consumo e transferir caixas](/docs/pt/inventory/use-and-moves).
* O estoque mínimo e a reposição são definidos por insumo e depósito. Veja
  [Reposição e alertas de estoque](/docs/pt/inventory/replenishment-and-alerts).
* As contagens são feitas por depósito. Veja [Contagens físicas](/docs/pt/inventory/counts).
* Quando sai estoque de uma caixa para uma sala ou área, o depósito da caixa define quais salas podem
  ser escolhidas: a partir de um depósito central, as salas de todas as unidades; a partir de um
  depósito express, só as salas da própria unidade. Veja [Salas e áreas](/docs/pt/locations/destinations).

### Entregas

As caixas reservadas para um pedido são separadas e despachadas a partir do depósito em que estão.
Quando o recebimento é confirmado, as caixas aceitas são creditadas no depósito de destino do pedido e
as caixas contestadas voltam ao depósito de onde saíram. Veja
[Entregas: visão geral](/docs/pt/deliveries/overview) e
[Entrega e recebimento](/docs/pt/deliveries/delivery-and-receipt).

## Como o acesso aos depósitos restringe o que cada pessoa vê

Cada pessoa tem **Acesso aos depósitos**: **Todos os depósitos desta conta** (inclui os criados
depois), **Depósitos selecionados** ou **Nenhum depósito**. Ele é gerenciado em **Equipe**; veja
[Equipe](/docs/pt/account/team).

| Com acesso a um depósito, a pessoa pode | Sem acesso |
| - | - |
| Ver as caixas e os saldos dele em **Inventário** | As caixas ficam ocultas e se comportam como se não existissem |
| Receber nele, transferir caixas para ele ou a partir dele, consumir a partir dele (com a permissão correspondente) | Essas ações são recusadas |
| Escolhê-lo em **Entregar no depósito** ao criar um pedido | Ele não é oferecido |
| Ver o uso registrado a partir dele em **Uso por sala ou área** | Essas saídas não aparecem |

Uma pessoa com **Nenhum depósito** lê **Você não tem depósitos atribuídos. Peça acesso a um
administrador.** em **Inventário**.

<Tip>
  Quando o acesso de uma pessoa lista depósitos específicos, os depósitos novos não são adicionados
  automaticamente. Isso inclui o ponto de estoque que o muveya cria para uma sala contada. Abra a pessoa
  em **Equipe** e adicione o depósito novo; caso contrário, ela não conseguirá levar caixas para ele nem
  consumir a partir dele.
</Tip>

## O que o sistema registra

* Criar um depósito grava o nome, o tipo, a unidade (só express) e o status `active`. Mudar o status
  atualiza esse mesmo registro.
* Essas mudanças nunca gravam movimentos de estoque e não geram um registro de auditoria separado.
* Os depósitos nunca são excluídos, então os movimentos e as caixas que mencionam um continuam
  apontando para ele.

## Pela API e pelo MCP

* A API pública lista os depósitos com `GET /v1/warehouses` (escopo `clinics:read`). Cada item traz
  `warehouseId`, `name`, `kind`, `status` e, só nos depósitos express, `clinicId`. A API não cria nem
  altera depósitos. Veja [Escopos](/docs/pt/api-reference/scopes).
* A ferramenta MCP `clinics.list` lista unidades e depósitos. Veja [Ferramentas MCP](/docs/pt/mcp/tools).

## O que pode dar errado

| Mensagem | Por quê | O que fazer |
| - | - | - |
| **Informe um valor.** | **Nome do depósito** está vazio ou só tem espaços. | Digite um nome. |
| **Este valor é muito longo.** | O nome tem mais de 120 caracteres. | Encurte o nome. |
| **Escolha uma unidade ativa.** | Você escolheu **Express** sem unidade. | Escolha uma unidade em **Unidade**. |
| **Crie uma unidade ativa antes de adicionar um depósito express.** | A conta não tem nenhuma unidade ativa. | Crie ou ative uma unidade em **Unidades**. |
| **Confira os dados informados antes de tentar novamente.** | O muveya recusou os dados (`common.invalid_request`), ou a unidade escolhida não existe mais nesta conta (`warehouses.clinic_required`). | Abra o formulário de novo, escolha a unidade outra vez e tente de novo. |
| **Sua conta não tem permissão para esta ação.** | Você não é proprietário nem administrador e não tem `settings.manage` (`tenants.insufficient_role`). | Peça a um proprietário ou administrador. |
| **Este registro não está disponível na conta de clínica odontológica ativa.** | O depósito não existe na conta em que você está trabalhando (`warehouses.not_found`). | Confira qual **Clínica odontológica** está escolhida e recarregue a lista. |
| **O registro mudou ou já existe. Confira antes de tentar novamente.** | Você tentou receber em um depósito, ou transferir uma caixa para ele, e o depósito foi desativado nesse meio-tempo (`inventory.warehouse_inactive`). | Recarregue a tela e escolha um depósito ativo. |
| **Esse depósito não está ativo.** | Um pedido indicou um depósito inativo (`orders.warehouse_unavailable`). A mesma mensagem aparece quando o depósito está fora do seu acesso aos depósitos ou pertence a outra unidade. | Escolha outro depósito, ou peça a um administrador que o ative ou lhe dê acesso. |
| **A conta de clínica odontológica ativa mudou. Recarregue a página antes de tentar novamente.** | Você trocou de conta em outra aba (`tenants.context_changed`). | Recarregue a página. |
| **Não foi possível confirmar a operação. Verifique sua conexão e a lista antes de tentar novamente.** | A conexão caiu antes de o muveya responder. | Confira a lista antes de tentar de novo: a mudança pode já estar salva. |
| **Não foi possível concluir a solicitação. Tente novamente.** | Qualquer outra falha. | Selecione **Tentar de novo**. Se continuar falhando, escreva para [team@muveya.com](mailto:team@muveya.com). |

## Páginas relacionadas

<CardGroup cols={2}>
  <Card title="Unidades" icon="location-dot" href="/docs/pt/locations/clinics">
    As unidades às quais os depósitos express pertencem.
  </Card>

  <Card title="Salas e áreas" icon="door-open" href="/docs/pt/locations/destinations">
    Salas contadas e seus pontos de estoque.
  </Card>

  <Card title="Registrar consumo e transferir caixas" icon="right-left" href="/docs/pt/inventory/use-and-moves">
    Registre consumos e transfira caixas entre depósitos.
  </Card>

  <Card title="Equipe" icon="users" href="/docs/pt/account/team">
    Defina o acesso aos depósitos de cada pessoa.
  </Card>
</CardGroup>


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