Loja Integrada MCP con Gemini CLI

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

Loja Integrada + Gemini

Gestisci un negozio Loja Integrada dalla tua AI: cerca prodotti, aggiorna stock e prezzi, crea prodotti, categorie e marchi, segui gli ordini, cambia lo stato degli ordini, aggiungi i codici di tracking e consulta i clienti. API v1 ufficiale.

Prerequisiti

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

LOJA_INTEGRADA_API_KEY, LOJA_INTEGRADA_APP_KEY

Step 1 — Ottieni le credenziali

La configurazione richiede circa 5 minuti una volta che hai entrambe le chiavi, ma la chiave di applicazione arriva in 5-10 giorni lavorativi. Ti servono un negozio Loja Integrada con un piano a pagamento, l'accesso al suo pannello e una chiave di applicazione (chave de aplicação) che Loja Integrada rilascia per l'integrazione.

1. Nel pannello del negozio apri Configurações → Chave para API, clicca Cadastrar nova chave e copia la chiave di 20 caratteri in LOJA_INTEGRADA_API_KEY. Incolla solo la chiave, senza chave_api. Le chiavi API sono disponibili solo nei piani a pagamento (guida di Loja Integrada).
2. Richiedi la chiave di applicazione (chave de aplicação) a Loja Integrada con il modulo per integratori descritto in questo articolo della guida. Nel modulo elenca gli indirizzi IP da cui partiranno le chiamate API: su un'installazione self-hosted l'indirizzo del tuo server, su AnythingMCP Cloud l'indirizzo IPv4 fisso 104.248.242.235, da cui Cloud fa ogni chiamata. Anche la pagina di setup del connettore mostra gli indirizzi in uscita. Loja Integrada risponde in 5-10 giorni lavorativi.
3. Inserisci la chiave di applicazione, un UUID come dc6049f0-1234-..., in LOJA_INTEGRADA_APP_KEY. Incolla solo la chiave, senza aplicacao.
4. Installa il connettore e verifica la connessione con loja_integrada_list_order_statuses.

La chiave di applicazione funziona solo dai suoi indirizzi IP: Loja Integrada rifiuta le chiamate da qualsiasi indirizzo non registrato con la chiave. Se l'indirizzo cambia (un nuovo server, il passaggio a Cloud o da Cloud), invia la nuova lista con lo stesso modulo prima di cambiare, così le chiamate non iniziano a fallire.

Cloud e self-hosting funzionano allo stesso modo: cambia solo l'indirizzo IP che registri con la chiave di applicazione.

Entrambe le chiavi viaggiano in un solo header: ogni chiamata invia Authorization: chave_api <API key> aplicacao <application key>; AnythingMCP lo compone dalle due variabili. Il login con Personal Token (Authorization: Basic ...) non è usato da questo connettore.

Limite di richieste: Loja Integrada consente 100 richieste al minuto per negozio e oltre risponde 429. Fai leggere le liste pagina per pagina invece di ripetere le chiamate; dopo un 429 aspetta un minuto.

Id e riferimenti: prodotti, categorie, marchi e clienti hanno id numerici (202591789); gli ordini si indicano con il loro numero (numero, ad esempio 164). I record si collegano tra loro con URI come /api/v1/categoria/15246059 (il campo resource_uri), che vanno così come sono in categorias, marca e pai di un prodotto. Con id_externo a 1, un prodotto o un prezzo si cerca con il tuo id esterno.

Paginazione, prezzi e date: le liste restituiscono 20 elementi per pagina di default, al massimo 50, e si sfogliano con limit e offset finché meta.next è null; meta.total_count è il totale. I prezzi sono in BRL e arrivano come stringhe tipo "32.83". I filtri per data accettano YYYY-MM-DD, con l'ora facoltativa.

Prodotti, varianti, stock e prezzi: un prodotto con varianti è un prodotto padre (tipo atributo) con un figlio per ogni variante (tipo atributo_opcao, con pai impostato sul padre); loja_integrada_list_grids e loja_integrada_get_grid mostrano i valori delle griglie di varianti, come taglie e colori. Prezzo e stock sono record separati, impostati dopo la creazione del prodotto. Lo stock è una quantità assoluta, non una differenza, e si imposta su ogni variante. Un aggiornamento sostituisce l'intero prodotto, quindi l'AI lo legge prima e reinvia ogni campo: i campi omessi possono essere svuotati.

Errori frequenti: 401 vuol dire che Loja Integrada ha rifiutato le chiavi: controlla LOJA_INTEGRADA_API_KEY, LOJA_INTEGRADA_APP_KEY e che la chiave di applicazione sia registrata per l'indirizzo IP del connettore. 403 vuol dire che le chiavi sono state lette ma l'accesso è stato negato: la chiamata è partita da un indirizzo non registrato con la chiave di applicazione. 429 è il limite di richieste.

Cosa legge: prodotti con SKU, tipo (semplice, padre con varianti o variante), categorie, marca, dimensioni e peso, NCM e GTIN, immagini e griglie di varianti; stock con quantità riservata e disponibile; prezzo di listino, promozionale e di costo; categorie, marchi e griglie di varianti con i loro valori; ordini con cliente, indirizzo di fatturazione e di consegna, righe, pagamenti, spedizioni con codice di tracking, stato e totali, più lo storico degli stati di ogni ordine e gli stati d'ordine e i metodi di pagamento del negozio; clienti con email, CPF o CNPJ, telefoni e indirizzi.

I tool di scrittura sono attivi all'installazione: nessun tool è disattivato. Il connettore crea prodotti, categorie e marchi, modifica prodotti, imposta stock e prezzi, sposta gli ordini in un altro stato e aggiunge codici di tracking, tutto nel negozio live; un cambio di stato può inviare un'email all'acquirente e uno stato finale come cancellato è definitivo. Disattiva nella pagina del connettore quelli che non ti servono; l'AI ti chiede conferma prima di ogni modifica.

Nulla viene cancellato: nessun tool cancella dati o crea ordini, e il connettore non gestisce immagini dei prodotti, coupon, SEO, webhook, fatture (NF), marketing né etichette di spedizione Enviali.

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 Gemini

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.

Gemini CLI legge i server MCP da ~/.gemini/settings.json (su Windows %USERPROFILE%\.gemini\settings.json). Aggiungi:

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "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 gemini.
3. Esegui /mcp in Gemini CLI (oppure gemini mcp list dal terminale): anythingmcp dovrebbe risultare connesso.
4. Inizia a scrivere prompt: Gemini CLI ora può chiamare i tool di Loja Integrada.

Tool disponibili

Esempi di prompt

• "Quante unità della SKU CAM-001 sono disponibili, e quali sono il prezzo di listino e quello promozionale?"
• "Mostrami gli ordini di questa settimana che aspettano ancora il pagamento."
• "Imposta il prezzo promozionale della SKU CAM-001 a R$ 89,90 e lo stock a 40 unità."
• "Segna l'ordine 164 come spedito e aggiungi il codice di tracking AA123456789BR."
• "Trova la cliente con l'email [email protected] ed elenca i suoi ordini."

FAQ

Dove cerca i server MCP Gemini CLI? In ~/.gemini/settings.json per il tuo utente, oppure in .gemini/settings.json dentro un progetto. gemini mcp list mostra ogni server e se si connette.

Prossimi passi

• Landing del connettore
• Collegare a Claude