API Lego per sviluppatori: dati dei set, prezzi dei negozi e MCP

Lego non mette a disposizione un’API pubblica per il suo catalogo né per i prezzi del suo negozio. Per portare dati Lego in un’app, in un foglio di calcolo o in un assistente di intelligenza artificiale bisogna affidarsi a servizi di terzi, e ognuno risponde a una domanda diversa. Rebrickable è il riferimento per pezzi e inventari, Brickset per schede dei set e collezioni, BrickLink per i prezzi del suo marketplace, nuovo e usato e Brickfact per le offerte attuali dei negozi, spedizione compresa, in nove Paesi. L’API e il server MCP di Brickfact non richiedono chiavi.

Qui API sta per Application Programming Interface, l’interfaccia con cui un programma legge i dati di un servizio. Se invece cercavi i set Lego con le api, come La fattoria delle api 21165 di Minecraft, trovi set e prezzi nel catalogo Lego. Questa guida spiega invece quale fonte usare per quale lavoro, mostra richieste testate sull’API JSON pubblica di Brickfact e illustra come collegare ChatGPT o un altro assistente tramite il Model Context Protocol (MCP). Gli esempi riguardano l’Italia e usano l’euro. Il servizio è gestito da Brickfact, quindi ne descriviamo i limiti con la stessa franchezza delle funzioni.

Quale API Lego fa al caso tuo?

Un inventario di pezzi, un prezzo consigliato, una vendita su un marketplace e un’offerta di un negozio sono quattro numeri diversi. Decidi prima quale serve al tuo progetto, poi scegli l’endpoint.

Non è una classifica, ma un elenco di strumenti per lavori diversi. Molti progetti finiscono per combinarne due: una fonte di catalogo per i pezzi e una di prezzi per gli acquisti. Leggi le condizioni di ogni servizio prima di iniziare, perché tutti e tre i servizi hanno regole proprie.

Rebrickable: pezzi, inventari e catalogo completo

L’API di Rebrickable copre i set ufficiali, i pezzi e le minifigure, oltre a colori, temi e inventari dei set. Gli utenti che hanno effettuato l’accesso possono anche leggere e modificare la propria collezione su Rebrickable. Ogni chiamata richiede una chiave API, che generi nelle impostazioni del profilo e invii nell’intestazione Authorization: key … o come parametro key.

La documentazione chiarisce che non ci sono prezzi di set o pezzi. Per avere l’intero catalogo, Rebrickable chiede di usare i file CSV scaricabili invece di scorrere l’API pagina per pagina. Un account può inviare in media una richiesta al secondo; chi va più veloce riceve errori HTTP 429.

Rebrickable è la scelta giusta per sapere quali pezzi contiene un set o in quali set compare un certo pezzo. Non ti dirà quanto costa un set in nessun negozio.

Brickset: schede dei set, collezioni e prezzi consigliati

L’API di Brickset, versione 3, restituisce schede dei set, temi e sottotemi, anni, istruzioni, recensioni e immagini aggiuntive. Con il login di un utente legge e aggiorna anche la sua collezione su Brickset. La chiave è obbligatoria e si richiede su Brickset dopo aver effettuato l’accesso.

Una chiave nuova consente 100 chiamate al giorno a getSets, abbastanza per i test. Per un progetto in produzione Brickset invita a chiedere un limite più alto, e la sua pagina sui servizi web vieta i siti che copiano Brickset. Le schede riportano il prezzo consigliato da Lego per Stati Uniti, Regno Unito, Canada e Germania, non per l’Italia. È un prezzo consigliato, non quello che i negozi chiedono oggi.

BrickLink: prezzi di mercato, nuovo o usato

L’API di BrickLink è pensata soprattutto per i venditori e dà accesso anche alla guida prezzi di BrickLink. Le richieste vengono firmate in stile OAuth 1.0, con chiave e segreto del consumer, e i token di accesso valgono solo per indirizzi IP fissi registrati. Da altri indirizzi l’accesso non funziona, il che esclude gran parte delle soluzioni nel browser o serverless.

