> ## 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.
# Apresentações e códigos
> Descreva as embalagens em que um insumo é comprado, vincule os códigos impressos nelas e corrija, mova ou retire ambos com segurança.
Uma *apresentação* é uma embalagem em que um insumo é comprado e recebido, como uma caixa com 100 luvas. Ela diz quantas unidades base do insumo contém, de modo que receber 3 caixas de 100 soma exatamente 300 unidades ao estoque.
Um *código* é um identificador impresso nessa embalagem: um código de barras (GTIN), uma referência do fornecedor ou um código que a sua clínica atribui. Quando alguém lê ou digita um código na tela de recebimento, o muveya encontra a apresentação e, por meio dela, o insumo e a quantidade.
Os códigos da embalagem dizem *o que* é um produto: todas as caixas do mesmo artigo trazem o mesmo código. Eles são diferentes dos códigos de caixa como `BX-000123`, que identificam *qual* recipiente físico está na prateleira. Os códigos de caixa são criados no recebimento do estoque. Veja [Caixas e etiquetas](/docs/pt/inventory/boxes).
O formulário do insumo tem um campo de texto livre chamado **Apresentação**. Esse campo é só uma descrição e nunca muda uma quantidade. Esta página trata da seção **Apresentações** dos detalhes do insumo, que é a usada para contar.
## O que está disponível
| Disponível na versão atual | Não disponível |
| - | - |
| Ver as apresentações de um insumo com seus códigos. | Embalagens aninhadas (uma caixa que contém caixas). Registre a embalagem externa como uma apresentação própria com o total de unidades base. |
| Adicionar, corrigir e retirar uma apresentação. | Reativar uma apresentação retirada. Publique uma nova no lugar. |
| Adicionar um código, movê-lo para outra apresentação do mesmo insumo e retirá-lo. | Editar o valor de um código. Retire-o e adicione o correto. |
| Ler códigos na tela de recebimento. | Apresentações ou códigos na importação ou exportação CSV. |
| | Apresentações ou códigos na API pública ou no MCP. |
## Quem pode fazer
| Ação | Permissão |
| - | - |
| Ver apresentações e códigos | `catalog.read` (todas as funções), `catalog.manage` ou `inventory.receive` |
| Adicionar, corrigir ou retirar uma apresentação; adicionar, mover ou retirar um código | `catalog.manage` |
Veja [Funções e permissões](/docs/pt/account/roles-and-permissions).
## Onde
Abra um insumo a partir de **Catálogo**. A seção **Apresentações** fica abaixo da seção de status, com a descrição **Como este insumo é comprado e recebido. Receber N de uma apresentação soma N × o seu conteúdo.**
Cada apresentação mostra:
* O nome, por exemplo "Caixa com 100".
* O conteúdo, por exemplo **Contém 100 × Unidade**.
* A versão e o status, por exemplo **Versão 2** e **Ativa** ou **Retirada**.
* Os botões **Corrigir** e **Retirar**, para quem gerencia o catálogo, nas apresentações ativas.
* Abaixo, **Códigos de** seguido do nome da apresentação, com os códigos ativos.
A lista mostra a versão atual de cada apresentação, inclusive as retiradas. Quando o insumo não tem nenhuma, mostra **Ainda não há apresentações** e, para quem gerencia o catálogo, **Adicione a embalagem que você compra, como uma caixa de 100, e o código impresso nela.** (as demais pessoas leem **Uma pessoa que gerencia o catálogo pode adicionar apresentações a este insumo.**).
## Adicionar uma apresentação
Em **Apresentações**, clique em **Adicionar apresentação**. O diálogo **Nova apresentação** abre.
Informe o **Nome da apresentação** como a sua equipe chama a embalagem, com até 120 caracteres.
Informe **Unidades base que contém**: um número inteiro de 1 a 1.000.000.000. A ajuda lembra a unidade de medida do insumo, por exemplo **Unidade base deste insumo: Unidade.**
Clique em **Publicar apresentação**. A lista mostra a nova apresentação e a tela anuncia que ela foi publicada como versão 1.
Você pode adicionar apresentações mesmo com o insumo ainda em rascunho. A apresentação guarda uma cópia da unidade de medida do insumo no momento da publicação.
### Exemplos
| Unidade de medida do insumo | Embalagem | Nome da apresentação | Unidades base que contém |
| - | - | - | - |
| **Unidade** | Caixa com 100 luvas | Caixa com 100 | `100` |
| **Unidade** | Fardo com 3 caixas de 100 luvas | Fardo 3 × 100 | `300` |
| **Mililitro** | Frasco de desinfetante de 500 ml | Frasco 500 ml | `500` |
| **Caixa** | Uma caixa contada como uma | Caixa | `1` |
Decimais não são aceitos: se uma embalagem traz meia unidade, escolha uma unidade base menor para o insumo antes que ela fique fixa.
## Corrigir uma apresentação
Uma correção nunca edita a apresentação salva. Ela publica a versão seguinte e mantém a anterior legível, porque as caixas recebidas com a versão 1 precisam continuar significando o mesmo.
Clique em **Corrigir** na apresentação. O diálogo **Corrigir** seguido do nome abre com os valores atuais e a nota **A correção publica a versão 3. As caixas já recebidas mantêm a versão com que foram recebidas.** (com o número da versão seguinte).
Edite **Nome da apresentação** ou **Unidades base que contém**.
Clique em **Publicar correção**. A tela anuncia a nova versão.
* Os códigos da apresentação continuam vinculados: eles pertencem à apresentação, não a uma versão.
* Uma correção também publica a apresentação de novo com a unidade de medida atual do insumo. Use-a se a unidade de medida mudou depois da publicação da apresentação.
* Se alguém estiver recebendo estoque com a apresentação enquanto você a corrige, a tela de recebimento para e mostra o novo conteúdo. Veja [Receber estoque](/docs/pt/inventory/receive).
## Retirar uma apresentação
Clique em **Retirar** na apresentação.
O diálogo pergunta **Retirar** seguido do nome e avisa **Não poderá mais ser recebida. As caixas e as movimentações já registradas mantêm as suas quantidades. Não é possível desfazer.** Clique em **Retirar apresentação**.
Retirar marca todas as versões da apresentação como **Retirada**. Ela continua na lista, sem **Corrigir** nem **Retirar**. Os códigos continuam visíveis para que você possa movê-los ou retirá-los; se alguém ler um código que ainda aponta para ela, o recebimento mostra **Esta apresentação está retirada e não aceita mais novas entradas.** Para continuar recebendo essa embalagem, adicione uma nova apresentação e mova os códigos para ela.
## Códigos
### Tipos de código
| Tipo | Rótulo | O que é | Formato |
| - | - | - | - |
| `supplier` | **Código do fornecedor** | A referência de catálogo do próprio fornecedor. O formulário escolhe este tipo por padrão. | De 1 a 64 caracteres. |
| `gtin` | **GTIN (código de barras)** | A família de códigos de barras impressa em embalagens comerciais e logísticas (EAN-13, UPC-A, ITF-14). | De 8 a 14 dígitos. |
| `internal` | **Código interno** | Um código que a sua clínica atribui e imprime. | De 1 a 64 caracteres. |
### Adicionar um código
Em **Códigos de** da apresentação, clique em **Adicionar código**. Só as apresentações ativas oferecem essa opção.
Escolha o **Tipo de código**, digite o **Código** (**Exatamente como impresso, com os zeros iniciais.**) e, se for útil, o **Emissor (opcional)**, por exemplo o nome do fornecedor, com até 120 caracteres.
Clique em **Adicionar código**. O código aparece na lista com o tipo e, se informado, **Emitido por** e o emissor.
Como o muveya lê um código:
* Espaços e hífens são ignorados e as letras são comparadas em maiúsculas. `7 501234 567890` e `7501234-567890` são o mesmo código. A lista continua mostrando o código como impresso.
* Um GTIN mantém os zeros iniciais. Sem espaços nem hífens, ele precisa ter de 8 a 14 dígitos; caso contrário, o formulário diz **Um GTIN tem de 8 a 14 dígitos.**
* O dígito verificador de um GTIN é conferido. Se não conferir, o código é salvo mesmo assim e marcado com **O dígito verificador não confere. Confirme o código impresso.** Etiquetas reais às vezes vêm erradas, e recusá-las impediria registrar o estoque que a clínica tem em mãos.
* Um código de um determinado tipo pode estar ativo em apenas uma apresentação de toda a sua clínica odontológica. Adicioná-lo a uma segunda apresentação falha com **Outra apresentação já usa este código. Retire-o ou mova-o lá primeiro.** Adicioná-lo de novo à mesma apresentação não muda nada.
* O mesmo valor pode existir com dois tipos diferentes, por exemplo como GTIN em uma apresentação e como código do fornecedor em outra. Ao ler esse valor, o recebimento pede uma escolha: **Este código corresponde a mais de uma apresentação. Escolha a que chegou.**
### Mover um código
Use quando um código foi vinculado à embalagem errada do mesmo insumo.
Clique em **Mover** ao lado do código. O diálogo **Mover código** explica **Escolha outra apresentação ativa deste insumo. O código deixa** a apresentação atual **na mesma etapa.**
Em **Mover para**, escolha uma apresentação (**Escolha uma apresentação**). Só aparecem outras apresentações ativas do mesmo insumo. Se não houver nenhuma, o diálogo diz **Primeiro adicione outra apresentação ativa deste insumo.**
Clique em **Mover código**. O código é movido com o valor impresso, o emissor e o aviso de dígito verificador.
Para levar um código a outro insumo, retire-o aqui e adicione-o a uma apresentação do outro insumo.
### Retirar um código
Clique em **Retirar** ao lado do código.
O diálogo avisa que o recebimento deixa de encontrar a apresentação por este código e que **Você pode adicioná-lo de novo depois.** Clique em **Retirar código**.
O código some da lista e as leituras não o encontram mais. O muveya guarda o código retirado, quem o retirou e quando, como evidência.
## Como o recebimento os usa
Em [Receber estoque](/docs/pt/inventory/receive), quem recebe lê ou digita um código. O muveya o procura nos três tipos:
| Resultado | O que quem recebe vê |
| - | - |
| Uma apresentação | O insumo e a apresentação são preenchidos. Receber N soma N × o conteúdo da apresentação. |
| Várias apresentações | Uma escolha entre elas. |
| Nenhuma apresentação | **Esse código ainda não está vinculado a um insumo. Abra o insumo no catálogo e adicione o código em Apresentações, ou escolha o insumo para recebê-lo sem código.** |
Os códigos só são vinculados a partir do catálogo, não da tela de recebimento.
## O que o sistema registra
* Cada versão de uma apresentação é guardada de forma permanente com o nome, o conteúdo, a unidade de medida que o insumo tinha no momento e quem a publicou. Uma caixa recebida por meio de uma apresentação registra com qual versão foi recebida.
* Retirar uma apresentação marca todas as versões como retiradas. Nenhuma quantidade já registrada muda.
* Cada código registra quem o adicionou. Retirar ou mover um código mantém o registro anterior com quem o retirou e quando, e grava uma entrada de auditoria, `catalog.identifier.retired`, que, quando o código é movido, também indica a apresentação de destino.
Internamente, uma apresentação tem um `presentationId` estável compartilhado por todas as versões e um número de `version`. O console nunca mostra esses identificadores.
## O que pode dar errado
| Mensagem | Código | O que fazer |
| - | - | - |
| **Outra apresentação já usa este código. Retire-o ou mova-o lá primeiro.** | `catalog.identifier_taken` | Encontre a apresentação que tem o código e retire-o ou mova-o. |
| **Outra pessoa corrigiu esta apresentação ao mesmo tempo. Revise a versão atual e aplique a alteração de novo.** | `catalog.presentation_version_conflict` | Feche o diálogo, confira a nova versão e corrija de novo se for preciso. |
| **Esta apresentação está retirada. Escolha uma ativa.** | `catalog.presentation_retired` | Use ou crie uma apresentação ativa. |
| **Este código não está mais nesta apresentação. Revise a lista.** | `catalog.identifier_not_found` | Outra pessoa o moveu ou retirou; atualize a página. |
| **Este código não é válido para o tipo escolhido.** | `catalog.identifier_invalid` | Confira o tipo; um GTIN precisa ter de 8 a 14 dígitos. |
| **O conteúdo deve ser um número inteiro de unidades base a partir de 1.** | `catalog.presentation_invalid_content` | Informe um número inteiro de 1 a 1.000.000.000. |
| **Esta apresentação não está disponível para este insumo.** | `catalog.presentation_not_found` | Atualize a página; a apresentação pertence a outro insumo ou não existe mais. |
| **Não foi possível carregar as apresentações.** | | Clique em **Tentar de novo**. |
| **Informe um número inteiro a partir de 1.** | | Corrija **Unidades base que contém**. |
| **Preencha este campo.** / **Use no máximo 120 caracteres.** | | Corrija o nome ou o emissor. |
| **Sua conta não tem permissão para esta ação.** | `tenants.insufficient_role` | Solicite `catalog.manage`. |
## Páginas relacionadas
Leia um código e receba embalagens em um depósito.
Defina a unidade base do insumo.
Os recipientes criados quando o estoque chega.
Quem pode gerenciar o catálogo.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.