Collegare Billbee MCP a Claude: ordini e scorte

💡 Niente installazione? Vai direttamente su cloud.anythingmcp.com. Accedi, clicca Connectors → Billbee Order Management, inserisci le credenziali, genera una MCP API key e hai finito. Niente Docker, niente git clone, niente server locale.

Billbee + Claude

Fai lavorare la tua AI con Billbee: trova gli ordini di tutti i tuoi marketplace e shop, cerca gli articoli per SKU o EAN con prezzo e giacenza, controlla lo storico ordini di un cliente e gestisci gli ordini: imposta lo stato, aggiungi numeri di tracking, prenota etichette con i corrieri collegati a Billbee, aggiorna le giacenze, aggiungi tag, modifica i campi di ordini e articoli e crea fatture. Con API key, email di accesso e password API.

Prerequisiti

Le istruzioni di setup complete sono incluse nel connettore stesso (visibili nello store quando lo selezioni). Le variabili d'ambiente richieste sono:

BILLBEE_API_KEY, BILLBEE_LOGIN_EMAIL, BILLBEE_API_PASSWORD

Step 1 — Ottieni le credenziali

1. Accedi a Billbee e apri Einstellungen (Settings) → Billbee API. Nelle impostazioni generali di quella pagina attiva l'accesso API e imposta una password API. È una password separata, solo per l'API, non quella con cui accedi.
2. Richiedi una API key a Billbee: usa il loro modulo di richiesta API oppure scrivi a [email protected] descrivendo in breve cosa vuoi collegare (qui: la tua AI che legge gli ordini tramite AnythingMCP). Billbee ti invia la chiave.
3. Inserisci la chiave in BILLBEE_API_KEY, l'indirizzo email con cui accedi a Billbee in BILLBEE_LOGIN_EMAIL e la password API del passo 1 in BILLBEE_API_PASSWORD.
4. Installa il connettore. Non c'è nessun passaggio Authorize with Provider: ogni chiamata invia la API key nell'header X-Billbee-Api-Key, più email e password API come HTTP Basic auth.
5. Comincia con billbee_list_shipping_providers: non richiede parametri ed elenca i corrieri configurati nel tuo account. Se risponde, tutti e tre i valori funzionano.

Tre valori, tutti obbligatori: Billbee rifiuta una chiamata che porta solo la API key, oppure solo email e password API. Sul connettore devono essere impostati tutti e tre.

Restare connessi: non ci sono token da rinnovare, il connettore invia i tre valori a ogni chiamata. Se cambi la password API in Billbee o ricevi una nuova API key, aggiorna BILLBEE_API_PASSWORD o BILLBEE_API_KEY nella pagina del connettore.

Lettura e scrittura: 9 dei 17 strumenti leggono soltanto ordini, articoli, clienti, corrieri e magazzini. Gli altri 8 modificano il tuo account Billbee reale, e Billbee trasmette la maggior parte delle modifiche agli shop e ai marketplace collegati. Tutti i 17 sono attivi dopo l'installazione. Per un setup in sola lettura disattiva gli strumenti di scrittura nella pagina del connettore; puoi disattivare anche singoli strumenti di lettura, per esempio billbee_list_customers e billbee_get_customer_orders se l'AI non deve vedere i dati dei clienti.

Strumenti di scrittura:

• billbee_set_order_state imposta lo stato dell'ordine, per esempio 3 pagato, 4 spedito, 8 annullato o 13 imballato. Lo shop o il marketplace può inviare un'email all'acquirente.
• billbee_add_shipment_to_order registra un numero di tracking creato altrove; non crea etichette e non cambia lo stato. billbee_ship_order_with_label prenota un'etichetta reale, a pagamento, con un corriere collegato a Billbee (DHL, DPD, GLS, Deutsche Post e altri) sul tuo contratto; providerId e productId vengono da billbee_list_shipping_providers, e l'AI ti chiede conferma prima di prenotare.
• billbee_update_stock imposta la giacenza assoluta di un articolo per SKU, non una variazione; con più magazzini serve lo stockId di billbee_list_stocks. Billbee invia la nuova giacenza ai tuoi shop e marketplace.
• billbee_add_order_tags aggiunge tag a un ordine. billbee_update_order e billbee_update_product modificano solo i campi passati, con i nomi dei campi che restituiscono billbee_get_order e billbee_get_product, come SellerComment o Price.
• billbee_create_invoice crea la fattura di un ordine con il tuo modello di fattura, al massimo una volta per ordine ogni 5 minuti, e può restituire il PDF.