La guida prezzi distingue tra le vendite degli ultimi sei mesi (guide_type=sold) e gli annunci attuali (stock), lo stato nuovo o usato, la regione e la valuta, e i suoi prezzi sono al netto dell’IVA. È la fonte giusta per sapere a quanto si vendono i set usati. Dove comprare oggi il set nuovo con consegna a casa è un’altra domanda.

Brickfact: le offerte attuali dei negozi in nove Paesi

L’API pubblica di Brickfact restituisce le offerte che Brickfact monitora presso i negozi: prezzo dell’articolo, spese di spedizione dichiarate e totale nella valuta del Paese di destinazione scelto. Copre la ricerca dei set, le caratteristiche, le offerte, i confronti, lo storico dei prezzi registrati nei negozi, la valutazione di un’offerta e i set simili. API JSON e server MCP usano la stessa logica, quindi il tuo codice e un assistente vedono gli stessi dati.

Questi endpoint in sola lettura non richiedono un account Brickfact né una chiave API. Questo non significa uso illimitato né la promessa di un servizio gratuito per sempre. È un servizio condiviso con un limite globale di richieste; nei momenti di picco risponde con HTTP 429 e un’intestazione Retry-After. Chiamalo da un server, uno script o un notebook: le richieste dal browser provenienti da altri siti vengono rifiutate con invalid_origin.

Il mercato è obbligatorio in ogni richiesta: stabilisce quali negozi contano e in quale valuta arrivano i prezzi. Gli altri Paesi vengono rifiutati invece di essere sostituiti da un Paese vicino. Il parametro facoltativo language cambia solo nomi ed etichette. Una richiesta per il mercato italiano con "language": "en" restituisce comunque euro, negozi italiani e un link alla pagina di confronto italiana.

La prima richiesta: set Lego fino a 50 € spedizione compresa

Questa richiesta cerca sul mercato italiano set di orchidee con un totale noto, spedizione compresa, non superiore a 50 €:

curl --fail --silent --show-error \
  'https://mcp.brickfact.com/api/v1/search' \
  --header 'Content-Type: application/json' \
  --data '{"market":"IT","query":"orchidea","price_basis":"delivered","max_price":50,"limit":3}'

Risposta abbreviata di un test del 30 ottobre 2026. I prezzi cambiano, quindi i tuoi valori saranno diversi:

{
  "market": "IT",
  "currency": "EUR",
  "price_basis": "delivered",
  "sets": [
    {
      "set_id": 10311,
      "name": "Orchidea",
      "theme": "Icons",
      "pieces": 608,
      "comparison_url": "https://brickfact.com/it-it/sets/lego-icons-orchidea-10311",
      "item_price": null,
      "total_price": 44.99,
      "rrp": 49.99
    }
  ],
  "page": 1,
  "total": 3
}

La ricerca accetta anche theme_ids, intervalli di numero di pezzi, età come "18+", filtri per set in uscita o già fuori produzione, ordinamento per prezzo, sconto o novità e pagine fino a 20 risultati. Gli identificativi dei temi arrivano da GET /api/v1/themes?market=IT&query=Star. Un campo sconosciuto restituisce HTTP 400 invece di essere ignorato, così un errore di battitura non allarga la ricerca a tua insaputa.

La stessa ricerca in Python, con un budget di 40 €, richiede solo la libreria standard:

import json
import urllib.request

payload = {
    "market": "IT",
    "query": "orchidea",
    "price_basis": "delivered",
    "max_price": 40,
    "limit": 5,
}
request = urllib.request.Request(
    "https://mcp.brickfact.com/api/v1/search",
    data=json.dumps(payload).encode(),
    headers={"Content-Type": "application/json"},
)
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)

for item in result["sets"]:
    print(item["set_id"], item["name"], item["total_price"], result["currency"])

Le offerte di un set, con le spese di spedizione

Per le offerte di un singolo set usa l’endpoint delle offerte con il numero del set:

curl --fail --silent --show-error \
  'https://mcp.brickfact.com/api/v1/sets/10311/offers?market=IT&price_basis=delivered'

