> ## 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 do catálogo
> Busque, crie e mantenha os insumos da sua clínica odontológica e entenda os status rascunho, ativo e inativo.
O catálogo é a lista fechada de insumos com que a sua clínica odontológica trabalha. Cada linha de pedido, caixa de estoque e registro de consumo aponta para um insumo desta lista, então um insumo precisa existir aqui antes que alguém possa pedi-lo, recebê-lo ou usá-lo. O console chama cada item do catálogo de *insumo*; a API e o código o chamam de item.
## Quem pode fazer
| Ação | Permissão | Observações |
| - | - | - |
| Ver a lista e abrir um insumo | `catalog.read` | Todas as funções (Proprietário, Administrador, Membro) a incluem. |
| Criar um insumo, editá-lo, ativá-lo ou desativá-lo | `catalog.manage` | Proprietários e Administradores a têm pela função. Um Membro precisa receber **Gerenciar catálogo**. |
| Ver custos na lista e no insumo | `catalog.cost.read` | Nenhuma função a inclui, nem mesmo Proprietário. Ela é concedida como **Ver custos dos materiais**. Veja [Custos](/docs/pt/catalog/costs). |
As permissões são atribuídas a cada pessoa na tela **Equipe**. Veja [Funções e permissões](/docs/pt/account/roles-and-permissions).
## Onde
Abra **Catálogo** na navegação principal. O módulo tem três telas de insumos:
| Tela | Caminho | Para que serve |
| - | - | - |
| **Catálogo** | `/catalog` | Buscar, filtrar e abrir insumos. |
| **Novo insumo** | `/catalog/items/new` | Criar um insumo. |
| Detalhes do insumo | `/catalog/items/:itemId` | Editar um insumo, mudar o status e gerenciar as apresentações e o custo. |
## A lista do catálogo
A tela **Catálogo** (**Organize os insumos utilizados pela sua clínica odontológica.**) mostra:
* **Novo insumo**, no cabeçalho, se você tem `catalog.manage`.
* Uma caixa de busca, **Buscar por SKU ou nome**. Ela encontra qualquer parte do SKU ou do nome, sem diferenciar maiúsculas nem acentos, então `anestesico` encontra "Anestésico local".
* Links para **Categorias** e, se você tem `catalog.manage`, para **Importar CSV** e **Exportar CSV**. Veja [Categorias](/docs/pt/catalog/categories) e [Importar e exportar](/docs/pt/catalog/import-export).
* Dois filtros: **Categoria** (padrão **Todas as categorias**) e **Status** (padrão **Todos os estados**, depois **Rascunho**, **Ativo** e **Inativo**). **Limpar filtros** zera a busca e os dois filtros.
A tabela tem as colunas **SKU**, **Nome do insumo**, **Categoria**, **Unidade** e **Status**, além de **Custo** se você tem `catalog.cost.read`. Clique no nome para abrir o insumo. Os insumos aparecem na ordem em que foram criados, do mais antigo ao mais recente, 50 por página, com **Anterior** e **Próxima** abaixo da tabela e um contador das linhas exibidas sobre o total.
| O que você vê | Significado |
| - | - |
| **Ainda não há insumos** | O catálogo está vazio. Quem gerencia o catálogo lê **Crie uma categoria e adicione o primeiro insumo ao catálogo.**; as demais pessoas leem **Um administrador pode adicionar insumos a este catálogo.** |
| **Nenhum insumo encontrado** | Nada corresponde à busca ou aos filtros. **Tente outra busca.** |
| **Categoria indisponível** | O insumo aponta para uma categoria que a tela não encontrou. Abra o insumo e escolha uma categoria. |
## Criar um insumo
Todo insumo pertence a uma categoria. Se não houver nenhuma, o formulário diz **Crie uma categoria antes de adicionar insumos.** Você pode criá-la em [Categorias](/docs/pt/catalog/categories) ou com **Nova categoria** dentro do formulário, que já a deixa selecionada.
Em **Catálogo**, clique em **Novo insumo**. A página **Novo insumo** abre com o texto **Defina como este insumo é identificado e controlado.**
Em **Informações do insumo**, informe **SKU**, **Nome do insumo**, **Categoria**, **Unidade**, **Apresentação**, **Criticidade** e **Descrição**. As regras de cada campo estão na tabela abaixo.
Em **Requisitos de rastreabilidade** (**Estas opções definem os dados necessários ao registrar o estoque.**), marque **Controlar lotes**, **Controlar números de série**, **Controlar validades** e **Insumo de alto valor** conforme necessário. As quatro opções começam desmarcadas.
Clique em **Criar insumo**. O console abre os detalhes do novo insumo. O insumo nasce como **Rascunho**: ative-o quando estiver pronto para ser pedido.
O formulário de criação não tem campo de custo. Registre o custo nos detalhes do insumo depois de criá-lo, ou inclua-o em uma importação CSV. Veja [Custos](/docs/pt/catalog/costs).
## Campos e validações
| Campo (rótulo no console) | Obrigatório | Regras | Pode mudar depois |
| - | - | - | - |
| `sku` (**SKU**) | Sim | De 1 a 64 caracteres. Apenas letras, dígitos, pontos, sublinhados, barras e hífens, sem espaços. Único na sua clínica odontológica e comparado de forma exata (`GLV-NIT-M` e `glv-nit-m` são códigos diferentes). | Nunca. |
| `name` (**Nome do insumo**) | Sim | Até 200 caracteres, não só espaços. | Sim. |
| `description` (**Descrição**) | Não | Até 2.000 caracteres. | Sim. |
| `categoryId` (**Categoria**) | Sim | Uma categoria da sua própria clínica odontológica. | Sim. |
| `unitOfMeasure` (**Unidade**) | Sim | Uma das unidades de medida abaixo. | Só até a unidade ficar fixa. Veja [A unidade fica fixa](#a-unidade-fica-fixa). |
| `packaging` (**Apresentação**) | Não | Texto livre de até 200 caracteres, por exemplo "Caixa com 100". É apenas descritivo: nunca muda uma quantidade. | Sim. |
| `criticality` (**Criticidade**) | Sim | `low` (**Baixa**), `medium` (**Média**) ou `high` (**Alta**). | Sim. |
| `tracksLot` (**Controlar lotes**) | Não | Desligado por padrão. | Sim. |
| `tracksSerial` (**Controlar números de série**) | Não | Desligado por padrão. | Sim. |
| `tracksExpiry` (**Controlar validades**) | Não | Desligado por padrão. | Sim. |
| `highValue` (**Insumo de alto valor**) | Não | Desligado por padrão. | Sim. |
A **Unidade** é a unidade de medida base em que o insumo é contado em todo lugar: estoque, pedidos, consumo e apresentações. Não confunda com as unidades da clínica (os locais). Os valores permitidos são:
| Código | Rótulo | Código | Rótulo |
| - | - | - | - |
| `unit` | **Unidade** | `liter` | **Litro** |
| `box` | **Caixa** | `gram` | **Grama** |
| `pack` | **Pacote** | `kilogram` | **Quilograma** |
| `bottle` | **Frasco** | `pair` | **Par** |
| `ampoule` | **Ampola** | `kit` | **Kit** |
| `milliliter` | **Mililitro** | | |
O campo de texto livre **Apresentação** do formulário não é o mesmo que a seção **Apresentações** dos detalhes do insumo. Para dizer que uma caixa traz 100 unidades, de modo que receber 3 caixas some 300 unidades, adicione uma apresentação nessa seção. Veja [Apresentações e códigos](/docs/pt/catalog/presentations-and-codes).
### O que as opções de rastreabilidade fazem
| Opção | Efeito |
| - | - |
| **Controlar lotes** | Cada recebimento de estoque do insumo precisa informar um número de lote. |
| **Controlar números de série** | Cada recebimento precisa informar um número de série por unidade recebida, sem repetir, e um número de série já recebido não pode ser recebido de novo. |
| **Controlar validades** | Cada recebimento precisa informar uma data de validade que não esteja no passado. |
| **Insumo de alto valor** | As regras de aprovação de pedidos podem mirar pedidos com insumos de alto valor (**Só pedidos com insumos de alto valor**), e toda correção de estoque do insumo precisa da aprovação de uma segunda pessoa. |
Uma mudança nessas opções vale para os recebimentos registrados depois dela; as caixas já recebidas mantêm o que foi registrado. Veja [Receber estoque](/docs/pt/inventory/receive), [Política de aprovação](/docs/pt/orders/approval-policy) e [Correções de estoque](/docs/pt/inventory/corrections).
A **Criticidade** é salva, exibida no insumo e incluída nas exportações. Na versão atual ela não altera alertas, reposição nem aprovações.
## Status
| Status | Rótulo | Significado |
| - | - | - |
| `draft` | **Rascunho** | Todo insumo novo começa aqui, seja criado no formulário ou por importação CSV. Não pode ser adicionado a pedidos. |
| `active` | **Ativo** | O insumo pode ser adicionado a novos pedidos e aparece quando alguém escolhe um insumo pelo nome na tela de recebimento. |
| `inactive` | **Inativo** | Uma desativação sem exclusão. O insumo, as caixas e o histórico continuam; ele não pode ser adicionado a novos pedidos. |
```mermaid theme={null}
stateDiagram-v2
[*] --> draft: Criar insumo
draft --> active: Ativar
active --> inactive: Desativar
inactive --> active: Ativar
```
Não há como voltar para `draft`, e insumos não podem ser excluídos. Desative os insumos que você não usa mais.
### Por que só insumos ativos podem ser pedidos
Quando alguém adiciona um insumo a um pedido, o muveya copia para a linha o SKU, o nome, a unidade, a categoria, a marca de alto valor e o custo vigente do insumo. Essa cópia só faz sentido se a unidade for definitiva, por isso a tela de pedidos oferece apenas insumos ativos e o servidor recusa qualquer outro com `orders.catalog_item_unavailable`: **Este insumo não está ativo no catálogo.** As linhas já adicionadas mantêm a cópia mesmo que depois o insumo seja desativado ou editado. Veja [Criar e acompanhar pedidos](/docs/pt/orders/create-and-track).
## Os detalhes do insumo
Abra um insumo a partir da lista. O título da página é o nome do insumo, com **Voltar ao catálogo** acima.
* **Se você tem `catalog.manage`**, vê o mesmo formulário da criação com os valores atuais. O **SKU** fica bloqueado e diz **O SKU identifica este insumo e não pode ser alterado.** Clique em **Salvar alterações**; **Insumo salvo** confirma.
* **Caso contrário**, vê uma lista somente leitura: **SKU**, **Categoria**, **Unidade**, **Apresentação**, **Descrição**, **Criticidade**, as quatro opções de rastreabilidade como **Sim** ou **Não**, e **Custo** se você tem `catalog.cost.read`.
Abaixo dos dados, todas as pessoas veem:
1. **Status**, por exemplo **Status: Rascunho**, com **Somente insumos ativos podem ser adicionados a novos pedidos.**
2. **Apresentações**: como o insumo é comprado e recebido. Veja [Apresentações e códigos](/docs/pt/catalog/presentations-and-codes).
3. **Custo do insumo**, só para quem tem `catalog.manage` e `catalog.cost.read`. Veja [Custos](/docs/pt/catalog/costs).
### Ativar ou desativar
Vá até **Catálogo** e clique no nome do insumo.
Se o insumo não está ativo, a seção de status diz **A ativação permite solicitar este insumo e fixa sua unidade:** seguido da unidade. Se você mudou a unidade e ainda não salvou, diz **Salve ou descarte a alteração da unidade antes de ativar.**
O botão diz **Ativar e fixar unidade** quando a ativação também vai fixar a unidade, **Ativar insumo** quando a unidade já está fixa, e **Desativar insumo** quando o insumo está ativo.
## A unidade fica fixa
Estoque, pedidos e apresentações são contados na unidade base do insumo, então mudá-la depois do uso mudaria o significado das quantidades registradas. O muveya protege a unidade:
* A unidade fica fixa na primeira vez que o insumo é *ativado*, ou na primeira vez que estoque do insumo é *recebido*, mesmo que ele ainda seja um rascunho.
* Uma vez fixa, continua fixa, inclusive depois de desativar o insumo. O formulário mostra a unidade como texto com **Esta unidade está protegida e não pode ser alterada. Você pode editar os outros dados.**
* Todo o resto, exceto o SKU, continua editável: nome, descrição, categoria, apresentação (o texto livre), criticidade e as opções de rastreabilidade.
Enquanto a unidade não estiver fixa, você pode mudá-la e salvá-la junto com os outros campos. Antes de salvar, o formulário mostra **Alteração escolhida:** com a nova unidade e um botão **Descartar alteração da unidade**. Mudar a unidade tem consequências:
* Um custo registrado para a unidade anterior passa para `review_required` e precisa ser confirmado de novo. Veja [Custos](/docs/pt/catalog/costs).
* Uma apresentação publicada com a unidade anterior não serve para receber até que você a corrija, o que a publica novamente com a unidade atual.
Se a unidade não puder ser verificada ou tiver mudado nesse meio-tempo, o formulário avisa:
| Mensagem | O que fazer |
| - | - |
| **Verificando unidade…** | Aguarde um momento. |
| **A unidade não pode ser salva com as informações revisadas. Revise-a novamente ou descarte essa alteração para salvar os outros dados.** | Outra pessoa mudou ou fixou a unidade enquanto você editava. Revise a unidade atual ou clique em **Descartar alteração da unidade**. |
| **Não foi possível verificar se esta unidade pode ser alterada. Tente novamente ou salve os outros dados.** | Clique em **Tentar de novo**. |
| **A configuração da unidade precisa de revisão. Você pode editar os outros dados.** | Os dados salvos da unidade estão inconsistentes. Escreva para [team@muveya.com](mailto:team@muveya.com) com o SKU do insumo. |
| **Você não tem permissão para revisar esta unidade.** | Solicite `catalog.manage`. |
## Identificadores
| Identificador | Onde você vê | Para que serve |
| - | - | - |
| SKU | Em todo o console | O seu próprio código do insumo. É o que se usa para buscar e o que a importação CSV usa para detectar duplicados. |
| `itemId` | Na barra de endereços, `/catalog/items/:itemId` | O identificador interno permanente. A API e o MCP o usam, por exemplo `GET /v1/catalog/items/{itemId}`. |
| `categoryId` | Na tela de importação CSV | O identificador interno da categoria, necessário nos arquivos CSV. |
| Códigos da embalagem (GTIN, código do fornecedor e código interno) | Em **Apresentações** | Encontrar uma apresentação ao receber. Veja [Apresentações e códigos](/docs/pt/catalog/presentations-and-codes). |
O console sempre mostra nomes e nunca identificadores, exceto na tela de importação CSV, onde você precisa copiar os identificadores de categoria.
## Ler o catálogo fora do console
A API pública lê o catálogo com `GET /v1/catalog/items` e `GET /v1/catalog/items/{itemId}` (escopo `catalog:read`), e a ferramenta MCP `catalog.search` busca insumos por nome ou SKU (os ativos, por padrão). As duas são somente leitura: insumos são criados e editados apenas no console ou por uma importação CSV. Veja [API para desenvolvedores](/docs/pt/api-reference/introduction) e [Ferramentas MCP](/docs/pt/mcp/tools).
## O que o sistema registra
* O insumo, com status `draft`, ao ser criado.
* Quando a unidade fica fixa: quem a fixou e quando.
* As edições de campos e as mudanças de status atualizam o insumo. Na versão atual elas não são gravadas como entradas de auditoria separadas; as importações CSV, as exportações e as retiradas de códigos de embalagem são.
## O que pode dar errado
| Mensagem | Causa | O que fazer |
| - | - | - |
| **Preencha este campo.** | Falta um campo obrigatório. | Preencha-o. |
| **Use no máximo 64 caracteres.** (ou 200, 2000) | Um texto é longo demais. | Encurte-o. |
| **Use letras, números, pontos, sublinhados, barras ou hífens.** | O SKU tem espaços ou outros caracteres. | Remova-os. |
| **Escolha uma opção válida.** | Nenhuma categoria, unidade ou criticidade escolhida. | Escolha uma. |
| **Este SKU já existe. Use outro código.** | `catalog.sku_taken`: outro insumo tem esse SKU. | Use outro SKU ou abra o insumo existente. |
| **Esta categoria não está mais disponível. Escolha outra.** | `catalog.category_not_found`. | Escolha uma categoria da lista. |
| **A unidade mudou ou precisa de revisão. Revise a configuração atual antes de ativar.** | `catalog.measurement_conflict` ao ativar. | Recarregue o insumo, confira a unidade e ative de novo. |
| **Sua conta não tem permissão para esta ação.** | Você não tem `catalog.manage`. | Peça ajuda a um administrador da clínica odontológica. |
| **Este registro não está disponível na conta de clínica odontológica ativa.** | O insumo não existe na clínica odontológica em que você está trabalhando. | Confira a clínica odontológica ativa. |
| **Confira os dados informados antes de tentar novamente.** | O servidor recusou um valor. | Confira cada campo com a tabela acima. |
| **Este insumo não está ativo no catálogo.** | Aparece nos pedidos: o insumo está em rascunho ou inativo. | Ative o insumo. |
## Páginas relacionadas
Crie os grupos a que cada insumo pertence.
Descreva como um insumo é comprado e os códigos impressos nele.
Registre custos e controle quem pode vê-los.
Crie muitos insumos de uma vez a partir de um arquivo CSV.
Dê entrada de estoque de um insumo em um depósito.
Peça insumos ativos para uma unidade.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.