Collegare bol.com MCP a Cursor: offerte e stock

💡 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 + Cursor

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

Prerequisiti

Consulta le istruzioni complete di configurazione integrate nel connettore (visibili nello store dell'app quando selezioni il connettore). Le variabili ambientali richieste per questo connettore sono:

BOL_CLIENT_ID, BOL_CLIENT_SECRET

Passo 1 — Ottieni le credenziali

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

1. Nel bol Seller Dashboard 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 segreto 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'è 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.

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, disponibilità di stock e paese, motivi per cui 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 prestazione 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 di sospensione. Un aggiornamento cambia solo i campi forniti, ma un array (prezzi bundle, paesi) sostituisce l'intero vecchio. Un 409 significa che qualcuno ha cambiato l'offerta nello stesso momento. I prezzi sono in EUR inclusa IVA 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 di venditore, e un'offerta eliminata scompare immediatamente da bol e non può essere ripristinata. Per mettere in pausa un'offerta, impostala in attesa con bol_com_update_offer. 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: le liste 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 usano un cursore: passa page.nextCursor fino a quando non è mancante.

Limiti di frequenza: bol li imposta per endpoint. La lista degli ordini e la lista 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.

Id e formati: gli ID degli ordini 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: attendi il tempo di Retry-After.

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

Passo 2 — Installa l'adattatore

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

Passo 3 — Aggiungi il connettore in Cursor

L'URL del tuo server: in AnythingMCP apri MCP Servers → il server su cui si trova questo connettore e copia il suo URL (https://cloud.anythingmcp.com/mcp/…). Usalo ovunque questa guida mostra YOUR_SERVER_ID.

Cursor legge i server MCP da ~/.cursor/mcp.json. Aggiungi questa voce:

{
  "mcpServers": {
    "anythingmcp": {
      "url": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Crea una chiave API MCP in AnythingMCP da MCP Servers → il tuo server → API keys e incollala al posto di YOUR_MCP_API_KEY.
2. Salva il file e riavvia Cursor.
3. Apri Cursor → Settings → MCP e verifica che anythingmcp sia elencato e connesso.
4. Inizia a chattare: l'agente ora può usare i tool di bol.com.

Strumenti disponibili

Esempi di prompt

• "Quali ordini aperti devono ancora essere spediti oggi, e ce ne sono alcuni con una richiesta di cancellazione?"
• "Mostrami 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."

FAQ

Può gestire resi o annullare ordini? Legge i resi ma non li gestisce o registra, perché accettare un reso fa sì che bol rimborsi il cliente. Annullare un articolo d'ordine è possibile con bol_com_cancel_order_item, che è disattivato all'installazione.

Funziona per vendite belghe e olandesi? Sì. Un account venditore copre entrambi i paesi; le offerte portano la loro disponibilità per paese, e bol_com_get_offer_not_for_sale_reasons spiega per paese perché un'offerta non è in vendita.

Cursor supporta server MCP personalizzati nel piano gratuito? Sì — MCP è disponibile nei piani Hobby, Pro e Business.

Prossimi passi

• Pagina di atterraggio del connettore
• Collegati a Claude