Ogni offerta contiene item_price, shipping, total, currency, feed_updated_at e stock_status. Le offerte con totale noto vengono prima, e la risposta aggiunge lowest_known_total e lowest_item_price. Quando Brickfact non conosce le spese di spedizione di un negozio, shipping e total valgono null. Leggilo come sconosciuto, mai come gratuito.

stock_status vale sempre not_verified. Un prezzo in un feed non dimostra che il set sia disponibile, e la spedizione indicata vale per un singolo set. Soglie per la spedizione gratuita, codici sconto e regole del carrello possono cambiare l’importo finale; fa fede solo il checkout del negozio.

Il dettaglio di un set (GET /api/v1/sets/10311?market=IT) aggiunge il prezzo consigliato, l’età indicata, il numero di minifigure, le dimensioni e una data stimata di fine produzione. Per confrontare da due a quattro set invia POST /api/v1/compare con una lista in set_ids.

Prezzo dell’articolo o prezzo con spedizione?

Per impostazione predefinita price_basis vale "item". In questa modalità budget e ordinamento usano solo il prezzo del set, item_price è compilato e total_price resta null. Un set da 45 € con 6,99 € di spedizione rientra così in un budget di 50 €, anche se consegnato a casa ti costa di più.

Con "delivered" Brickfact usa il totale comprensivo della spedizione dichiarata verso il mercato scelto. Le offerte con spedizione sconosciuta vengono scartate prima del filtro di prezzo, del conteggio e della paginazione: total e ogni pagina includono solo set con un totale noto, senza buchi tra le pagine. Il rovescio della medaglia è che un negozio che non dichiara le spese di spedizione sparisce del tutto da questi risultati.

Per acquistare, il prezzo con spedizione è di solito la scelta più onesta. Un prezzo basso in un negozio estero smette spesso di essere un affare quando si aggiunge la spedizione verso l’Italia, ed è per questo che i collezionisti tendono a confrontare i prezzi spedizione inclusa. Usa la modalità articolo per le viste di catalogo in cui la spedizione non conta.

Due tipi di storico dei prezzi

Brickfact tiene due storici distinti, e confonderli porta a risposte sbagliate.

Lo storico dei prezzi nei negozi (POST /api/v1/retail-history, strumento MCP get_retail_price_history) registra ogni giorno il prezzo più basso noto con spedizione presso i negozi monitorati di un mercato, nella sua valuta. Amazon è escluso, così come i giorni con spedizione sconosciuta o stimata. I giorni passati vengono calcolati con le regole di spedizione attuali per il Paese. La risposta indica observation_days e first_observed_day. Questa serie è iniziata solo il 12 ottobre 2026: chiedere un periodo lungo non garantisce uno storico lungo. Controlla la copertura prima di trarre conclusioni.

Lo storico del valore di mercato (GET /api/v1/sets/75192/history?market=IT&range=1Y, strumento MCP get_price_history) è un’altra serie: le valutazioni dei set sigillati in euro. Mostra quanto vale un set sigillato nel tempo; il nostro studio sull’investimento in Lego usa valutazioni di questo tipo per i set ancora in collezione. Anche se chiedi GB, US o CH resta in euro, e non è uno storico dei prezzi praticati dai negozi.

La valutazione dell’offerta (POST /api/v1/assess-deal, strumento MCP assess_deal) confronta l’offerta attuale più conveniente con spedizione, da un feed non più vecchio di 48 ore, con il minimo registrato nei negozi. Risponde at_or_below_recorded_low o above_recorded_low, con la differenza in percentuale. Senza almeno due giorni registrati o con uno storico più vecchio di 48 ore risponde insufficient_history, e senza un’offerta utilizzabile no_delivered_offer. L’offerta attuale può arrivare da Amazon anche se lo storico lo esclude. Un risultato al minimo registrato non è un minimo storico assoluto e non dice nulla sul prezzo del mese prossimo.

Collegare ChatGPT o un altro assistente tramite MCP

Il Model Context Protocol è uno standard aperto per collegare le applicazioni di IA a sistemi esterni. Invece di scrivere tu le richieste, lasci che l’assistente scopra gli strumenti di Brickfact e li chiami quando la tua domanda richiede dati aggiornati.

