Documentazione

Tre modi per inviare i tuoi ordini a Get5Stars: l'integrazione Shopify con un clic (consigliata per i merchant Shopify), l'API REST (per qualsiasi altro back office) o l'importazione CSV occasionale dalla tua dashboard.

• Shopify — installazione dalla dashboard e poi OAuth, nessuno sviluppatore necessario. Vedi Webhook Shopify.
• API REST — chiama POST /api/v1/orders/ingest a ogni nuovo ordine. Vedi API REST.
• Importazione CSV — carica un CSV da I miei clienti per inviare fino a 10.000 ordini in una volta.

URL di base: https://get5stars.app. Tutte le chiamate sono autenticate tramite l'header x-api-key (la tua chiave è visibile in Profilo → Chiave API). Limite: 100 richieste / minuto / chiave.

POST /api/v1/orders/ingest

Crea l'ordine e pianifica l'email iniziale + i due solleciti in base alla tua campagna. Idempotente su (merchantId, order_id).

curl -X POST https://get5stars.app/api/v1/orders/ingest \
  -H "x-api-key: $G5S_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ORD-2031",
    "customer_email": "alice@example.com",
    "customer_first_name": "Alice",
    "customer_last_name": "Dupont",
    "order_date": "2026-05-28T10:21:00Z",
    "customer_locale": "fr-FR"
  }'

Risposte

• 200 — { "order_id": "ORD-2031", "created": true }
• 200 — { "order_id": "ORD-2031", "created": false } (già acquisito, idempotente)
• 400 — payload non valido (Zod). Il body descrive il campo errato.
• 401 — chiave API mancante o account sospeso.
• 402 — quota mensile raggiunta (Starter 100 / Business 500). Su Scale, l'eccedenza è fatturata a +0,02 €.
• 429 — limite di frequenza superato (100/min/chiave).

Endpoint delle recensioni

Gli endpoint /api/v1/reviews/rate e /api/v1/reviews/submit alimentano il flusso di recensioni lato client. Di norma non devi chiamarli manualmente: sono usati dalla pagina pubblica di recensioni servita da Get5Stars.

Connettere e testare un'altra piattaforma

Per una piattaforma diversa da Shopify (WooCommerce, n8n, Zapier, codice personalizzato), invia i tuoi ordini a POST /api/v1/orders/ingest con la tua chiave API. Prima di scegliere un piano, verifica la connessione: invia una richiesta di test a POST /api/v1/ping (header x-api-key). Appena ricevuta, la tua piattaforma viene contrassegnata come connessa e puoi attivare il tuo abbonamento.

Dopo l'installazione OAuth dalla dashboard, Get5Stars registra automaticamente due webhook Shopify: orders/create (avvia la sequenza di recensioni) e app/uninstalled (cancellazione GDPR). Non devi configurare nulla manualmente.

• orders/create — ogni nuovo ordine Shopify viene convertito in un ordine Get5Stars. Firma HMAC verificata con il tuo SHOPIFY_API_SECRET.
• app/uninstalled — disinstallazione pulita: interrompiamo le email e avviamo la cancellazione dei dati entro 30 giorni.
• shop/redact + customers/redact + customers/data_request — endpoint GDPR obbligatori di Shopify. Implementati e testati.

Risoluzione dei problemi

• Un ordine non arriva? Controlla Shopify Admin → Settings → Notifications → Webhooks. orders/create deve puntare a https://get5stars.app/api/webhooks/shopify.
• Ricevi un 401? Il segreto HMAC è cambiato: reinstalla l'app dalla dashboard per aggiornare il token.

Get5Stars utilizza un LLM di terze parti (OpenRouter) per due funzionalità opzionali: l'estrazione di temi dalle recensioni negative (piano Business e superiori) e la stesura di bozze di risposta (piano Scale).

Dati inviati al LLM

• Temi: solo il testo delle recensioni ≤ 3★, sulla finestra scelta (7 giorni, 30 giorni o tutto lo storico). Nessuna email, nome o identificativo del cliente, né nome del negozio. Le chiamate sono incrementali: vengono inviate solo le nuove recensioni, i temi già calcolati fanno da contesto.
• Risposte IA: solo il testo della recensione, il voto e il nome del cliente (per la formula di saluto). Mai il nome del tuo negozio, né i dati di altre recensioni.

Fornitori

• OpenRouter (router multi-modello, San Francisco, USA). Modello primario: Llama 3.3 70B (Meta, gratuito, nessuna conservazione dei dati). Fallback: Gemini 2.5 Flash Lite (Google).
• Tutte le chiamate sono da server a server dai nostri worker nella regione CDG (Vercel).

Conservazione

• OpenRouter non conserva alcun prompt per impostazione predefinita sui modelli « free » e « no-retention » che utilizziamo.
• Le bozze IA generate sono archiviate nella tua dashboard (campo aiReply) fino all'eliminazione della recensione.

Disattivare

Nessuna estrazione di temi viene avviata finché non apri la scheda « Temi » nella dashboard. Le risposte IA vengono generate solo su richiesta, tramite il pulsante « Risposta IA » nel dettaglio di una recensione. Contatta il supporto per disattivare completamente gli LLM sul tuo account.