> ## 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.
# API para desenvolvedores
> O que a API pública do muveya cobre, sua URL base, as convenções que todas as respostas seguem e como esta referência está organizada.
A API pública do muveya é uma interface REST sob `/v1` para integrações no lado do servidor: um ERP ou sistema de compras, uma ferramenta de BI, uma planilha automatizada, um painel interno. Ela se autentica com uma **chave de API** que pertence a uma única clínica odontológica e lê os mesmos dados com que sua equipe trabalha no console.
A API é **somente leitura**, com uma exceção: `POST /v1/analytics/exports`, que pede ao muveya para gerar um arquivo CSV do resumo gerencial. Nada do que você chama em `/v1` cria, altera ou exclui um pedido, uma caixa, um movimento de estoque, um membro ou um insumo do catálogo.
## URL base
```text theme={null}
https://api.muveya.com
```
Todos os caminhos públicos começam com `/v1`, então sua primeira chamada é `https://api.muveya.com/v1/me`.
## Autenticação em uma linha
```bash theme={null}
curl https://api.muveya.com/v1/me \
-H "Authorization: Bearer $MUVEYA_API_KEY"
```
A chave é enviada como token bearer em cada requisição. O servidor a vincula a uma clínica odontológica: nenhum caminho, parâmetro ou cabeçalho indica uma clínica odontológica, então uma chave só consegue ler a sua. Veja [Autenticação](/docs/pt/api-reference/authentication) para saber como obter uma chave e protegê-la.
## Termos do console e termos da API
O console e a API descrevem as mesmas coisas com palavras diferentes. Tenha as duas em mente ao relacionar os dados da API com o que as pessoas veem na tela.
| No console | Na API |
| - | - |
| **Clínica odontológica** (seu espaço de trabalho) | O espaço de trabalho ao qual a chave pertence. `GET /v1/me` o retorna como `workspaceId`. Nunca aparece em um caminho. |
| **Unidades** | Unidades (`clinics`): `GET /v1/clinics`, `clinicId` |
| **Depósitos** | Depósitos (`warehouses`): `GET /v1/warehouses`, `warehouseId`. Um depósito `central` atende toda a clínica odontológica; um depósito `express` pertence a uma unidade. |
| **Catálogo** | Insumos e categorias do catálogo: `itemId`, `catalogItemId`, `categoryId` |
| **Inventário** | Caixas de estoque, seus saldos e seus movimentos no registro: `boxId`, `movementId` |
| **Pedidos** e **Aprovação de pedidos** | Pedidos, suas linhas e seu plano de aprovação: `orderId`, `lineId` |
| **Entregas** | Atendimentos (`fulfillments`) e histórico de custódia, identificados por `orderId` |
| **Relatórios** | Análises (`analytics`): métricas, exceções, consumo, resumo gerencial |
## O que `/v1` cobre
| Operação | Escopo | O que você recebe |
| - | - | - |
| `GET /v1/me` | Qualquer chave válida | A clínica odontológica (`workspaceId`), o `environment` da chave e seus `scopes` |
| `GET /v1/clinics` | `clinics:read` | Todas as unidades com nome e status |
| `GET /v1/warehouses` | `clinics:read` | Todos os depósitos com tipo (`central` ou `express`) e status |
| `GET /v1/catalog/items` | `catalog:read` | Todos os insumos do catálogo, qualquer que seja o status |
| `GET /v1/catalog/items/{itemId}` | `catalog:read` | Um insumo do catálogo |
| `GET /v1/catalog/categories` | `catalog:read` | Todas as categorias |
| `GET /v1/inventory/balances` | `inventory:read` | Quantidades em estoque (`onHand`), reservadas (`reserved`) e disponíveis (`available`) por caixa, paginadas e filtráveis por `catalogItemId` e `warehouseId` |
| `GET /v1/inventory/boxes/{boxId}` | `inventory:read` | Uma caixa: código, insumo, depósito, status, lote, números de série, validade, origem |
| `GET /v1/inventory/boxes/{boxId}/balance` | `inventory:read` | As quantidades de uma caixa |
| `GET /v1/inventory/boxes/{boxId}/movements` | `inventory:read` | Os movimentos de uma caixa no registro, do mais antigo para o mais recente |
| `GET /v1/orders` | `orders:read` | Pedidos, paginados e filtráveis por `status` |
| `GET /v1/orders/{orderId}` | `orders:read` | Um pedido com suas linhas e seu plano de aprovação |
| `GET /v1/fulfillments` | `fulfillment:read` | Registros de entrega, paginados e filtráveis por `status` |
| `GET /v1/fulfillments/{orderId}` | `fulfillment:read` | O histórico de custódia de um pedido: movimentos, entrega, recebimento e encerramento |
| `GET /v1/analytics/metrics/{metric}` | `analytics:read` | Uma métrica operacional com sua evidência |
| `GET /v1/analytics/exceptions` | `analytics:read` | Exceções operacionais, da maior para a menor prioridade |
| `GET /v1/analytics/clinics/comparison` | `analytics:read` | Unidades comparadas por volume de pedidos |
| `GET /v1/analytics/consumption-trend` | `analytics:read` | Consumo por insumo na sua própria unidade ao longo do tempo |
| `GET /v1/analytics/approval-backlog` | `analytics:read` | Aprovações pendentes agrupadas por tempo de espera |
| `GET /v1/analytics/cycle-time` | `analytics:read` | Duração média de cada etapa do pedido |
| `GET /v1/analytics/briefing` | `analytics:read` | O resumo gerencial diário ou semanal |
| `POST /v1/analytics/exports` | `analytics:read` | Pede uma exportação CSV do resumo gerencial (a única escrita) |
| `GET /v1/analytics/exports/{exportId}` | `analytics:read` | O estado de uma exportação e, quando pronta, seu link de download |
Cada escopo é explicado em [Escopos](/docs/pt/api-reference/scopes). A requisição e a resposta de cada operação estão documentadas no grupo **Endpoints** desta aba.
## O que `/v1` não faz
* Não cria nem altera nada na sua operação: pedidos, aprovações, separação, despacho, entrega, recebimento, recebimentos de estoque, consumo, transferências, correções, contagens, alterações de catálogo e mudanças na equipe são feitos no [console](/docs/pt/introduction), e algumas tarefas de estoque pelo [WhatsApp](/docs/pt/whatsapp/overview).
* Não cria nem revoga chaves de API. Veja [Autenticação](/docs/pt/api-reference/authentication).
* Não envia eventos para os seus sistemas. Ainda não há webhooks; veja [Webhooks](/docs/pt/api-reference/webhooks) para saber como consultar periodicamente.
* Nunca retorna totais de pedidos nem referências de pacientes (veja [Dados omitidos](#dados-omitidos)).
## Convenções
**JSON em tudo.** As respostas de sucesso são `application/json`. Os erros são documentos `application/problem+json` com um `code` estável (veja [Erros](/docs/pt/api-reference/errors)). Os nomes dos campos são em inglês, no formato camelCase, e os valores de enumerações são palavras em inglês em minúsculas, como `pending_approval`; as chaves de métricas são em maiúsculas, como `LOW_STOCK`. Nenhum deles muda com o idioma.
**Ids opacos.** Todo id é uma string. Compare ids como texto e nunca os interprete nem os construa. Um id que pertence a outra clínica odontológica se comporta exatamente como um id inexistente: a resposta é `404`.
**Ausente, não null.** Um campo opcional sem valor, ou que sua chave não pode ver, fica fora da resposta. Ele não é enviado como `null` nem como `0`. As exceções são três campos de análise: `value` (de uma métrica ou de um número do resumo) e `averageHours` (de uma etapa do tempo de ciclo) são `null` quando não houve amostra para medir, e `maxAgeHours` é `null` na faixa aberta do acúmulo de aprovações.
**Datas em UTC.** Datas e horários são strings ISO 8601 em UTC com o sufixo `Z`, por exemplo `2026-09-15T13:45:00.000Z`. Os relatórios de análise informam `"timezone": "UTC"`. As janelas de tempo que você envia (`from`, `to`) também são ISO 8601.
**Dinheiro em unidades menores.** Um valor monetário é um inteiro na unidade menor da sua moeda (centavos para USD) e sempre vem com `currency`, um código ISO 4217: `"cost": 1250, "currency": "USD"` significa 12,50 USD. Dinheiro aparece apenas nos campos de custo do catálogo e no `unitCost` das linhas de pedido, e só para uma chave com `catalog.cost:read`.
**Quantidades na unidade de medida do insumo.** Quantidades como `onHand`, `requestedQty` ou `quantityDelta` são inteiros contados na `unitOfMeasure` do insumo (`unit`, `box`, `milliliter` etc.). A API nunca soma quantidades de insumos ou unidades de medida diferentes.
**Idioma.** Envie `Accept-Language` com `en`, `es` ou `pt` (o inglês é o padrão). Ele muda apenas o texto destinado a pessoas: o `title` e o `detail` de um erro, a `label` de cada número do resumo gerencial e os rótulos dentro de uma exportação CSV. Chaves, códigos, valores de enumerações, números e ids são iguais em todos os idiomas.
**Ids de requisição.** Toda resposta traz o cabeçalho `x-request-id`. Se você enviar seu próprio `X-Request-Id` com um UUID, o muveya o reutiliza; caso contrário, gera um. Os corpos de erro o repetem como `requestId`. Registre-o no seu sistema e inclua-o quando escrever para [team@muveya.com](mailto:team@muveya.com).
**Listas.** Toda lista responde `{ "data": [...], "hasMore": false }`, mais `nextCursor` quando há outra página. Veja [Paginação](/docs/pt/api-reference/pagination).
**Limites de uso.** Cada chave tem seu próprio orçamento de requisições e cada resposta o informa em cabeçalhos. Veja [Limites de uso](/docs/pt/api-reference/rate-limits).
**Estabilidade.** Dentro de `/v1`, as mudanças são aditivas. Veja [Versionamento e estabilidade](/docs/pt/api-reference/versioning) e as [novidades](/docs/pt/changelog).
## Dados omitidos
O servidor remove os dados que sua chave não pode ver antes de montar a resposta. Os campos ficam ausentes, nunca mascarados.
| Dado | Quando `/v1` o retorna |
| - | - |
| `cost`, `currency`, `costStatus`, `costMeasurement` do catálogo | Só com `catalog.cost:read` |
| `unitCost` e `currency` das linhas de pedido | Só com `catalog.cost:read` |
| `value`, `currency` e `approvalPlan.evaluatedValue` do pedido | Nunca. Nenhum escopo da API dá acesso a valores de pedidos. |
| `patientRef` de um pedido clínico | Nunca. Nenhum escopo da API dá acesso a referências de pacientes. |
| Análises e exportações do resumo gerencial | Apenas contagens, quantidades e durações. Nunca custos, valores ou referências de pacientes. |
Uma chave de API não é um membro da equipe e não é limitada pelo acesso a unidades: ela lê **todas as unidades e depósitos** da sua clínica odontológica dentro dos seus escopos. Dê a cada chave apenas os escopos de que a integração precisa.
## Como esta referência está organizada
* **Visão geral** (estas páginas): autenticação, guia rápido, escopos, paginação, limites de uso, erros, versionamento, exportações e webhooks.
* **Endpoints**: uma página por operação, gerada a partir do contrato OpenAPI do muveya, no seu idioma. Cada página mostra os parâmetros, o esquema de resposta, os erros possíveis e exemplos de requisição em cURL, JavaScript e Python. O construtor de requisições dessas páginas apenas prepara uma requisição para você copiar: ele nunca a envia e nunca guarda sua chave.
O servidor MCP em `https://api.muveya.com/mcp` usa login e autorização com OAuth, para assistentes de IA. Veja [Servidor MCP](/docs/pt/mcp/introduction).
Obtenha uma chave, envie-a e mantenha-a no seu servidor.
Suas primeiras chamadas com cURL, JavaScript e Python.
O que cada escopo permite ler.
O documento de problema e todos os códigos de erro.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.