Antes de começar
- Uma chave de API com os escopos
clinics:read,catalog:readeorders:read. Veja Autenticação para saber como obtê-la. - Um destes:
curl, Node.js 18 ou superior (que já incluifetch), ou Python 3 com o pacoterequests(pip install requests). - Os exemplos em JavaScript usam
awaitno nível superior: salve-os em um arquivo terminado em.mjs.
Passos
1
Coloque a chave em uma variável de ambiente
Nunca escreva a chave no seu código. Exporte-a no terminal (ou carregue-a do seu gerenciador de segredos):Todos os exemplos abaixo leem
MUVEYA_API_KEY e chamam https://api.muveya.com.2
Identifique a chave
GET /v1/me não exige escopo. Ela informa qual clínica odontológica a chave lê e quais escopos ela tem.Resposta
401 com api_keys.invalid significa que o cabeçalho ou a chave estão errados. Veja Respostas 401 e 403.3
Liste suas unidades
GET /v1/clinics (escopo clinics:read) retorna todas as unidades da clínica odontológica em uma única página. GET /v1/warehouses funciona do mesmo jeito para os depósitos.Resposta
clinicId para name: pedidos e análises se referem às unidades pelo id.4
Liste os insumos do catálogo
GET /v1/catalog/items (escopo catalog:read) retorna todos os insumos do catálogo, qualquer que seja o status, em uma única página.Resposta
catalog.cost:read, então os campos de custo ficam ausentes. Com esse escopo, cada insumo também traz costStatus e, quando há um custo registrado, cost, currency e costMeasurement. Confira costStatus antes de usar um valor: veja Custos.5
Leia um pedido
Pegue um O
orderId de GET /v1/orders e leia-o com GET /v1/orders/{orderId} (escopo orders:read). O detalhe inclui as linhas e o plano de aprovação.Resposta
value do pedido e o patientRef de um pedido clínico nunca são retornados em /v1. Um pedido de outra clínica odontológica, ou um id que não existe, responde 404 com o código orders.not_found.6
Percorra as páginas
GET /v1/orders é paginado. Peça até 200 pedidos por página e envie nextCursor de volta como cursor enquanto hasMore for true. Envie os mesmos filtros em todas as páginas.Primeira página
Trate erros e limites
Dois hábitos deixam uma integração robusta desde o primeiro dia:- Decida pelo
code, não pelo texto. Todo erro é um documento de problema com umcodeestável e umrequestId. Registre os dois. Veja Erros. - Respeite o limite de uso. Cada chave tem um orçamento de requisições por minuto. Diante de um
429, espere os segundos indicados emRetry-Aftere tente de novo. Veja Limites de uso.
Próximos passos
Escolha os escopos
Receitas de privilégio mínimo para integrações comuns.
Exporte o resumo gerencial
Peça um CSV, acompanhe o status e verifique o checksum.
Fique em dia sem webhooks
Receitas de consulta periódica para pedidos, entregas e estoque.
Conecte um assistente de IA
O MCP usa um fluxo separado de login e autorização com OAuth.