Muro Box API abierta — Guía del usuario

Versión 1.0 (16 de agosto de 2026)

La API abierta de Muro Box permite que servicios de terceros y herramientas de automatización (por ejemplo, Home Assistant, IFTTT o sus propios scripts) controlen su Muro Box —reproducir canciones y listas de reproducción, detener la reproducción, ajustar la configuración y buscar en el catálogo de canciones/listas de reproducción— mediante una clave de API vinculada a su cuenta de Muro Box.

La API está diseñada en torno a la reproducción en su Muro Box: nunca devuelve archivos MIDI ni direcciones URL de descarga. Toda la reproducción se realiza en el propio dispositivo.


1. Inicio rápido

  1. Cree una clave API — Abra el Muro Box App → Configuración → Claves API → Añadir. Asigne un nombre a la clave y confirme. La clave completa se muestra solo una vez, justo después de crearla; cópiela y guárdela en un lugar seguro (no podrá recuperarla más adelante).
  2. Localice el número de serie de su dispositivo (device_sn) — aparece en la página de configuración del dispositivo de la aplicación correspondiente a su Muro Box emparejado.
  3. Realice una llamada a la API — envíe una solicitud POST con:
    • URL: https://api.murobox.com/muro_api/v1/... (véase el §3)
    • Encabezado: api-key: YOUR_API_KEY;your key>
    • Encabezado: Content-Type: application/json
    • Cuerpo JSON con los campos obligatorios

Descargue la colección de Postman e impórtela con un solo clic para iniciar las pruebas.

Ejemplo (reproducir una canción):

curl -X POST https://api.murobox.com/muro_api/v1/devices/play_song/ 
  -H "api-key: YOUR_API_KEY 
  -H "Content-Type: application/json" 
  -d '{"device_sn": "YOUR_BOX_SN", "song_id": "YOUR_SONG_ID"}'

Respuesta de ejemplo:

{"status": true, "message": "scuuess"}

Analice siempre el campo status para decidir si la operación se ha realizado correctamente; el texto message es meramente informativo.


2. Autenticación

Elemento Valor
Encabezado api-key
Valor su clave de API (32 caracteres hexadecimales, que se muestra una sola vez en el momento de su creación)
Pertenece a su cuenta de Muro Box; permite controlar las cajas emparejadas con dicha cuenta
  • Las claves se almacenan en el servidor únicamente como una huella SHA-256; la clave en texto plano no se puede recuperar una vez creada. Manténgala en secreto: cualquiera que tenga la clave puede controlar su Muro Box.
  • Puede crear varias claves (por ejemplo, una por servicio) y renombrarlas/eliminarlas desde la aplicación (Configuración → Claves de API).

Limitación de frecuencia

  • 60 solicitudes por minuto por clave de API. Al superarse el límite, recibirá una respuesta HTTP 429 con un encabezado Retry-After. Diseñe su automatización teniendo en cuenta este límite.

3. URL base y puntos de conexión

URL base: https://api.murobox.com

Todos los puntos de conexión utilizan POST + cuerpo JSON.

# Punto de conexión Finalidad Campos clave
1 /muro_api/v1/devices/play_song/ Reproducir una canción device_sn, song_id
2 /muro_api/v1/devices/play_playlist/ Reproducir una lista de reproducción device_sn, playlist_id
3 /muro_api/v1/devices/stop_playing/ Detener la reproducción device_sn
4 /muro_api/v1/devices/device_settings/ Leer/actualizar la configuración device_sn + al menos un ajuste
5 /muro_api/v1/search/songs/ Buscar canciones keyword, opcional page, lang
6 /muro_api/v1/search/packages/ Buscar listas de reproducción keyword, opcional page

Detalles del endpoint

4.1 Reproducir una canción — POST /muro_api/v1/devices/play_song/

{
  "device_sn": "YOUR_BOX_SN",
  "song_id": "YOUR_SONG_ID"
}
Campo Tipo Obligatorio Descripción
device_sn string Sí el número de serie de su Muro Box
song_id string Sí identificador de la canción (véase §6)

