Muro Box Open API — Guida per l'utente
Versione 1.0 (16 agosto 2026)
L'Open API di Muro Box consente a servizi di terze parti e strumenti di automazione (ad esempio Home Assistant, IFTTT o i Suoi script personali) di controllare il Suo Muro Box — riprodurre brani e playlist, interrompere la riproduzione, regolare le impostazioni e cercare nel catalogo di brani/playlist — utilizzando una chiave API collegata al Suo account Muro Box.
L'API è incentrata sulla riproduzione sul Suo Muro Box: non restituisce mai file MIDI né URL di download. Tutta la riproduzione avviene sul carillon.
1. Avvio rapido
- Creare una chiave API — Aprire Muro Box App → Impostazioni → Chiavi API → Aggiungi. Assegnare un nome alla chiave e confermare. La chiave completa viene mostrata una sola volta, subito dopo la creazione — copiarla e conservarla in un luogo sicuro (non sarà possibile recuperarla in seguito).
- Trovare il numero di serie del dispositivo (
device_sn) — visualizzato nella pagina delle impostazioni del dispositivo dell'app relativa al Muro Box abbinato. - Chiamare l'API — inviare una richiesta
POSTcon:- URL:
https://api.murobox.com/muro_api/v1/...(consultare §3) - Intestazione:
api-key: <your key> - Intestazione:
Content-Type: application/json - Corpo JSON con i campi obbligatori
- URL:
Scaricare la collezione Postman e importarla con un clic per iniziare a eseguire i test.
Esempio (riproduzione di un brano):
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"}'
Esempio di risposta:
{"status": true, "message": "scuuess"}
Analizzare sempre il campo status per determinare l’esito: il testo message ha valore puramente informativo.
2. Autenticazione
| Elemento | Valore |
|---|---|
| Intestazione | api-key |
| Valore | la Sua chiave API (32 caratteri esadecimali, mostrata una sola volta al momento della creazione) |
| Appartiene al | Suo account Muro Box; può controllare i carillon associati a tale account |
- Le chiavi sono memorizzate sul server esclusivamente sotto forma di impronta SHA-256; la chiave in chiaro non è recuperabile dopo la creazione. Mantenerla segreta — chiunque possieda la chiave può controllare il Suo Muro Box.
- È possibile creare più chiavi (ad esempio, una per ciascun servizio) e rinominarle/eliminarle dall’App (Impostazioni → Chiavi API).
Limitazione della frequenza
- 60 richieste al minuto per chiave API. Se il limite viene superato, si riceve una risposta HTTP
429con un'intestazioneRetry-After. Progetti la propria automazione tenendo conto di questo limite.
3. URL di base e endpoint
URL di base: https://api.murobox.com
Tutti gli endpoint utilizzano POST + corpo JSON.
| # | Endpoint | Scopo | Campi principali |
|---|---|---|---|
| 1 | /muro_api/v1/devices/play_song/ |
Riprodurre un singolo brano | device_sn, song_id |
| 2 | /muro_api/v1/devices/play_playlist/ |
Riprodurre una playlist | device_sn, playlist_id |
| 3 | /muro_api/v1/devices/stop_playing/ |
Interrompere la riproduzione | device_sn |
| 4 | /muro_api/v1/devices/device_settings/ |
Leggi/aggiorna le impostazioni | device_sn + almeno un'impostazione |
| 5 | /muro_api/v1/search/songs/ |
Cerca brani | keyword, opzionale page, lang |
| 6 | /muro_api/v1/search/packages/ |
Cerca playlist | keyword, opzionale page |
4. Dettagli degli endpoint
4.1 Riproduzione di un brano — POST /muro_api/v1/devices/play_song/
{
"device_sn": "YOUR_BOX_SN",
"song_id": "YOUR_SONG_ID"
}
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
device_sn |
string | Sì | il numero di serie del Suo Muro Box |
song_id |
string | Sì | identificatore del brano (vedere §6) |
Esito positivo: 200 con {"status": true, "message": "scuuess"}. Errori: 400 campo mancante · 404 dispositivo o brano non trovato · 403 utente non associato o senza permessi · 429 limite di richieste superato.
4.2 Riproduzione di una playlist — POST /muro_api/v1/devices/play_playlist/
{
"device_sn": "YOUR_BOX_SN",
"playlist_id": "YOUR_PLAYLIST_ID"
}
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
device_sn |
string | Sì | il numero di serie del Suo Muro Box |
playlist_id |
string | Sì | identificativo della playlist (vedi §6) |
Filtraggio dei permessi: i brani della playlist vengono filtrati in base ai permessi del Suo account prima di essere inviati al carillon; pertanto, una playlist pubblica che contiene brani privati invierà solo i brani che Lei è autorizzato a riprodurre:
- Playlist pubbliche → brani pubblici + i Suoi brani
- Le sue playlist private → i suoi brani + i brani pubblici di altri utenti
- Dispositivo / copyright / playlist offline → richiedono che il carillon sia associato a Lei
Esito positivo: 200 con {"status": true, "message": "scuuess"}. Errori: 400 campo mancante · 404 dispositivo o playlist non trovati · 403 utente non associato o permessi insufficienti · 422 nessun brano riproducibile in questa playlist (comprese le playlist vuote) · 429 limite di richieste raggiunto.
4.3 Interruzione della riproduzione — POST /muro_api/v1/devices/stop_playing/
{ "device_sn": "YOUR_BOX_SN" }
Esito positivo: 200 con {"status": true, "message": "scuuess"}. Errori: 400 · 404 · 403 · 429.
4.4 Impostazioni 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 | Intervallo / Valori | Descrizione |
|---|---|---|---|
device_sn |
stringa | — | obbligatorio; il numero di serie del Suo Muro Box |
motorSpeed |
Numero intero | 50–120 (limitato) | Percentuale della velocità del motore |
plRandom |
booleano | true / false(accetta anche"true"/"false",1/0) |
Riproduzione casuale |
plMaxTime |
Numero intero | 0–2147483647 secondi (valore limitato) | durata massima di riproduzione |
midiPortEnabled |
booleano | true / false |
Uscita MIDI attiva/disattiva |
bleMidiEnabled |
booleano | true / false |
BLE MIDI attivo/disattivo |
Note:
- È richiesto almeno un campo di impostazione (una chiamata con solo
device_snrestituisce400). - Viene accettato solo il sottoinsieme sopra indicato, compatibile con l'automazione; le altre impostazioni (nome visualizzato, ora legale (DST), regolazione fine del motore, riproduzione automatica all'accensione, …) sono ignorate da questo endpoint.
Successo: 200 con il sottoinsieme aggiornato:
{
"status": true,
"data": {
"motorSpeed": 85,
"plRandom": false,
"plMaxTime": 10800,
"midiPortEnabled": true,
"bleMidiEnabled": true
}
}
Errori: 400 mancante device_sn / campo non valido / nulla da aggiornare · 404 · 403 · 429.
4.5 Ricerca dei brani — POST /muro_api/v1/search/songs/
{
"keyword": "your keyword",
"page": 1,
"lang": "en"
}
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
keyword |
stringa | sì | parola chiave di ricerca |
page |
numero intero | no (predefinito 1) | numero di pagina, 10 risultati per pagina; le pagine fuori dall'intervallo restituiscono un elenco vuoto |
lang |
stringa | no | lingua preferita per display_name, ad es. en, zh-hant, zh-hans, ja, ko, de; ometta il valore per utilizzare il nome predefinito |
Successo: 200
{
"status": true,
"data": [
{
"song_id": "8bad5d17bccc4b7b9fca727ce2390983",
"display_name": "Your Song",
"owner_name": "Artist Name",
"code": "GI20",
"visibility": "public"
}
],
"page": 1,
"total_page": 3
}
Note:
- Nessun URL di un file MIDI viene mai restituito — la riproduzione deve avvenire tramite
play_song. - Non è previsto alcun filtro predefinito per il codice della melodia: se la Sua automazione richiede un tipo specifico di melodia, applichi autonomamente un filtro in base al campo
coderestituito. - La visibilità è restituita nel campo
visibilitya tre stati (public/unlisted/private). Il campo booleano legacyis_publicnon è più incluso (rimosso il 17 agosto 2026).
Errori: 400 mancante keyword / non valido page · 429.
4.6 Ricerca playlist — POST /muro_api/v1/search/packages/
{
"keyword": "playlist keyword",
"page": 1
}
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
keyword |
string | sì | parola chiave di ricerca |
page |
integer | no (valore predefinito 1) | numero di pagina, 10 risultati per pagina; le pagine fuori intervallo restituiscono un elenco vuoto |
Esito positivo: 200
{
"status": true,
"data": [
{
"package_id": "485029fa2d3e4fa9ae5db030079c95df",
"package_name": "My Playlist",
"owner_name": "Owner",
"visibility": "public",
"songs_count": 12
}
],
"page": 1,
"total_page": 2
}
Note:
- Restituisce solo i metadati (nessun elenco dei brani all'interno della playlist).
- La visibilità viene restituita nel campo a tre stati
visibility. I campi legacyis_publisheis_offlinenon sono più inclusi (rimossi il 17 agosto 2026; le playlist offline sono collegate all'account virtuale del carillon). songs_countè il numero di brani riproducibili con il Suo account (secondo la stessa regola dell'App).- La riproduzione deve avvenire tramite
play_playlist.
Errori: 400: manca keyword / page non valido · 429.
5. Gestione degli errori
In tutti i casi di errore viene restituito un JSON con la stessa struttura:
{ "status": false, "message": "..." }
| HTTP | Significato | Come gestirli |
|---|---|---|
| 400 | campo mancante o non valido | verificare il corpo della richiesta rispetto al §4 |
| 404 | dispositivo / brano / playlist non trovati | verificare device_sn, song_id, playlist_id |
| 403 | utente non autorizzato all'abbinamento oppure permessi insufficienti | L'account associato alla chiave deve essere abbinato al dispositivo; per le playlist, verificare il filtraggio dei permessi (§4.2) |
| 422 | Nessun brano riproducibile in questa playlist | La playlist è vuota o non contiene brani riproducibili con il Suo account |
| 429 | Limite di frequenza superato | Rispettare l'intestazione Retry-After; quota di 60 richieste/min/chiave |
6. Come ottenere song_id e playlist_id
- Dall'app (consigliato):
song_id— aprire il lettore di un brano →⋯menu → Copia ID brano.playlist_id— aprire la pagina dei dettagli di una playlist →⋯menu → Copia ID playlist (disponibile per tutti i tipi di playlist, incluse quelle offline).
- Dall’API: utilizzare gli endpoint di ricerca (§4.5 / §4.6) per cercare gli identificatori tramite parola chiave.
7. Collezione Postman
Una collezione Postman pronta per l'importazione è disponibile all'indirizzo open-api-postman-collection-prod.json:
- Postman → Importa → selezionare il file.
- Nelle variabili della collezione, compilare
api_keyedevice_sn. - Impostare
song_id/playlist_idcome necessario (cfr. §6). base_urlpunta già all'ambiente di produzione (https://api.murobox.com).
8. Note di sicurezza e operative
- Tratti la chiave API come una password: viene mostrata una sola volta e non può essere recuperata.
- Ogni chiave è soggetta a un limite di frequenza (60/min) ed è sottoposta ad audit (il server registra le chiamate riuscite); revochi dall'App le chiavi che non utilizza più.
- L'API attiva la riproduzione solo sui dispositivi Muro Box abbinati al Suo account; non può essere utilizzata per scaricare brani o file MIDI.
- Se intende automatizzare in modo intensivo, si mantenga entro il limite di frequenza previsto per chiave oppure crei più chiavi per quote indipendenti.
Qualora riscontrasse problemi di utilizzo o avesse richieste di nuove funzionalità, La invitiamo a contattarci via e-mail all'indirizzo: support@tevofy.com
Il team di Muro Box