Antes de empezar
- Una clave de API con los scopes
clinics:read,catalog:readyorders:read. Consulta Autenticación para saber cómo obtenerla. - Alguno de estos:
curl, Node.js 18 o superior (incluyefetch), o Python 3 con el paqueterequests(pip install requests). - Los ejemplos de JavaScript usan
awaiten el nivel superior: guárdalos en un archivo que termine en.mjs.
Pasos
1
Pon la clave en una variable de entorno
Nunca escribas la clave en tu código. Expórtala en la terminal (o cárgala desde tu gestor de secretos):Todos los ejemplos de abajo leen
MUVEYA_API_KEY y llaman a https://api.muveya.com.2
Identifica la clave
GET /v1/me no requiere scope. Te dice qué clínica dental lee la clave y qué scopes tiene.Respuesta
401 con api_keys.invalid significa que el encabezado o la clave están mal. Consulta Respuestas 401 y 403.3
Lista tus sedes
GET /v1/clinics (scope clinics:read) devuelve todas las sedes de la clínica dental en una sola página. GET /v1/warehouses funciona igual para las bodegas.Respuesta
clinicId a name: los pedidos y la analítica se refieren a las sedes por id.4
Lista los insumos del catálogo
GET /v1/catalog/items (scope catalog:read) devuelve todos los insumos del catálogo, sin importar su status, en una sola página.Respuesta
catalog.cost:read, así que los campos de costo no aparecen. Con ese scope, cada insumo también trae costStatus y, cuando hay un costo registrado, cost, currency y costMeasurement. Revisa costStatus antes de usar un importe: consulta Costos.5
Lee un pedido
Toma un El
orderId de GET /v1/orders y léelo con GET /v1/orders/{orderId} (scope orders:read). El detalle incluye las líneas y el plan de aprobación.Respuesta
value del pedido y el patientRef de un pedido clínico nunca se devuelven en /v1. Un pedido de otra clínica dental, o un id que no existe, responde 404 con el código orders.not_found.6
Recorre las páginas
GET /v1/orders está paginado. Pide hasta 200 pedidos por página y devuelve nextCursor como cursor mientras hasMore sea true. Envía los mismos filtros en cada página.Primera página
Maneja errores y límites
Dos hábitos hacen que una integración sea robusta desde el primer día:- Decide según
code, no según el texto. Todo error es un documento de problema con uncodeestable y unrequestId. Registra ambos. Consulta Errores. - Respeta el límite de uso. Cada clave tiene un presupuesto de solicitudes por minuto. Ante un
429, espera los segundos que indicaRetry-Aftery vuelve a intentarlo. Consulta Límites de uso.
Próximos pasos
Scopes
Recetas de mínimo privilegio para integraciones comunes.
Exportaciones del resumen gerencial
Pide un CSV, consulta su estado y verifica su checksum.
Webhooks
Recetas de consulta periódica para pedidos, entregas y existencias.
Servidor MCP
MCP usa un flujo separado de ingreso y autorización con OAuth.