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
- 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).
- 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. - Realice una llamada a la API — envíe una solicitud
POSTcon:- 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
- URL:
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
429con un encabezadoRetry-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_sndevuelve400). - 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
codedevuelto. - La visibilidad se devuelve como el campo
visibilityde tres estados (public/unlisted/private). El campo booleano heredadois_publicya 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
visibilityde tres estados. Los campos heredadosis_publishyis_offlineya 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_countes 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:
- Postman → Importar → seleccione el archivo.
- En las variables de la colección, complete
api_keyydevice_sn. - Establezca
song_id/playlist_idsegún sea necesario (conforme a lo indicado en el §6). base_urlya 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