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

  1. 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).
  2. Trovare il numero di serie del dispositivo (device_sn) — visualizzato nella pagina delle impostazioni del dispositivo dell'app relativa al Muro Box abbinato.
  3. Chiamare l'API — inviare una richiesta POST con:
    • 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

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 429 con un'intestazione Retry-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_sn restituisce 400).
  • 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 code restituito.
  • La visibilità è restituita nel campo visibility a tre stati (public / unlisted / private). Il campo booleano legacy is_public non è 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 legacy is_publish e is_offline non 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:

  1. Postman → Importa → selezionare il file.
  2. Nelle variabili della collezione, compilare api_key e device_sn.
  3. Impostare song_id / playlist_id come necessario (cfr. §6).
  4. base_url punta 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