Éxito: 200 con {"status": true, "message": "scuuess"}. Errores: 400 campo faltante · 404 dispositivo o canción no encontrados · 403 no es un usuario de emparejamiento o no tiene permiso · 429 límite de solicitudes excedido.

4.2 Reproducir una lista de reproducción — POST /muro_api/v1/devices/play_playlist/

{
  "device_sn": "YOUR_BOX_SN",
  "playlist_id": "YOUR_PLAYLIST_ID"
}
Campo Tipo Obligatorio Descripción
device_sn string yes el número de serie de su Muro Box
playlist_id string yes identificador de la lista de reproducción (véase §6)

Filtrado de permisos: las canciones de la lista de reproducción se filtran según los permisos de su cuenta antes de enviarse a la caja, de modo que una lista de reproducción pública que contenga canciones privadas solo enviará las canciones que usted tenga permiso para reproducir:

  • Listas de reproducción públicas → canciones públicas + sus propias canciones
  • Sus listas de reproducción privadas → sus canciones + las canciones públicas de otros usuarios
  • Dispositivo / derechos de autor / listas de reproducción sin conexión → requieren que el dispositivo esté vinculado a usted

Correcto: 200 con {"status": true, "message": "scuuess"}. Errores: 400 campo faltante · 404 dispositivo o lista de reproducción no encontrados · 403 usuario no emparejado o sin permiso · 422 no hay ninguna canción reproducible en esta lista de reproducción (incluidas las listas de reproducción vacías) · 429 límite de solicitudes excedido.

4.3 Detener la reproducción — POST /muro_api/v1/devices/stop_playing/

{ "device_sn": "YOUR_BOX_SN" }

Correcto: 200 con {"status": true, "message": "scuuess"}. Errores: 400 · 404 · 403 · 429.

4.4 Configuración del dispositivo — POST /muro_api/v1/devices/device_settings/

{
  "device_sn": "YOUR_BOX_SN",
  "motorSpeed": 85,
  "plRandom": false,
  "plMaxTime": 10800,
  "midiPortEnabled": true,
  "bleMidiEnabled": true
}
Campo Tipo Rango / Valores Descripción
device_sn string — obligatorio; número de serie de su Muro Box
motorSpeed entero 50–120 (acotado) porcentaje de velocidad del motor
plRandom booleano true / false (también acepta "true"/"false", 1/0) reproducción aleatoria
plMaxTime entero 0–2147483647 segundos (acotado) tiempo máximo de reproducción
midiPortEnabled booleano true / false salida MIDI activada/desactivada
bleMidiEnabled booleano true / false MIDI por BLE activado/desactivado

Notas:

  • Se requiere al menos un campo de configuración (una llamada que incluya únicamente device_sn devuelve 400).
  • Solo se acepta el subconjunto anterior compatible con la automatización; este punto de conexión ignora los demás ajustes (nombre visible, DST, ajuste fino del motor, reproducción automática al encender, …).

Correcto: 200 con el subconjunto actualizado:

{
  "status": true,
  "data": {
    "motorSpeed": 85,
    "plRandom": false,
    "plMaxTime": 10800,
    "midiPortEnabled": true,
    "bleMidiEnabled": true
  }
}

Errores: 400 faltante device_sn / campo no válido / no hay nada que actualizar · 404 · 403 · 429.

4.5 Búsqueda de canciones —POST /muro_api/v1/search/songs/

{
  "keyword": "your keyword",
  "page": 1,
  "lang": "en"
}
Campo Tipo Obligatorio Descripción
keyword string Sí palabra clave de búsqueda
page integer No (predeterminado: 1) número de página, 10 resultados por página; las páginas fuera de rango devuelven una lista vacía
lang string No Idioma preferido de display_name, p. ej., en, zh-hant, zh-hans, ja, ko, de; omítalo para usar el nombre predeterminado

Correcto: 200

{
  "status": true,
  "data": [
    {
      "song_id": "8bad5d17bccc4b7b9fca727ce2390983",
      "display_name": "Your Song",
      "owner_name": "Artist Name",
      "code": "GI20",
      "visibility": "public"
    }
  ],
  "page": 1,
  "total_page": 3
}

