Collegare Billbee MCP a Microsoft Copilot

💡 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 + Microsoft Copilot

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 Microsoft Copilot

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.

Microsoft Copilot usa i server MCP tramite gli agenti creati in Copilot Studio: aggiungi AnythingMCP a un agente come strumento, poi pubblichi l'agente in Microsoft 365 Copilot e in Teams. Copilot Studio si collega dal cloud di Microsoft via Streamable HTTP, che AnythingMCP supporta.

1. In Copilot Studio apri il tuo agente (o creane uno), vai su Tools e scegli Add a tool → New tool → Model Context Protocol.
2. Inserisci un Server name (per esempio AnythingMCP), una Server description che dica cosa fa il connettore e il Server URL https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID. Copilot Studio usa la descrizione per decidere quando chiamare il server.
3. Come autenticazione scegli API key, imposta Type su Header e come nome dell'header X-API-Key, poi seleziona Create.
4. In Add tool scegli Create a new connection, incolla una chiave API MCP di AnythingMCP (MCP Servers → il tuo server → API keys) e seleziona Add to agent.
5. Provalo nel riquadro Test dell'agente: chiedi qualcosa che richiede i tool di Billbee.
6. Seleziona Publish, poi Channels → Microsoft 365 and Microsoft Teams, lascia selezionato Make agent available in Microsoft Copilot e scegli Add channel. See agent in Teams lo installa per te; in Microsoft 365 Copilot scrivi @ e scegli l'agente.

Preferisci un accesso per ogni utente? Al posto della chiave API scegli OAuth 2.0 → Dynamic discovery: ogni persona accede ad AnythingMCP la prima volta che l'agente lo chiama.

Usi il self-hosting? Usa l'indirizzo HTTPS pubblico della tua istanza al posto di https://cloud.anythingmcp.com. Copilot Studio si collega dal cloud di Microsoft, quindi localhost non funziona.

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

Per quale Copilot vale? Per Microsoft 365 Copilot in azienda, tramite gli agenti di Copilot Studio. L'app Microsoft Copilot per account personali non permette di aggiungere un proprio server MCP.

Cosa mi serve? Un account di lavoro con accesso a Copilot Studio (licenza o prova) per creare l'agente. Chi lo usa in Microsoft 365 Copilot o in Teams deve avere accesso all'agente: condividilo, oppure chiedi a un amministratore di pubblicarlo per l'organizzazione. Se la tua organizzazione applica criteri sui dati ai connettori di Power Platform, valgono anche per i server MCP.

L'agente non chiama i tool. Controlla che il nome dell'header sia esattamente X-API-Key e che la chiave appartenga allo stesso server MCP dell'URL, e scrivi una Server description precisa: Copilot Studio la usa per decidere quando chiamare il server. Dopo ogni modifica pubblica di nuovo l'agente; in una chat già aperta scrivi "start over" per passare alla nuova versione.

Prossimi passi

• Landing del connettore
• Collegare a Claude
• Collegare a ChatGPT
• Collegare a Cursor
• Collegare a Gemini
• Collegare a Meta Muse