Per ChatGPT, la guida di collegamento di OpenAI descrive il percorso attuale: apri ChatGPT Plugins, seleziona il pulsante «+» e poi Add custom MCP server, indica nome e descrizione, inserisci l’URL con /mcp, scegli nessuna autenticazione, conferma l’avviso sui rischi e seleziona Create as a plugin. Valgono le regole del tuo account e del tuo spazio di lavoro; in azienda è l’amministratore a decidere se i server MCP personalizzati siano consentiti. La presenza nella directory pubblica dei plugin di ChatGPT richiede una revisione separata da parte di OpenAI; cerca Brickfact nella directory prima di dare per scontato che ci sia.

Gli altri client che supportano server remoti via Streamable HTTP si collegano con lo stesso URL. I client locali che supportano solo stdio hanno bisogno di un bridge.

Gli undici strumenti:

Cosa chiedere all’assistente per gli acquisti

Il server chiede all’assistente di riprendere il Paese d’acquisto dalla conversazione e di chiederlo se manca, quindi indicalo subito. Questi prompt coprono gli strumenti principali:

• «Trova set Lego Star Wars sotto i 100 € spedizione compresa in Italia e mostrali come schede.»
• «Aiutami a scegliere un regalo Lego fino a 60 € spedizione compresa in Italia per un bambino di 10 anni a cui piacciono le auto.»
• «Confronta i set Lego 10311 e 10313 con consegna in Italia, con numero di pezzi e prezzo con spedizione.»
• «Il prezzo attuale del set Lego 75192 in Italia è buono rispetto ai prezzi registrati nei negozi? Dimmi su quanti giorni di dati ti basi.»
• «Trova alternative più economiche al set Lego 75192 con consegna in Italia.»

Gli host compatibili con MCP Apps mostrano schede dei set con immagini, un confronto affiancato e grafici dello storico dei prezzi nei negozi. Altrove l’assistente risponde in forma testuale con gli stessi dati. Se l’host consente alle app di salvare uno stato, la scheda può conservare una selezione fino a sei numeri di set. Quella selezione appartiene alla scheda nella conversazione, non a un account Brickfact, e in una nuova chat potrebbe non esserci.

Cosa non può fare l’assistente

Il server MCP legge solo dati pubblici del catalogo. Non può comprare nulla, non chiede dati di pagamento, non vede la tua collezione Brickfact e non modifica il tuo account. Se gli chiedi di avvisarti quando il set Lego 10311 scende sotto i 30 €, ricevi un rimando all’app con "created": false: un link all’app Brickfact e le istruzioni per creare lì l’avviso. Non viene creato nulla finché non confermi nell’app. Se ti interessano gli sconti del momento, la nostra pagina delle offerte Lego li raccoglie.

I prezzi di una risposta non sono mai più aggiornati del feed da cui arrivano. Una buona offerta può esaurirsi pochi minuti dopo un ribasso: apri il link di confronto restituito e controlla il negozio prima di comprare.

Buone pratiche per l’integrazione

Alcune abitudini mantengono corretta un’integrazione quando i dati cambiano:

• Parti da un set e un mercato, e controlla valuta e price_basis in ogni risposta prima di aggiungere altri Paesi.
• Mostra una spedizione null come sconosciuta, senza sostituirla con zero.
• Indica feed_updated_at o l’ora della tua richiesta accanto ai prezzi.
• Tratta i risultati vuoti e gli storici brevi come risposte normali, non come errori.
• Metti in cache le risposte per qualche minuto, rispetta Retry-After e non scorrere l’intero catalogo attraverso le pagine di ricerca.
• Usa il campo comparison_url restituito invece di costruire da solo gli indirizzi delle pagine dei set.

Gli schemi di input di tutti gli endpoint sono pubblicati sull’endpoint pubblico degli schemi. Se preferisci confrontare i prezzi a mano, il catalogo Lego mostra le stesse offerte con filtri, e come confrontiamo i prezzi spiega quali negozi monitoriamo.

Un’API per programmare hub e motori Lego riguarda la robotica, non i dati: la nostra guida per programmare un robot Lego tratta SPIKE, Mindstorms e Python con Pybricks. Brickfact è indipendente dal Gruppo Lego.