Skip to main content
Esta página te lleva desde una clave de API nueva hasta una lista paginada de pedidos. Todos los ejemplos se ejecutan en tu servidor, nunca en un navegador.

Antes de empezar

  • Una clave de API con los scopes clinics:read, catalog:read y orders:read. Consulta Autenticación para saber cómo obtenerla.
  • Alguno de estos: curl, Node.js 18 o superior (incluye fetch), o Python 3 con el paquete requests (pip install requests).
  • Los ejemplos de JavaScript usan await en 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
Un 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
Guarda una relación de 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
Esta clave no tiene 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 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
El 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
Los pedidos vienen del más antiguo al más reciente. El cursor es opaco: no lo decodifiques ni lo construyas. Consulta Paginación para ver todas las reglas.

Maneja errores y límites

Dos hábitos hacen que una integración sea robusta desde el primer día:
  1. Decide según code, no según el texto. Todo error es un documento de problema con un code estable y un requestId. Registra ambos. Consulta Errores.
  2. Respeta el límite de uso. Cada clave tiene un presupuesto de solicitudes por minuto. Ante un 429, espera los segundos que indica Retry-After y 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.