Notas:

  • Nunca se devuelve una URL de archivo MIDI — la reproducción debe realizarse a través de play_song.
  • No existe un filtrado predeterminado por código de melodía; si su automatización requiere un tipo de melodía específico, filtre usted mismo por el campo code devuelto.
  • La visibilidad se devuelve como el campo visibility de tres estados (public / unlisted / private). El campo booleano heredado is_public ya no se incluye (eliminado el 17 de agosto de 2026).

Errores: 400 ausente keyword / page no válido · 429.

4.6 Buscar listas de reproducción — POST /muro_api/v1/search/packages/

{
  "keyword": "playlist keyword",
  "page": 1
}
Campo Tipo Obligatorio Descripción
keyword cadena sí palabra clave de búsqueda
page entero no (predeterminado: 1) número de página, 10 resultados por página; las páginas fuera de rango devuelven una lista vacía

Correcto: 200

{
  "status": true,
  "data": [
    {
      "package_id": "485029fa2d3e4fa9ae5db030079c95df",
      "package_name": "My Playlist",
      "owner_name": "Owner",
      "visibility": "public",
      "songs_count": 12
    }
  ],
  "page": 1,
  "total_page": 2
}

Notas:

  • Devuelve únicamente metadatos (sin la lista de canciones dentro de la lista de reproducción).
  • La visibilidad se devuelve como el campo visibility de tres estados. Los campos heredados is_publish y is_offline ya no se incluyen (eliminados el 17 de agosto de 2026; las listas de reproducción sin conexión están vinculadas a la cuenta virtual de la caja de música).
  • songs_count es el número de canciones que su cuenta puede reproducir (la misma regla que en la aplicación).
  • La reproducción debe realizarse a través de play_playlist.

Errores: 400 falta keyword / page no válido · 429.


5. Gestión de errores

Todos los fallos devuelven JSON con la misma estructura:

{ "status": false, "message": "..." }
HTTP Significado Cómo proceder
400 campo ausente o no válido verifique el cuerpo de la solicitud conforme al §4
404 no se encontró el dispositivo / la canción / la lista de reproducción verifique device_sn, song_id, playlist_id
403 no es un usuario emparejado o no tiene permiso La cuenta asociada a la clave debe estar vinculada al dispositivo; para las listas de reproducción, compruebe el filtrado de permisos (§4.2)
422 No hay ninguna canción reproducible en esta lista de reproducción. La lista de reproducción está vacía o no contiene ninguna canción que su cuenta pueda reproducir.
429 Se ha superado el límite de solicitudes. Respete el encabezado Retry-After; cuota de 60 solicitudes/min/clave

6. Obtención de song_id y playlist_id

  • Desde la aplicación (opción recomendada):
    • song_id — abra el reproductor de una canción → menú ⋯ → Copiar ID de la canción.
    • playlist_id — abra la página de detalles de una lista de reproducción → menú ⋯ → Copiar ID de la lista de reproducción (disponible para todos los tipos de lista de reproducción, incluidas las listas de reproducción sin conexión).
  • Desde la API: utilice los endpoints de búsqueda (§4.5 / §4.6) para buscar identificadores por palabra clave.

7. Colección de Postman

En open-api-postman-collection-prod.json está disponible una colección de Postman lista para importar:

  1. Postman → Importar → seleccione el archivo.
  2. En las variables de la colección, complete api_key y device_sn.
  3. Establezca song_id / playlist_id según sea necesario (conforme a lo indicado en el §6).
  4. base_url ya apunta al entorno de producción (https://api.murobox.com).

8. Notas de seguridad y operación

  • Trate su clave de API como una contraseña: solo se muestra una vez y no se puede recuperar.
  • Cada clave tiene su propio límite de solicitudes (60/min) y está sujeta a auditoría (el servidor registra las llamadas exitosas); revoque desde la aplicación las claves que ya no utilice.
  • La API solo activa la reproducción en las cajas de música vinculadas a su cuenta; no puede usarse para descargar canciones ni archivos MIDI.
  • Si prevé una automatización intensiva, manténgase dentro del límite de solicitudes por clave o cree varias claves con cuotas independientes.

 

Si encuentra algún problema de uso o desea solicitar nuevas funciones, contáctenos por correo electrónico en: support@xx.invalid

Equipo de Muro Box