Gli strumenti di scrittura vogliono l'id interno dell'ordine Billbee, non il numero d'ordine dello shop: billbee_get_order_by_extref trova l'id a partire dal numero d'ordine del marketplace.

Ordini: billbee_list_orders filtra per data dell'ordine (minOrderDate, maxOrderDate) e per ultima modifica (modifiedAtMin, modifiedAtMax), con date in ISO 8601 come 2026-01-01. billbee_get_order restituisce l'ordine completo con righe, indirizzi, dati di pagamento e di spedizione a partire dall'id Billbee. billbee_get_order_by_extref trova un ordine con il numero d'ordine del marketplace o dello shop, per esempio un numero d'ordine Amazon o eBay. Gli stati degli ordini tornano come numeri.

Articoli e clienti: billbee_get_product cerca un articolo per id Billbee, oppure per SKU o EAN se lookupBy vale sku o ean, e restituisce prezzi e giacenza. billbee_list_products si può limitare agli articoli creati dopo una data (minCreatedAt). billbee_list_customers non ha una ricerca, quindi per trovare un cliente per nome bisogna scorrere l'elenco pagina per pagina; con l'id del cliente, billbee_get_customer_orders elenca i suoi ordini.

Pagine e limiti di frequenza: gli strumenti di elenco restituiscono fino a 250 righe per pagina (pageSize), con Page, TotalPages e TotalRows nella risposta, e l'AI chiede la page successiva fino all'ultima. Billbee consente 2 richieste al secondo per API key e utente e oltre risponde 429: aspetta un attimo e riprova. Billbee fa pagare l'uso dell'API oltre una quota gratuita, quindi intervalli di date stretti e modifiedAtMin sono meglio che rileggere tutto ogni volta.

Errori comuni: se Billbee rifiuta le credenziali, controlla che tutte e tre le variabili siano impostate, che l'accesso API sia attivo in Einstellungen → Billbee API e che BILLBEE_API_PASSWORD contenga la password API e non quella di accesso. 429 significa che è stato superato il limite di 2 richieste al secondo.

Il connettore non crea né elimina ordini, non crea né modifica clienti e non crea né elimina articoli.

Step 2 — Installa l'adapter

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

Step 3 — Aggiungi il connettore in Claude

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.

Percorso consigliato: funziona su claude.ai web senza toccare alcun file di configurazione.

1. In Claude apri Customize → Connectors.
2. Clicca + e poi Add custom connector.
3. Inserisci un nome, ad esempio Billbee, e l'URL del server MCP remoto https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID, poi clicca Add.
4. Clicca Connect e accedi ad AnythingMCP (OAuth) per consentire l'accesso.

Tutti i tool sotto compaiono nella tua chat: inizia a scrivere prompt.

Tool disponibili

Esempi di prompt

• "Quali ordini sono arrivati negli ultimi 7 giorni e quali non sono ancora stati spediti?"
• "Trova l'ordine con il numero d'ordine del marketplace 302-1234567-1234567 e mostrami le righe, l'indirizzo di consegna e i dati di pagamento."
• "Quanti pezzi dello SKU ABC-123 abbiamo in magazzino e qual è il prezzo di vendita?"
• "Elenca tutti gli ordini del cliente Billbee 4567 con data e totale, dal più recente."
• "Imposta l'ordine Amazon 302-1234567-1234567 come spedito e aggiungi il numero di tracking DHL 00340434161234567890."
• "Crea tramite Billbee un'etichetta DHL per l'ordine eBay 14-12688-90311 e poi la sua fattura."

FAQ

Funziona con Claude Code come con Claude Desktop? Sì, punta entrambi a https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID.

Prossimi passi

• Landing del connettore
• Collegare a ChatGPT
• Collegare a Cursor
• Collegare a Gemini
• Collegare a Meta Muse
• Collegare a Microsoft Copilot