bol.com MCP Server: ordini, offerte e spedizioni

💡 Nessuna installazione? Usa direttamente cloud.anythingmcp.com. Accedi, clicca su Connettori → bol.com, incolla le tue credenziali, crea una chiave API MCP e hai finito. Niente Docker, niente git clone, niente server locale.

bol.com

API Retailer di bol.com per venditori nel mercato olandese e belga: ordini, spedizioni con tracciamento, resi, inventario FBB, offerte con prezzo e stock, commissioni, contenuti del catalogo, offerte concorrenti, valutazioni, fatture e indicatori di performance. ID cliente e segreto.

Configurazione

La configurazione richiede circa 3 minuti. Hai bisogno di un account venditore bol.com (Vendere tramite bol) e accesso alle impostazioni API nel Dashboard venditore bol. Il connettore necessita di un ID cliente e di un segreto cliente per l'API Retailer.

1. Nel Dashboard venditore bol apri il tuo account, poi Instellingen → Diensten → API Instellingen (Impostazioni, Servizi, Impostazioni API). Salva un contatto tecnico se bol lo richiede.
2. Sotto Client credentials voor de Retailer API clicca su Aanmaken (Crea), dai un nome alla chiave e clicca su Toon secret (Mostra segreto).
3. Copia il client ID in BOL_CLIENT_ID e il secret in BOL_CLIENT_SECRET. Se il segreto viene perso, crea nuove credenziali.
4. Installa il connettore. Esegui bol_com_list_orders per controllare la connessione: restituisce i tuoi ordini aperti che spedisci tu stesso (FBR).

Cloud e self-hosted funzionano allo stesso modo: le credenziali sono le stesse, e non c'è nessun URL di reindirizzamento o indirizzo IP da registrare.

Autenticazione: il connettore scambia l'ID cliente e il segreto su https://login.bol.com/token (credenziali cliente) per un token bearer che dura circa 5 minuti, e lo riutilizza fino alla scadenza. Non richiede mai un nuovo token ad ogni chiamata, perché bol blocca gli indirizzi che sovraccaricano il suo servizio di login.

Da dove iniziare: bol_com_list_orders elenca gli ordini FBR aperti, i più recenti per primi; bol_com_get_order aggiunge i dettagli di spedizione e fatturazione del cliente e gli articoli. bol_com_list_offers elenca le tue offerte e bol_com_list_inventory mostra lo stock che bol tiene per te nei suoi magazzini (FBB).

Cosa legge: ordini, spedizioni con trasporto e tracciamento, resi con motivi e commenti dei clienti, stock FBB, offerte con prezzo, stock e disponibilità per paese, perché un'offerta non è in vendita, commissione per un prodotto a un prezzo, contenuti del catalogo bol per EAN, offerte concorrenti e chi ha la buy box, valutazioni stellari, visite e percentuale di buy box per offerta, indicatori di performance del venditore per settimana, e fatture (solo lettura).

Spedizione: bol_com_create_shipment conferma la spedizione di articoli che spedisci tu stesso, con il tuo corriere e codice di tracciamento. bol_com_add_track_and_trace aggiunge un codice mancante a una spedizione; non può cambiare un codice esistente.

Offerte: bol_com_create_offer e bol_com_update_offer creano offerte e cambiano prezzo, stock, adempimento, paesi o il flag in attesa. Un aggiornamento cambia solo i campi forniti, ma un array (prezzi bundle, paesi) sostituisce il vecchio interamente. Un 409 significa che qualcuno ha cambiato l'offerta contemporaneamente. I prezzi sono in EUR IVA inclusa, e lo stock è da 0 a 999.

Disattivato all'installazione: bol_com_cancel_order_item (annulla un articolo d'ordine che non puoi consegnare) e bol_com_delete_offer (elimina un'offerta). Un'annullamento non può essere annullato e conta contro il tuo punteggio venditore, e un'offerta eliminata scompare da bol immediatamente e non può essere ripristinata. Per mettere in pausa un'offerta, impostala in attesa con bol_com_update_offer invece. Attivale nella pagina del connettore solo se l'AI deve usarle; l'AI ti chiede di confermare ogni modifica. Spedizioni, tracciamento e creazione e aggiornamento delle offerte sono attivati.

Scritture asincrone: spedizioni, trasporti e cancellazioni rispondono con uno stato di processo invece di un risultato. bol_com_get_process_status (o bol_com_find_process_statuses per entità e tipo di evento) mostra quando è SUCCESS o FAILURE. bol mantiene gli stati di processo per un giorno. Le offerte sono sincrone.

Paging: gli elenchi di ordini, spedizioni, resi e inventario prendono page da 1 con 50 righe per pagina; una risposta vuota significa che non ci sono più pagine. Le offerte utilizzano un cursore: passa page.nextCursor fino a quando non è mancante.

Limiti di frequenza: bol li imposta per endpoint. L'elenco degli ordini e l'elenco delle spedizioni consentono 25 chiamate al minuto, resi e inventario 20 al minuto, fatture 24 al minuto; dettagli degli ordini 25 al secondo e offerte 25 a 50 al secondo. Un 429 porta un Retry-After in secondi; i valori live sono su api.bol.com/retailer/public/ratelimits.

Ids e formati: gli ID ordine possono contenere lettere (A4K8290LP0), gli EAN sono stringhe, le date sono YYYY-MM-DD e gli orari ISO 8601 con un offset. I campi non utilizzati vengono omessi, perché bol risponde 400 a stringhe vuote.

Errori comuni: gli errori arrivano come application/problem+json con title, detail e violations che nominano il campo. 400 di solito significa che un campo è mancante o vuoto. 429 è il limite di frequenza: aspetta il tempo di Retry-After.

Non coperto: gestione o registrazione dei resi (accettare un reso fa rimborsare il cliente da bol), acquisto di etichette di spedizione e qualsiasi cosa che muova denaro.

Prerequisiti: BOL_CLIENT_ID, BOL_CLIENT_SECRET

Installa il connettore localmente

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Apri http://localhost:3000/connectors/store, scegli bol.com e incolla le variabili d'ambiente elencate sotto Prerequisiti.

Strumenti disponibili

Esempi di richieste

• "Quali ordini aperti devono ancora essere spediti oggi, e ce ne sono alcuni con una richiesta di cancellazione?"
• "Mostra l'ordine A4K8290LP0 con l'indirizzo del cliente e gli articoli."
• "Quali delle mie offerte non sono in vendita, e perché?"
• "Chi ha la buy box su EAN 8712345678901, e a quale prezzo?"
• "Imposta il prezzo della mia offerta per EAN 8712345678901 a 24,95 e lo stock a 40."

Prossimi passi

• Collegati a Claude
• Collegati a ChatGPT