> ## 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.
# Custos
> Registre quanto custa um insumo, entenda os estados e o histórico do custo e controle quem pode vê-lo e como os pedidos o usam.
Cada insumo pode ter um custo vigente: um valor por unidade base, em uma moeda. Os custos são confidenciais. O servidor os remove de toda leitura, a menos que a pessoa tenha a permissão de custos, e cada alteração guarda o custo anterior em um histórico. Quando alguém adiciona o insumo a um pedido, a linha guarda uma cópia do custo vigente naquele momento.
## Quem pode fazer
| Ação | Permissão |
| - | - |
| Ver custos no console, nas exportações CSV e nas linhas de pedido | `catalog.cost.read` (**Ver custos dos materiais**) |
| Registrar um custo no console | `catalog.manage` *e* `catalog.cost.read` |
| Ler custos pela API pública | Uma chave de API com `catalog:read` *e* `catalog.cost:read` |
Nenhuma função inclui `catalog.cost.read`, nem mesmo Proprietário: ela é sempre concedida explicitamente, pessoa por pessoa. Tê-la não permite alterar custos nem unidades. Veja [Funções e permissões](/docs/pt/account/roles-and-permissions).
## Onde os custos aparecem
| Lugar | O que você vê |
| - | - |
| Lista de **Catálogo** | Uma coluna **Custo**, só com `catalog.cost.read`. |
| Detalhes do insumo, visão somente leitura | Uma linha **Custo**, só com `catalog.cost.read`. |
| Detalhes do insumo, seção **Custo do insumo** | O formulário para registrar um custo, só com `catalog.manage` e `catalog.cost.read`. |
| Importação CSV | Colunas opcionais `cost` e `currency`. Veja [Importar e exportar](/docs/pt/catalog/import-export). |
| Exportação CSV | Seis colunas de custo, só com `catalog.cost.read`. |
| Linhas de pedido | O custo copiado quando a linha foi adicionada, só com `catalog.cost.read`. |
## Valores, moedas e unidades menores
O muveya guarda cada valor como um número inteiro de *unidades menores* da moeda, como os centavos, junto com um código de moeda ISO 4217 de três letras maiúsculas. Assim os valores ficam exatos.
| O que você quer dizer | `cost` salvo | `currency` |
| - | - | - |
| USD 12,00 | `1200` | `USD` |
| USD 0,35 | `35` | `USD` |
| BRL 7,90 | `790` | `BRL` |
| CLP 1.200 | `1200` | `CLP` |
* **No console** você digita o valor em unidades normais: dígitos, opcionalmente seguidos de um ponto ou uma vírgula decimal e no máximo tantas casas decimais quanto a moeda usa (duas para USD e BRL, nenhuma para CLP). Não use separadores de milhares: `1250,50` é válido, `1.250,50` não. O console converte o valor para unidades menores de forma exata e nunca adivinha a moeda.
* **Em arquivos CSV e na API** o valor já está em unidades menores: um número inteiro como `1200`.
* `0` é um custo válido e é diferente de não ter custo. Valores negativos não são aceitos.
## Registrar um custo
Vá até **Catálogo** e clique no nome do insumo.
Ela fica no fim da página: **As alterações de custo são salvas separadamente e mantêm seu histórico.** A linha **Custo por** seguida da unidade, por exemplo **Custo por Caixa**, indica a qual unidade base o valor será aplicado.
Digite o **Valor** (**Escolha uma moeda e informe o valor sem separadores de milhares.**) e a **Moeda**, por exemplo `BRL`. Se o insumo já tem custo, os dois campos começam preenchidos com ele.
Clique em **Salvar custo**. **Custo salvo** confirma.
O que acontece ao salvar:
* O custo anterior, se houver, é fechado e fica no histórico.
* O novo valor passa a ser o custo vigente a partir daquele momento.
* O custo fica vinculado à unidade de medida do insumo como ela estava quando você a revisou. Se a unidade mudou nesse meio-tempo, nada é salvo e o formulário diz **A unidade revisada mudou. Confira a unidade atual antes de confirmar este valor.**, depois **Unidade atual:** com a unidade e um botão **Revisar custo para a unidade atual**. Clique nele, confira o valor e salve de novo.
O formulário de criação não tem campo de custo. Um insumo novo recebe o primeiro custo aqui ou por uma importação CSV.
Use uma única moeda para todos os insumos da sua clínica odontológica. O valor de um pedido soma apenas as linhas na moeda da sua primeira linha com custo; as linhas em outra moeda ficam fora do valor.
## Estados do custo
Toda leitura que inclui um custo também inclui `costStatus`. Confira o estado antes de usar o valor.
| `costStatus` | O que o console mostra | Significado | O que fazer |
| - | - | - | - |
| `unset` | **Não definido** | Nenhum custo foi registrado. Não é o mesmo que um custo igual a zero. | Registre um custo se quiser que os pedidos tenham valor. |
| `verified` | O valor e **Custo por** a unidade | O valor vale para a unidade de medida atual do insumo. | Nada. |
| `review_required` | O valor, **Registrado por** a unidade anterior e **Requer confirmação para a unidade atual.** | Existe um valor anterior, mas ele foi registrado para uma unidade que o insumo não tem mais, ou vem de dados antigos sem unidade. Não o multiplique por quantidades da unidade atual. | Salve o custo de novo em **Custo do insumo** para confirmá-lo para a unidade atual. |
| `invalid` | **Os dados anteriores do custo precisam de revisão.**, com o valor se ele pôde ser lido | Os dados salvos do custo estão inconsistentes. Eles nunca são convertidos em dinheiro nem tratados como ausentes. O formulário de custo fica desabilitado. | Escreva para [team@muveya.com](mailto:team@muveya.com) com o SKU do insumo. |
Um custo `review_required` costuma aparecer depois que alguém muda a unidade de medida do insumo enquanto ela ainda pode ser editada. Veja [Insumos do catálogo](/docs/pt/catalog/items#a-unidade-fica-fixa).
Onde ficaria um custo, podem aparecer outras duas mensagens:
* **A informação do custo não está disponível.**: você tem a permissão, mas o custo não pôde ser lido. Recarregue a página.
* **A unidade registrada não está disponível.**: o valor aparece, mas falta a unidade a que ele corresponde.
## Histórico do custo
Toda vez que um custo é substituído, o anterior é fechado e guardado com o valor, a moeda, o momento em que passou a valer, quem o registrou e a unidade a que correspondia. O histórico só cresce: nada nele é editado ou apagado.
A versão atual não tem tela, operação de API nem ferramenta MCP para consultar o histórico de custos. As linhas de pedido mantêm o custo que copiaram, então os pedidos antigos continuam mostrando o que foi pago na época.
## Omissão de dados: quem vê o quê
Os custos são removidos no servidor, não apenas escondidos na tela. Para uma pessoa sem `catalog.cost.read`:
* Os campos `cost`, `currency`, `costStatus` e `costMeasurement` não existem em nenhuma leitura do catálogo: o console, `GET /v1/catalog/items`, `GET /v1/catalog/items/{itemId}` e a ferramenta MCP `catalog.search`. Não existir significa não existir, nunca zero.
* Uma exportação CSV não traz as seis colunas de custo.
* As linhas de pedido não mostram a cópia do custo.
* Salvar um custo nunca devolve o valor na resposta.
O valor total do pedido depende de outra permissão, `orders.value.read`. Veja [Criar e acompanhar pedidos](/docs/pt/orders/create-and-track).
Assim fica um custo em uma leitura da API feita com uma chave que tem `catalog.cost:read`:
```json theme={null}
{
"itemId": "665f1a2b3c4d5e6f7a8b9c0d",
"sku": "GLV-NIT-M",
"name": "Nitrile gloves size M",
"categoryId": "665f1a2b3c4d5e6f7a8b9c01",
"unitOfMeasure": "pair",
"criticality": "high",
"tracksLot": true,
"tracksSerial": false,
"tracksExpiry": true,
"highValue": false,
"status": "active",
"costStatus": "review_required",
"cost": 1200,
"currency": "CLP",
"costMeasurement": {
"unitOfMeasure": "unit",
"measurementVersion": 1,
"quantityProtocol": "base_number_v1"
}
}
```
Aqui o valor foi registrado por `unit`, mas o insumo agora é contado em `pair`, então o valor precisa ser confirmado antes de valer. `costMeasurement` indica a unidade de medida, a versão dela e a regra de quantidade (`base_number_v1`, números inteiros da unidade base) para as quais o valor foi registrado.
## Como os pedidos usam o custo
Quando alguém adiciona um insumo a um pedido em rascunho, o muveya copia para a linha o custo vigente naquele momento, junto com o SKU, o nome, a unidade de medida, a categoria e a marca de alto valor.
| `costStatus` do insumo ao adicionar a linha | Resultado |
| - | - |
| `verified` | A linha guarda o valor e a moeda. |
| `unset` | A linha é adicionada sem custo e não soma nada ao valor do pedido. |
| `review_required` ou `invalid` | A linha é recusada com `catalog.cost_unverified`. A tela do pedido mostra **O registro mudou ou já existe. Confira antes de tentar novamente.** Confirme o custo no insumo e adicione a linha de novo. |
* Mudar o custo depois não altera as linhas já adicionadas.
* O valor do pedido é a soma do custo vezes a quantidade solicitada nas linhas que têm custo, na moeda da primeira delas.
* As regras de aprovação com valor mínimo ou máximo de pedido usam esse valor, então insumos sem custo não contam. Veja [Política de aprovação](/docs/pt/orders/approval-policy).
## O que o sistema registra
* O custo vigente, com a moeda, o momento em que passou a valer, quem o registrou e a unidade a que corresponde.
* Os custos anteriores fechados, no histórico.
* Em cada linha de pedido, o custo e a moeda copiados.
## O que pode dar errado
| Mensagem | Código | O que fazer |
| - | - | - |
| **Informe um valor exato, não negativo e sem separadores de milhares.** | | Remova separadores e casas decimais a mais. |
| **Use um código de moeda de três letras maiúsculas, como BRL.** | | Digite um código como `BRL`. |
| **Preencha este campo.** | | Informe um valor. |
| **A unidade revisada mudou. Confira a unidade atual antes de confirmar este valor.** | `catalog.measurement_conflict` | Clique em **Revisar custo para a unidade atual** e salve de novo. |
| **A alteração não foi confirmada. Tente novamente.** | `catalog.cost_clock_conflict` | O novo custo não recebeu um horário posterior ao do custo vigente. Salve de novo. |
| **Os dados anteriores do custo precisam de revisão.** | `catalog.cost_unverified` | O custo ou o histórico não podem ser usados com segurança. Escreva para [team@muveya.com](mailto:team@muveya.com). |
| **A configuração da unidade precisa de revisão. Você pode editar os outros dados.** | `catalog.measurement_unverified` | Escreva para [team@muveya.com](mailto:team@muveya.com) com o SKU. |
| **Sua conta não tem permissão para esta ação.** | `tenants.insufficient_role` | Solicite `catalog.manage`. |
| **Este registro não está disponível na conta de clínica odontológica ativa.** | `catalog.item_not_found` | Confira a clínica odontológica ativa. |
| **Falta um campo obrigatório.** (linha de importação CSV) | `catalog.cost_incomplete` | A linha tem custo sem moeda, ou moeda sem custo. Informe os dois ou nenhum. |
Nenhum desses erros aplica a alteração proposta. Confira as informações antes de tentar novamente.
## Páginas relacionadas
Insumos, unidades de medida e status.
Custos em arquivos CSV.
Onde aparecem as cópias do custo e o valor do pedido.
Regras de aprovação pelo valor do pedido.
Conceda **Ver custos dos materiais**.
`catalog:read` e `catalog.cost:read`.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.